Language / 语言: English · 中文

A3S Test gives coding agents a trustworthy interface feedback loop:
fresh browser facts, revision-bound actions, source-aware review, and inspectable evidence.

中文文档 · English docs · Install · Quick start · Test Kit · Architecture

_{The real Test Kit package running inside the documentation site. This public demo keeps findings in the current tab; it does not connect to a repair agent or edit source.}

A coding agent should never repair an interface it only imagines. A3S Test keeps the path from page to regression short and checkable:

Browser facts, model advice, human authorization, and workspace mutation remain separate authorities. A source span can explain where to look; it never grants permission to edit.

Test Kit is optional for ordinary browser automation. Add it when component ownership, source mapping, rendered geometry, visual references, or human marking materially improves the task.

The release installer downloads the platform archive, verifies its SHA-256, and installs the matching portable A3S Test Skill for detected coding agents.

macOS or Linux:

curl -fsSL https://github.com/A3S-Lab/Test/releases/latest/download/install.sh | sh

Windows PowerShell:

& ([scriptblock]::Create((irm 'https://github.com/A3S-Lab/Test/releases/latest/download/install.ps1')))

Pin the current stable release when reproducibility matters:

curl -fsSL https://github.com/A3S-Lab/Test/releases/latest/download/install.sh |
  sh -s -- --version v1.0.2

& ([scriptblock]::Create((irm 'https://github.com/A3S-Lab/Test/releases/latest/download/install.ps1'))) -Version v1.0.2

Install the development-only React integration from npm:

npm install --save-dev @a3s-lab/testkit@0.6.2
npm ls @a3s-lab/testkit

@a3s-lab/testkit 0.6.2 is published on the official npm Registry with GitHub OIDC provenance. Its version advances independently from the CLI.

Open the complete installation guide

Start a persistent session with a result the page can prove:

a3s-test agent start http://127.0.0.1:3000/checkout \
  --session checkout \
  --goal "Complete checkout with the fixture account" \
  --success "The confirmation heading is visible" \
  --json

a3s-test agent observe --session checkout --interactive --json

The observation returns fresh semantic refs bound to one observation:

observation_id: 1
@e1 [button] Continue

Admit one action against that observation, retain the minimum evidence, and finish explicitly:

a3s-test agent click @e1 \
  --session checkout \
  --observation 1 \
  --json

a3s-test agent screenshot screenshots/confirmation.png \
  --session checkout \
  --json

a3s-test agent finish \
  --session checkout \
  --status passed \
  --summary "Checkout completed and confirmation was observed" \
  --json

The browser can close; the result remains inspectable:

.a3s-test/agent-sessions/checkout/
├── session.json
├── events.jsonl
├── report.json
└── artifacts/
    └── screenshots/confirmation.png

Continue through the first Web test

Mount two components at the application root and keep both explicitly disabled in production:

import { A3SReviewOverlay, A3STestKit } from "@a3s-lab/testkit/react";

const testKitEnabled = import.meta.env.DEV;

<A3STestKit enabled={testKitEnabled} page={{ id: "app" }}>
  <App />
  <A3SReviewOverlay enabled={testKitEnabled} locale="auto" />
</A3STestKit>;

That is enough for the default review path:

1. Open the right-side Review panel.
2. Select an element or drag over an area.
3. Describe the expected result and submit deliberately.

Text, multi-select, drawing, and Layout stay under More tools. The design board slides out on the right and can hold a sketch or a crop of browser-page content without requesting whole-screen sharing permission. The headless Context Runtime can also run without the visible Review Overlay.

The local project loop validates the live a3s.test.testkit-handshake/1 after hydration before it reports ready. Its init, doctor, and dev commands are included in the v1.0.2 release.

Add an explicit source boundary only where it helps:

import { A3STestBoundary } from "@a3s-lab/testkit/react";

<A3STestBoundary
  id="checkout-form"
  name="Checkout form"
  source={{ file: "src/Checkout.tsx" }}
>
  <Checkout />
</A3STestBoundary>;

Framework adapters may register an exact DOM owner and an explicitly supplied Source Map v3. A resulting source-mapping record keeps ranked spans, confidence, origin, and exact or ancestor relation. It is navigation evidence, not source-edit authority.

Read the Test Kit integration guide

Every actionable ref belongs to an observation or page revision. Page changes expire browser semantics, geometry, screenshots, and any Test Kit locator that an exact delta cannot prove unchanged.

Actions are closed variants. Schema, target type, driver capability, origin policy, and session state are validated before input reaches Web, GUI, or TUI. Unsupported behavior fails closed instead of being approximated.

Selecting, sketching, capturing, or saving a draft does not authorize a source change. A finding crosses into the repair ledger only through explicit submission; workspace mutation belongs to a separately authorized coding agent.

A repair must prove its success against a newer rendered revision. A3S Test can select focused project checks from trusted configuration, expand to broader regression when observed impact demands it, and preserve the smallest proven browser path as ACL.

Read the authority and safety model

Agent sessions discover unknown paths. ACL repeats only paths whose actions, waits, and success conditions are explicit:

suite "product-smoke" {
    version = 1

    scenario "home-page" {
        name = "Open the home page"
        surface = "web"
        timeout_ms = 30000

        navigate "open" {
            url = "https://example.com"
        }

        wait "loaded" {
            load = "networkidle"
        }

        expect "heading" {
            text = "Example Domain"
            stable_for_ms = 300
            sample_interval_ms = 50
        }

        screenshot "evidence" {
            path = "home.png"
        }
    }
}

a3s-test check tests/e2e/smoke.acl --json
a3s-test run tests/e2e/smoke.acl --json

Ordinary actions are never retried implicitly. Only an explicitly sampled, read-only assertion repeats inside its bounded stability window.

Every launched program belongs to an owned process tree. Timeouts and cancellation reap that tree without closing unrelated developer sessions.

All surfaces share Core action, policy, evidence, result, and cleanup contracts; each adapter still owns perception and execution.

• Run the first Web test
• Install only the parts you need
• Add Web Test Kit
• Understand Page Context
• Compare exploration and ACL
• Inspect every capability

Repository-level protocol and implementation references remain in docs/.

cargo fmt --all -- --check
cargo test --workspace --all-targets --locked
cargo clippy --workspace --all-targets --locked -- -D warnings

npm --prefix packages/testkit test
npm --prefix website run check
npm --prefix website run build
npm --prefix website run check:site

A3S Test and @a3s-lab/testkit are licensed under the MIT License.