For AI agents: the complete documentation index is available at https://a3s-lab.github.io/Test/llms.txt, the full documentation bundle is available at https://a3s-lab.github.io/Test/llms-full.txt, and this page is available as Markdown at https://a3s-lab.github.io/Test/guide/surfaces-and-mcp.md.

Web、GUI、TUI 与 MCP

A3S Test 把被测界面抽象成 SurfaceDriver。Core 只认识类型化观察、动作、证据和关闭结果,不依赖浏览器 DOM、操作系统辅助功能 API 或终端模拟器。Web、GUI 和 TUI 驱动分别把自己的真实感知投影到这套公共协议。

相同的 click 或 expect 名称不代表三个 surface 拥有相同证据。每个驱动只能报告底层平台实际暴露的状态,缺少等价证据时必须关闭失败。

选择哪一种 Surface

产品形态推荐入口权威感知来源主要限制
浏览器页面,流程已经明确确定性 Web ACL浏览器语义、实时 DOM、渲染几何、网络与 Test KitURL 和网络受 origin policy 约束
浏览器页面,需要 Agent 探索agent start 或 agent run最新 observation、Page Context 和有界证据ref 每轮失效,模型 finish 只能提出建议
原生桌面应用GUI ACL 或 MCPCUA 辅助功能语义,可选窗口截图当前准入平台是 macOS,仍须认证真实 host
已知终端程序流程确定性 TUI ACLVT viewport、scrollback、cursor 和模式没有交互式 Agent host
外部编码 Agent 需要统一工具接口a3s-test mcp已注册 Web、GUI 和/或 TUI driver 的会话层MCP 不替代确定性 check 与 run;持久 agent CLI 仍仅 Web

Web Surface

Web 同时拥有最丰富的结构证据和最严格的浏览器策略。它适合业务回归、响应式布局、可访问性、网络替身、文件上传下载和 Test Kit 上下文。

确定性 ACL

suite "checkout" {
    version = 1

    scenario "complete-order" {
        name = "Complete checkout"
        surface = "web"
        timeout_ms = 30000

        navigate "open" {
            url = "http://127.0.0.1:3000/checkout"
        }

        fill "email" {
            target = label("Email")
            value = "tester@example.test"
        }

        click "continue" {
            target = role("button", "Continue")
        }

        expect "confirmed" {
            visible = role("heading", "Order confirmed")
        }
    }
}
a3s-test check tests/checkout.acl --json
a3s-test run tests/checkout.acl --json

check 只解析和准入,不打开浏览器。run 在准入通过后为每个 Web scenario 创建自有浏览器会话,按源顺序执行步骤,保存报告和证据,最后清理自己创建的进程树。

浏览器 adapter 与能力发现

a3s-test capabilities --json

a3s-test run tests/checkout.acl \
  --browser-driver standalone \
  --browser-executable /path/to/agent-browser \
  --json

当前协议准入 A3S Browser >= 0.4.0, < 0.5.0 和 standalone adapter >= 0.26.0, < 0.27.0。能力发现会实际探测 executable。文件存在但版本、Schema 或启动行为不兼容时仍会返回 test.driver.web.*。

默认运行强制 headless。只有显式 --headed 才显示窗口。--browser-microphone synthetic 使用确定性假设备,不读取真实麦克风;默认 disabled。

Origin 与 network domain 是两种权限

持久 Agent 会话从初始 URL 和每个 --allow-origin 建立 exact-origin 集合。它同时约束显式导航和成功观察。

a3s-test agent start http://127.0.0.1:3000/checkout \
  --session checkout \
  --goal "Complete checkout" \
  --success "The confirmation heading is visible" \
  --allow-origin https://auth.example.test \
  --allow-domain cdn.example.test \
  --json

--allow-origin 包含 scheme、hostname 和有效 port,可以扩大动作导航范围。--allow-domain 只向浏览器网络层增加 hostname 或前导 *. wildcard,不允许 Agent 导航或接受来自该 origin 的新页面观察。两者不能互相替代。

A3S Browser 直接执行 exact-origin policy。standalone 协议只能表达 hostname,因此会收到保守投影,session metadata 会记录实际使用的 containment mode。恢复持久会话时,策略或 adapter 模式不匹配会关闭失败。

DOM 渲染时如何附加 Test Kit 上下文

浏览器首先生成自己的交互语义。页面引入 Test Kit 后,运行时在组件注册、DOM commit、viewport 变化和页面稳定信号上增量维护 Page Context。

React 或页面组件
    -> Test Kit 注册组件身份、意图与稳定定位器
    -> 读取 DOM 几何、可访问名称、状态和样式事实
    -> 生成带 revision 的 Page Context snapshot
    -> Web driver 按当前 observation 合并浏览器语义
    -> Agent 得到 @eN、@cN 和只读 @uN

Test Kit 不篡改业务可访问树,也不向每个 DOM 节点永久写入大块属性。它维护独立、可撤销、有界的元数据层。坐标由实际渲染后的 DOM geometry 产生,只有当前 revision 有效。MutationObserver、ResizeObserver、scroll、viewport 和显式 ready 状态只负责失效与重新采样,不赋予页面新的动作权限。

普通观察应保持紧凑。需要组件、私有 node 或局部区域的完整细节时,使用 agent inspect。Page Context 协议、坐标空间和分页规则见Page Context 详解。

Web 生命周期

每个确定性 scenario、Agent session 或 MCP session 都拥有独立 runtime namespace、artifact 根和浏览器进程边界。Unix 使用专用 process group 与 EOF watchdog,Windows 使用 kill-on-close Job Object。timeout、取消、Drop 和第二次中断只清理本次运行注册的进程树,不按进程名终止其他浏览器。

GUI Surface

GUI 通过 A3S CUA adapter 使用操作系统辅助功能和窗口捕获。A3S Test 仍然拥有会话、动作策略、预算、报告和清理,CUA 负责平台感知与输入。CUA 私有 element token 不会进入 Core 或返回给 Agent。

先核对平台和真实 host

a3s-test gui-certification --json

当前锁定的 CUA 0.23.2 配置只准入 macOS installed-daemon 与 embedded-socket profile。Windows 和 Linux 在 transport 启动前明确失败。contract_tested 说明检入协议测试通过,不代表当前机器已经授予 Accessibility 和 Screen Recording 权限。

真实 worker 启用前应运行认证。

a3s-test gui-certify \
  --gui-policy-file config/gui-policy.yaml \
  --cua-proxy-executable /Applications/CuaDriver.app/Contents/MacOS/cua-proxy \
  --gui-macos-bundle-id com.example.Editor \
  --gui-target-mode launch \
  --gui-profile window-vision \
  --json

认证会执行真实 observation 和 ownership-safe cleanup。正式 release 还要求 CI 生成绑定源码修订、binary 与 policy digest、host 权限、语义与视觉观察、零残留进程的签名记录。一次本地成功 JSON 不能替代 release certification。

Host 固定应用身份和捕获范围

GUI 的以下选择都是 host 配置,Agent action 无权修改。

  • CUA policy 与 endpoint
  • macOS bundle ID
  • launch 或 attach 模式
  • attach PID 或 launch arguments
  • 精确窗口 title、automation ID 或 primary window
  • semantic 或 window-vision perception profile

launch 创建一个新应用实例,session 只有在证明它启动前不存在且 PID 身份仍匹配时才会终止它。attach 连接已有应用,任何终态都不会杀掉该应用。当前捕获范围严格限制为绑定的顶层窗口,不支持任意桌面截图。

Semantic 与 window-vision

semantic observation 返回有界辅助功能元素、role、label、value、automation ID、parent 和 frame,并投影成 A3S Test 自有 @gN.M ref。每个状态改变动作后,整代 ref 失效。

window-vision 还为每次观察生成一个窗口范围 PNG、尺寸、SHA-256 和 @vN。只有语义无法识别目标时才使用视觉点。

{
  "type": "click",
  "target": {
    "type": "visual_point",
    "snapshot": "@v2",
    "x": 420,
    "y": 96
  }
}

输入前会再次校验最新 observation、坐标边界、截图 digest、artifact containment、应用 PID 和窗口 identity。任一项漂移都会阻止 CUA input。成功的视觉动作会把 grounding 图片和 digest 作为证据返回。

GUI 支持边界

GUI 语义定位器只接受当前 ref、role、text、label 和 automation_id。CSS、test ID 与 placeholder 属于浏览器语义,GUI 不会根据字符串猜测等价元素。一个语义定位器匹配多个元素时会返回歧义错误,不会任选第一个。

动作可用目标与约束
snapshot只支持 interactive = true;非交互快照没有当前 CUA 协议可证明的完整节点集合
click、double_click、context_click接受语义目标或当前 visual_point;动作后整代 @gN.M 与 @vN 失效
fill只接受语义元素并派发 CUA set_value;视觉点无法证明控件身份,应改用 type,不可编辑状态仍由 driver 报错
type接受语义元素或当前视觉点,通过 CUA type_text 输入
drag当前必须是来自同一张最新窗口截图的两个 visual_point;语义到语义拖拽尚未准入
press发送非空按键名称,不使用元素目标
wheel目标可省略,也可使用语义元素或当前视觉点;不支持 modifier,且横纵轴必须恰好一个非零
screenshot只生成绑定窗口的 PNG,并重新校验 artifact 路径、图片摘要、PID 和窗口身份

GUI wheel 把 delta 的绝对值按每 100 单位换算成一行,向上取整并限制在 1 到 50 行。它不等价于 Web 的带 modifier 缩放手势。

断言GUI 的证据边界
text在当前辅助功能元素的 name 或 value 中查找可见文本
visible / hiddenvisible 接受已准入语义目标和当前 ref;hidden 只接受可重复解析的语义目标,过期或歧义不是“隐藏”的证据
value仅当匹配元素实际暴露 value 时比较精确字符串
layout两个稳定语义目标必须在同一次快照中都提供有限、正尺寸 frame;ref 与视觉点不准入

in_viewport、viewport coverage、pointer reachability、URL、rendered_texts、visible count、boolean state 和 selected values 当前没有等价 CUA 证据,会以 test.driver.gui.assertion_unsupported 关闭失败。单目标 rendered_text 读取 CUA value,否则回退到 label。浏览器网络、tab、frame、DOM 集合状态和终端动作也不会被猜测映射到 GUI。

TUI Surface

TUI 驱动拥有 executable、PTY 或 ConPTY、完整进程树、VT 状态、证据和清理。它适合已经知道命令、按键和文本成功条件的流程。

suite "editor" {
    version = 1

    scenario "open-document" {
        surface = "tui"
        timeout_ms = 30000

        wait "ready" {
            text = "Ready"
        }

        terminal_resize "size" {
            columns = 120
            rows = 40
        }

        terminal_paste "open" {
            text = "open fixtures/report.txt"
        }

        press "submit" {
            key = "Enter"
        }

        expect "visible" {
            text = "Quarterly report"
        }
    }
}
a3s-test run tests/editor.acl \
  --tui-executable ./target/debug/editor \
  --tui-arg --fixture-mode \
  --tui-columns 120 \
  --tui-rows 40 \
  --json

--tui-working-directory 必须是绝对路径。scrollback row 和 raw output byte 上限只控制有界保留,不会把观察变成无限。TUI snapshot 返回 viewport、scrollback、cursor、alternate-screen、application-cursor、bracketed-paste、process exit 和 truncation 元数据。

Unix 为每个 scenario 创建专用 PTY session、process group 和 EOF watchdog。Windows 使用 ConPTY 与 kill-on-close Job。根进程退出后仍有后代时,清理继续作用于完整 owned tree。

TUI 支持确定性 ACL,并可通过 --tui-executable(可与 Web/GUI 组合)注册 MCP host。持久 a3s-test agent CLI 仍仅 Web;终端动作在那里不可用。

MCP 给外部 Agent 的统一会话接口

MCP 把同一 session application layer 投影到 stdio。确定性测试仍由原有 runner 执行。host 可通过 --web-url、已审核 GUI host 选项和/或 --tui-executable 注册 Web、GUI、TUI 或其任意组合。仅当注册了 Web surface 时才广告 test_inspect 与 test_repair_*。

启动 Web host

a3s-test mcp \
  --web-url http://127.0.0.1:3000 \
  --web-allow-domain cdn.example.test \
  --max-sessions 4 \
  --artifacts-root .a3s-test/mcp-sessions

启动 GUI host

a3s-test mcp \
  --gui-policy-file config/gui-policy.yaml \
  --cua-proxy-executable /Applications/CuaDriver.app/Contents/MacOS/cua-proxy \
  --gui-macos-bundle-id com.example.Editor \
  --gui-target-mode attach \
  --gui-attach-pid 4242 \
  --gui-profile window-vision

MCP tool 参数中没有 executable、bundle ID、window selector、捕获范围或 policy。调用方只能选择 host 已注册的 surface。

协议生命周期

客户端必须使用 MCP 2025-06-18,并完成下面的顺序。

initialize
    -> notifications/initialized
    -> tools/list
    -> test_session_start
    -> test_observe
    -> test_act
    -> test_observe
    -> test_finish 或 test_abort

服务器按 session 串行化 turn,同时允许不同 session 在配置上限内独立运行。失败的 observation 也会使上一轮 ref 失效。EOF 会并发关闭所有独立 surface,每个 surface 仍受 cleanup deadline 限制。

MCP tools

工具组工具用途
会话test_session_start、test_observe、test_act、test_finish、test_abort、test_schema完成 observe、decide、act 循环
Page Contexttest_inspect读取有界 page、node、component 或 region
Repair 恢复test_repair_inbox、test_repair_inspect先排列一个活动会话,再读取一条持久循环
Repair 提取test_repair_watch、test_repair_claim提取人工提交并领取一个带 lease 的 attempt
Repair 生命周期test_repair_progress、test_repair_reply、test_repair_complete、test_repair_verify报告编辑阶段、请求澄清并进入本地验证
Repair 终止test_repair_fail、test_repair_cancel追加失败或取消终态,同时保留历史

test_schema 返回当前 interactive Action JSON Schema 和实际注册 surface。Runner 专用 verify_contract 不会出现在 interactive Schema 中。test_repair_inbox 不连接浏览器,只读取当前活动 owner 的 ledger;修改 lease 过期时会返回类型化对账动作,不会重放旧编辑命令。工作区级 CLI 发现、Repair Ledger 的 attempt、lease 和验证规则见人工评审与自动修复。

Cleanup 是可观察状态

test_finish 或 test_abort 达到调用方 deadline 后,已经派发的 driver close 仍在 owned task 中继续。此时其他 turn 返回 retryable test.session.cleanup_in_progress。如果 close 最终返回可重试错误,session 进入 cleanup_required,只能用同一 session ID 再次调用 finish 或 abort,不能继续 observe 或 act。

这条规则避免调用方超时后丢失 surface ownership,也避免重用仍绑定旧浏览器或应用的 session 名称。

三种执行入口如何配合

入口谁做决策是否持久最终 verdict 来自哪里
a3s-test runACL 固定步骤否Runner 对每个确定性步骤和清理结果的汇总
a3s-test agent run部署方 LLM provider单次工作流本地 verification block 与清理,模型 finish 无权决定
agent start 或 MCP外部编码 Agent是调用方 finish 摘要加持久证据,稳定路径应再固化为 ACL

探索阶段用持久会话理解未知路径。动作和成功条件稳定后,把它们迁移到 ACL。分布式执行只调度已经确定性的 Web、GUI 与 TUI suite,见Worker 与分布式执行。