aidlc-testagent

Purpose Mục đích

aidlc-testagent solves a specific problem: writing and maintaining E2E tests takes too long. This tool acts as an agent that automates the entire test lifecycle — from exploring the UI, planning test cases, generating code, running tests, to self-healing when tests fail. The end goal is a committable test suite in your repo, not a temporary output.

aidlc-testagent giải quyết một vấn đề cụ thể: viết và duy trì E2E test tốn thời gian. Tool này đóng vai trò một agent tự động hóa toàn bộ vòng đời test — từ khám phá giao diện, lên kế hoạch, sinh code, chạy thử, đến tự sửa khi test fail. Mục tiêu cuối là có một test suite có thể commit vào repo, không phải chỉ là output tạm thời.

Supported surfaces: web apps (Playwright), Electron desktop apps, REST APIs, and mobile (roadmap).

Phạm vi áp dụng: web app (Playwright), Electron desktop app, REST API, và mobile (roadmap).

What's new in v0.6.0 — a manual explore mode with an in-browser toolbar (checkpoints with screenshot previews, use-case recording → auto-generated markdown docs, live XHR/fetch monitoring, and HAR capture per use case), plus @playwright/mcp integration so the agent drives the browser through the Playwright MCP server. Requires Node ≥ 20.

Mới ở v0.6.0 — manual explore mode với toolbar ngay trong trình duyệt (checkpoint kèm screenshot preview, ghi use case → tự sinh markdown docs, theo dõi XHR/fetch trực tiếp, và bắt HAR theo từng use case), cùng tích hợp @playwright/mcp để agent điều khiển trình duyệt qua Playwright MCP server. Yêu cầu Node ≥ 20.

Architecture Kiến trúc

The system is organized into three layers: a CLI entry point, a core reasoning engine with pluggable modules, and surface adapters. The core never imports Playwright or Appium directly — it only talks to the TestAdapter interface.

Hệ thống chia thành ba lớp: CLI entry point, core reasoning engine với các module có thể thay thế, và surface adapter. Core không bao giờ import Playwright hay Appium trực tiếp — chỉ giao tiếp qua interface TestAdapter.

Entry point Điểm vào

CLI — npx ata

config · plan · run · validate

Core — Orchestrator Core — Orchestrator

Orchestrator

Drives the 6-step pipeline · manages state · computes final verdict

Điều phối 6 bước pipeline · quản lý state · tính verdict cuối

Cost Meter

USD budget guard per run

Giới hạn chi phí USD mỗi run

Core modules Các module core

Planner

Grounding + trust-ordered context → test plan

Grounding + context ưu tiên → test plan

Generator

Plan → Playwright specs + Page Objects

Executor

Stability gate · session reuse

Stability gate · tái sử dụng session

Healer

Re-observe → re-generate → retry loop

Re-observe → re-generate → vòng lặp retry

Shared services Dịch vụ dùng chung

LLM Provider

Delegates to local CLI (e.g. claude). No API keys in repo.

Gọi qua local CLI (vd. claude). Không có API key trong repo.

Perception · Playwright MCP

PerceptionSnapshot via @playwright/mcp — accessibility tree, element list, endpoints; auto + manual explore

PerceptionSnapshot qua @playwright/mcp — accessibility tree, element list, endpoint; explore tự động + thủ công

Config Loader

testagent.config.yaml + targets/*.target.yaml → Zod-validated

testagent.config.yaml + targets/*.target.yaml → Zod validate

Surface adapters (TestAdapter interface) Surface adapter (interface TestAdapter)

playwright-web

Phase 1 · Web apps

Phase 1 · Web app

playwright-electron

Phase 1 · Desktop apps

Phase 1 · Desktop app

REST API

Phase 2 · roadmap

iOS / Android

Phase 4+ · roadmap

Pipeline Pipeline

Six sequential steps. The Confirm step is the only human-in-the-loop checkpoint — the pipeline pauses here when autoApprove: false.

Sáu bước tuần tự. Bước Confirm là human-in-the-loop checkpoint duy nhất — pipeline dừng ở đây khi autoApprove: false.

Explore Explore

observe target

quan sát target

→

Plan Plan

LLM → test plan

→

Confirm ✓ Confirm ✓

human gate

duyệt bởi người

→

Generate Generate

specs + POMs

→

Execute Execute

stability gate

→

Heal Heal

re-observe · retry

→

Verdict Verdict

pass / fail

Explore — Adapter navigates to the target (autonomously, or driven by you in manual mode), observes accessibility tree + DOM → PerceptionSnapshot. The snapshot persists to perception.json and is reused across runs without reopening the browser.
Plan — LLM receives snapshot + trust-ordered grounding context → structured test plan with stages: setup → smoke → core → edge → teardown.
Confirm — Terminal shows the plan for human approval (Y/n). Only proceeds after explicit sign-off.
Generate — Approved plan → Playwright specs + Page Object Models, Zod-validated before write.
Execute — Tests run N times through the stability gate. Flaky tests are quarantined, never committed.
Heal — Failures trigger re-observation + LLM regeneration. Retries up to maxHealAttempts.
Explore — Adapter điều hướng đến target (tự động, hoặc do bạn điều khiển ở manual mode), quan sát accessibility tree + DOM → PerceptionSnapshot. Snapshot được lưu vào perception.json và tái sử dụng giữa các run mà không cần mở lại browser.
Plan — LLM nhận snapshot + grounding context theo thứ tự ưu tiên → test plan có cấu trúc: setup → smoke → core → edge → teardown.
Confirm — Terminal hiện plan để duyệt (Y/n). Chỉ tiếp tục sau khi được approve.
Generate — Plan đã duyệt → Playwright specs + Page Object Models, Zod-validated trước khi ghi.
Execute — Test chạy N lần qua stability gate. Test flaky bị quarantine, không commit.
Heal — Fail → re-observe + LLM regenerate. Retry tối đa maxHealAttempts lần.

Manual Explore Mode · new in v0.6.0 Manual Explore Mode · mới ở v0.6.0

Autonomous exploration doesn't always reach the screen you care about — behind a login, a multi-step wizard, a feature flag. Manual mode hands you the keyboard: you drive a real headed browser to the exact state you want, and an in-browser toolbar records it as grounded context the planner can trust.

Explore tự động không phải lúc nào cũng tới được màn hình bạn cần — sau login, qua wizard nhiều bước, hay sau feature flag. Manual mode trao quyền điều khiển cho bạn: bạn tự lái một headed browser tới đúng trạng thái mong muốn, và toolbar ngay trong trình duyệt ghi lại nó thành grounding context mà planner tin cậy.

npx ata explore myapp --manual --headed

Toolbar actionHành động trên toolbar	What it capturesGhi lại gì
Checkpoint	Snapshots the current DOM + accessibility tree with a screenshot preview, so the planner sees the exact state you reached. Chụp DOM + accessibility tree hiện tại kèm screenshot preview, để planner thấy đúng trạng thái bạn đã tới.
Record use case	Records a named flow of your actions and auto-generates a markdown doc describing the steps — committable grounding for the plan. Ghi lại một flow có tên từ thao tác của bạn và tự sinh markdown doc mô tả các bước — grounding có thể commit cho plan.
Network monitor	Live XHR/fetch call log surfaces the endpoints each screen depends on, feeding the API surface map. Log XHR/fetch trực tiếp cho thấy endpoint mỗi màn hình phụ thuộc, bổ sung cho API surface map.
HAR capture	Writes a HAR file per recorded use case — a complete network trace for debugging and replay. Ghi một file HAR cho mỗi use case — network trace đầy đủ để debug và replay.

AI Techniques Kỹ thuật AI

TechniqueKỹ thuật	What it doesVai trò
Structured Perception	Adapter normalizes DOM into an accessibility tree + element list (`PerceptionSnapshot`) rather than feeding raw HTML to the LLM. Reduces hallucination. Adapter chuẩn hóa DOM thành accessibility tree + element list (`PerceptionSnapshot`) thay vì đưa raw HTML vào LLM. Giảm hallucination.
Browser Control via MCP	Perception and exploration run through `@playwright/mcp` — the agent observes and drives the browser over the Playwright MCP server instead of hand-rolled scripting. Perception và exploration chạy qua `@playwright/mcp` — agent quan sát và điều khiển browser qua Playwright MCP server thay vì script thủ công.
Trust-Ordered Grounding	Planner loads context in strict priority: requirements → manual tests → business rules → source code. Human intent always outranks implementation. Planner nạp context theo thứ tự cứng: requirements → manual tests → business rules → source code. Ý định con người luôn thắng implementation.
LLM Delegation via CLI	Core never calls a model API directly — delegates through a local CLI (e.g. `claude`). No API keys in the repo. Core không gọi model API trực tiếp — delegate qua local CLI (vd. `claude`). Không có API key trong repo.
Structured Output (Zod)	All LLM output (plans, generated code) is validated against Zod schemas before use. If parsing fails, the pipeline stops — no silent failures. Mọi output từ LLM (plan, code) được validate qua Zod schema trước khi dùng. Nếu không parse được, pipeline dừng — không có silent failure.
Self-Healing Loop	On test failure: re-observe target → send error context to LLM → regenerate test → retry. Up to `maxHealAttempts`. Khi test fail: re-observe target → gửi error context cho LLM → regenerate → retry. Tối đa `maxHealAttempts` lần.
Stability Gate	Each new test runs N consecutive times before acceptance. All N must pass. Flaky tests are quarantined and never committed to the suite. Mỗi test mới chạy N lần liên tiếp trước khi accept. Tất cả N lần phải pass. Test flaky bị quarantine, không commit vào suite.
Cost Metering	Every LLM call is metered in USD. Runs abort automatically when the configured budget is exceeded. Mọi LLM call được đo chi phí bằng USD. Run tự động abort khi vượt budget đã cấu hình.

Behavior when applied Behavior khi apply

First run Chạy lần đầu

npx playwright install chromium     # One-time browser setup
npx ata config                      # Interactive setup: LLM provider, budget
npx ata explore myapp --manual --headed   # Optional: drive the browser yourself, record use cases
npx ata plan todomvc                # Propose plan only, no code generated
npx ata run todomvc                 # Full loop: explore → plan → [confirm] → generate → execute (+stability) → heal

When npx ata run executes, the agent opens a browser, navigates to the configured URL (or reuses a saved perception.json), generates a PerceptionSnapshot, asks the LLM to plan, pauses for your approval, then generates Playwright spec files and runs them through the stability gate. If any fail, the healing loop kicks in automatically. Each run leaves behind a committable tests/ directory plus perception.json (session reuse), a human-readable plan.md and machine plan.json, and per-use-case HAR network logs.

Khi npx ata run chạy, agent mở browser, navigate đến URL trong config (hoặc tái dùng perception.json đã lưu), sinh PerceptionSnapshot, hỏi LLM để lên plan, dừng chờ bạn duyệt, sau đó sinh Playwright spec files và chạy qua stability gate. Nếu có fail, healing loop tự động chạy. Mỗi run để lại thư mục tests/ có thể commit cùng perception.json (tái dùng session), plan.md cho người đọc và plan.json cho máy, và HAR network log theo từng use case.

CI Gate

npx ata validate        # Run all targets, exit 0 if all pass verdict

Plug into your CI pipeline to block merges when the test suite doesn't pass verdict thresholds (minScenarios, mustPass, stability).

Cắm vào CI pipeline để block merge khi test suite không đạt verdict threshold (minScenarios, mustPass, stability).

Safety guardrails Bảo vệ an toàn

Production hosts refused by default — staging only unless explicitly allowlisted
Private targets in .targets/private/ (gitignored)
Credentials from env vars, never YAML
Action guardrails block dangerous verbs: delete, pay, remove
Production host bị từ chối mặc định — chỉ staging trừ khi allowlist rõ ràng
Private targets trong .targets/private/ (gitignored)
Credentials từ env vars, không bao giờ trong YAML
Action guardrail chặn verb nguy hiểm: delete, pay, remove

Configuration Cấu hình

File structure Cấu trúc file

testagent.config.yaml        # Global: LLM provider, budget, stability runs
targets/
  todomvc.target.yaml        # Per-target: URL, auth, grounding, success criteria
  .targets/private/          # Gitignored private targets

Example target Ví dụ target config

name: todomvc
adapter: playwright-web
url: https://todomvc.com/examples/react
auth:
  strategy: none
grounding:
  requirements: docs/requirements.md
  manualTests:  docs/manual-tests.md
scope:
  include: ["todo list", "add item", "complete item"]
successCriteria:
  minScenarios: 5
  mustPass: ["add a todo item", "complete a todo item"]

Roadmap

Phase 1 (current) — Web + Electron, reliability core (auth, stability gate, cost guard, healing, scope, CLI)
Phase 2 — REST API adapter + traceability report
Phase 3 — --diff mode (test only changed code) + Claude Code skill / MCP packaging
Phase 4+ — iOS, Android, vision fallback, policy engine
Phase 1 (hiện tại) — Web + Electron, reliability core (auth, stability gate, cost guard, healing, scope, CLI)
Phase 2 — REST API adapter + traceability report
Phase 3 — --diff mode (chỉ test code thay đổi) + Claude Code skill / MCP packaging
Phase 4+ — iOS, Android, vision fallback, policy engine