Argus — Testing for Coding Agents

Argus — 面向编码 Agent 的测试工具

Argus 帮助编码 Agent 测试它们构建的应用——运行真实的用户操作流程、查找错误，并通过证据进行验证。

Argus 是一个 MCP 服务，可直接驱动浏览器，让你的 Agent 无需另行组装浏览器服务，也能获得完整的测试体验。目标覆盖率、持久性检查、独立复查、报告和回归复查为测试提供支持，但不会取代测试本身。每条发现都会说明其依据：由独立检查复现、由 Agent 观察到（例如，视觉判断）、未能复现，或结论不明确。宿主 Agent 决定要调查什么，以及行为是否有误。浏览器测试可跨平台运行，并提供单独的原生 macOS 配置。

产品页面 · 快速开始 · Argus 的不同之处 · 对比 · 工具 · 基准测试

English (primary) · 简体中文

以 Agent 为先的测试

Argus 为你已在使用的 Agent 增添了测试工作流：检查、操作、检查持久性、独立复现症状，并关联证据。 HTML 报告是查看证据的可选方式，而不是 Agent 界面。

自 0.8.0 起，工具响应会保留文本和 图像，同时新增带版本的 structuredContent 封装和输出架构。 核心操作、观察、验证、发现、覆盖率和报告操作会公开机器可读数据；其他工具目前会公开状态／错误元数据，并保留现有内容。 对于请求进度的 MCP 客户端，较长的工作流会发送真实的阶段通知。 不显示通知的客户端仍会在最终结果中收到阶段摘要。参见Agent 协议。

• 覆盖率指导： 最多提供四项基于证据的后续检查、未完成目标、持久性提醒、输入边界探测和探索停滞检测。
• 操作 + 观察： 点击、填写、选择、导航和键盘操作会返回当前页面证据，减少单独观察的需要。
• 保守检查： 缺失或格式错误的证据会保持为未知，而非猜测通过或捏造错误。发现会关联到稳定的会话引用。
• 完整的默认流程： web 配置提供 28 个测试工具，并附有简洁的发现说明，涵盖从首次观察到回归复查的整个流程。添加 --response-mode compact，即可保留结构化证据，而不再以文字重复这些证据。兼容模式仍为默认模式。
• 可见进度： 通过 MCP 展示真实阶段、目标数量和检查数量； --monitor-port 8765 会添加本地实时仪表板，且不会暴露目标文本。
• 已测量的响应开销（0.9）： 更小的输出架构、数值型负载和组件计时计数器，以及可选的 --response-mode delta，适用于保留观察快照的客户端。缺少基准时必须执行完整的 observe； 验证结果和图像块绝不会被缓存的判定取代。

安装 Argus 能提升 Agent 的表现吗？使用配对评估工具进行测量：模型、任务、测试夹具、初始状态和预算均相同，并保留两组测试结果及失败记录。本地脚本化冒烟测试套件用于验证评估工具；它不能证明 Agent 性能有所提升。

0.11.0 版本更新

• **完整的默认工作流：**28 个工具的 web 配置覆盖探索、操作、验证、记录、报告和 regression_check。advanced 配置增加网络、状态、标签页、坐标和爬取控制。
• **安装更轻量：**已移除旧版 LLM 规划器 CLI 和 LiteLLM；全新运行时安装会解析 41 个软件包，而非 82 个。基准测试和评估位于仅供仓库使用的 argus_lab 软件包中。
• **证据更有力：**即使在错误页面上，也能确定元素是否存在；expect_status 支持预期的 404；重新最终确认的目标会保持其证据窗口为最新状态；复查会记录哪次尝试得出了判定。

从 0.10 升级：agent 和 core 仍会启动服务，但现在会加载 web。原先使用 agent 的用户会获得 28 个工具，而非 19 个（发现载荷为 34,379 字节，而非 24,386）；原先使用 core 的用户会获得 28 个工具，而非 30 个（Python 3.11/3.12 下的载荷为 51,732 字节，Python 3.13 下为 50,564 字节），并会在 advanced 中找到 check_links 和 check_performance。argus <url> 命令已移除。详情请参阅变更日志。

0.8 Codex 评估包含十组匹配样本：Argus 发现了 6/6 个缺陷机会，而浏览器基线为 5/6，其中包括一个事后发现的测试夹具缺陷。两者都没有观察到误报，声明目标覆盖率也相同。Argus 花费的时间和令牌更多。在四个重复的试点案例中，针对性更新将 Argus 的调用中位数从 17 次降至 9 次；这个小规模的合成样本不足以证明其普遍更优。

无模型的响应编码基准测试比较了相同的合成证据，其中包括导航失效。对于这 24 个响应，Delta 模式相较紧凑模式将结果 JSON 总量减少了 48.25%；已使用 0.11.0 复现。该指标衡量的是字节数，而非 Agent 令牌用量或测试质量。

来自真实本地测试夹具运行的实时监控

下方的仪表板记录了一次保存名称持久性失败、一个独立复现凭证和两个已执行的目标。它展示的是实际运行时事件，而非模型推理或模拟百分比。MCP 宿主会自行决定是否显示进度通知；无论 UI 如何选择，本地仪表板都能独立运行。

无需模型即可复现：安装开发依赖项和 Chromium 后，运行 pytest tests/test_monitoring.py。

证据与报告

提供一个 URL，即可获取缺陷报告——每条缺陷都会标明 Argus 是否独立复现了它，还是仅观察到了它：

复现凭证显示指定症状是否经受住了独立复查。它本身并不能证明根本原因，也不能证明该行为违反了产品要求。观察结果、无法定论的检查和已复现的症状，在 Agent 结果和导出的证据中均可区分。

工作原理

flowchart LR
    A(["observe"]) --> B{"looks wrong?"}
    B -->|not sure| C["act: click · type · resize · verify"]
    C --> A
    B -->|suspected defect| D["verify_persistence — inspect a fresh load"]
    D --> E["record_bug with an independent recheck"]
    E --> F(["reproduced / not reproduced / inconclusive"])
    F --> G[["report: HTML · JSON · JUnit · SARIF"]]

Agent 负责判断。Argus 提供简明的 QA 指引、按描述命名的工具界面（click_what("Login button")，而非 click(7)）、目标覆盖记录，以及一个复现凭证引擎，用于区分已观察、已复现和无法定论的症状。

凭证确认的是指定的可观察症状，而非所有可能的根本原因。默认情况下，干净加载会保留身份验证状态和浏览器存储；重放可能会重复实际写入操作。定性观察和无法定论的检查会与已验证的发现明确区分。

快速开始

Argus 0.7.1 及更高版本要求 Python 3.11+。如果默认解释器版本较低，请在 MCP 配置中使用 uvx --python 3.12 --from argus-testing argus-mcp。升级现有 pip 安装前，请先升级 Python。

安装 uv 后，无需全局安装 Python 包。请先安装一次 Chromium：

uvx --from playwright playwright install chromium

如果升级时提示缺少浏览器可执行文件，请安装与 Argus 自带的 Playwright 环境匹配的浏览器，然后重启 MCP 宿主：

uvx --from argus-testing python -m playwright install chromium

uvx --from argus-testing argus-mcp --doctor 会检查 Chromium 是否与 Argus 的 Playwright 匹配、启动一次 Chromium，并确认报告目录可写；每项检查失败时都会显示确切的修复方法。然后将 Argus 连接到 MCP 客户端。

Claude Code

claude mcp add argus -- uvx --from argus-testing argus-mcp

可选的 Claude 插件包会固定已发布的运行时和默认的 web 配置。请用它替代手动 MCP 连接，而不要与手动连接同时使用。先运行一次性预热命令，然后使用 /plugin install argus-testing --marketplace chriswu727/argus 安装。该插件包由项目维护；目录批准需单独进行。

Codex 和 ChatGPT 桌面应用

Codex CLI、Codex IDE 扩展和 ChatGPT 桌面应用共用同一份本地 MCP 配置：

codex mcp add argus -- uvx --from argus-testing argus-mcp

或者，使用 codex plugin marketplace add chriswu727/argus 和 codex plugin add argus-testing@argus 安装 Codex 插件包（适用于 Codex CLI 和 ChatGPT 桌面应用）。该插件包会固定已发布的运行时和 web 配置。请用它替代手动配置项，而不要与手动配置同时使用。

Cursor

该按钮会将 Argus 添加到 Cursor；首次测试前，请先运行上方的 Chromium 安装命令。

任意 stdio MCP 客户端

{
  "mcpServers": {
    "argus": {
      "command": "uvx",
      "args": ["--from", "argus-testing", "argus-mcp"]
    }
  }
}

默认的 web 配置文件提供完整的 Web 测试闭环，同时不会让主机被所有专业工具淹没。使用 uvx --from argus-testing argus-mcp --list-tools 查看所选配置文件，使用 --tool-profile advanced 启用网络、状态、标签页、坐标和爬取控制，或使用 --tool-profile screen 进行 macOS 原生应用测试。ARGUS_TOOL_PROFILE 环境变量提供相同的设置方式。

对于会读取结构化 MCP 结果的 Agent，可启用精简响应（监视器为可选项）：

uvx --from argus-testing argus-mcp --response-mode compact --monitor-port 8765

在发出下一次 observe 前，先读取返回的观察结果。使用 coverage_update(goal=["edit profile", "reload profile"], status="in_progress") 将相关目标批量处理；完成时提供观察到的证据，而不是假定测试通过。监视器仅在本地运行。

--response-mode delta 是额外的可选设置，适用于能够保留并合并快照 ID 的客户端。如果主机无法可靠地解析基础快照，请保持使用 compact。 参阅快照约定。

无需打开浏览器或调用模型，即可检查安装、产品版本、stdio 握手、工具发现和结构化错误：

uvx --from argus-testing python -m argus.install_check

版本发生变化后，必须重新安装可编辑安装，以使其包元数据与源代码保持一致。MCP serverInfo.version 现在报告 Argus 的版本，而非 MCP SDK 的版本。

然后，只需在 Agent 会话中提出要求：

“测试我的应用 http://localhost:3000 — 找出真正的 bug。”

就这么简单。Agent 负责操作；Argus 确保测试可靠，并生成报告。

对于有范围限定的审查，主机可以在 start_session 中明确提供 goals、constraints 和建议性的 time_budget_minutes。Argus 会返回一次完整的测试协议，并在后续观察中持续显示未完成目标和已发现页面。在开始测试流程前，将目标标记为 in_progress；当 coverage_update 将目标标记为 exercised 或 blocked 时，Argus 会要求提供具体说明，并自动关联该测试时段内产生的 URL、已隐藏值的操作、屏幕截图、持久化检查、bug 和观察结果。最终的 HTML 和 JSON 报告会保留已完成和未完成的覆盖情况，不会暗示未完成的测试已经全面完成。

从 0.10.0 版本起，切换到另一组目标时，之前的证据窗口会被冻结，但这些目标不会因此完成。延后记录的发现可以指定 evidence.goal 或 evidence.goals；预期结果和实际结果都会保留在报告中。全新加载时记录的发现会先捕获被检查的页面，再返回 Agent 当前页面，因此稍后记录 bug 时不会附上无关的屏幕截图。参阅证据约定。

pip install argus-testing
playwright install chromium
claude mcp add argus -- argus-mcp

pip install 'argus-testing[mac]'
brew install cliclick          # keystroke / coordinate fallback
argus-mcp --doctor             # web checks plus Screen Recording + Accessibility grants
claude mcp add argus-screen -- argus-mcp --tool-profile screen

Argus 会将每次运行的截图写入各自的运行目录，确保后续测试不会覆盖之前的证据。 较长的浏览器会话也会限制内存中事件日志的容量，并且只读取可检查 API 流量的响应正文； 二进制正文和超大正文会在进入 Python 内存前跳过。

报告清理需显式执行，默认采用试运行模式。在此示例中，最新的 20 次完整运行受到保护； .argus 日志和状态胶囊永远不会被删除：

argus-cleanup --output ./argus-reports --keep-runs 20
argus-cleanup --output ./argus-reports --keep-runs 20 --apply

使用 --older-than-days 和 --max-size-mb 设置更严格的策略。高级限制可通过 ARGUS_MAX_NETWORK_EVENTS、ARGUS_MAX_ERROR_EVENTS、ARGUS_MAX_DOWNLOAD_EVENTS、 ARGUS_MAX_DIALOG_EVENTS、ARGUS_MAX_RESPONSE_BODY_BYTES 和 ARGUS_MAX_RESPONSE_READ_BYTES 调整。默认情况下，会跳过未声明长度的响应； 设置 ARGUS_CAPTURE_UNKNOWN_LENGTH_BODY=1 可选择读取这类响应。如果某项限制导致旧证据被丢弃， Argus 会在工具输出和最终会话摘要中说明。

实时监控（0.7）

在 MCP 客户端启动的命令中添加监控端口：

argus-mcp --monitor-port 8765
# Or choose an available port automatically:
argus-mcp --monitor-port 0

打开 http://127.0.0.1:8765，查看会话状态、当前操作及持续时间、 最近进度、调用、运行故障、发现和近期事件。所选 URL 会输出到 stderr， 因此 stdio MCP 消息保持完整。 ARGUS_MONITOR_PORT 具有相同作用；默认关闭监控。

监控仅绑定到 127.0.0.1，会拒绝无关的 Host/Origin 标头，且不提供操作端点。 它不会输出页面内容、URL、输入值、截图或工具参数。它不是经过身份验证的远程服务； 请勿通过公共代理公开它。事件保留数量有限（默认 512 条），同时最多允许 32 个 SSE 订阅者。

运行时设置会在启动时验证。显式命令行选项优先于环境变量，环境变量优先于默认值：

一个运行时仅管理一个活动会话。操作和生命周期变更会串行执行；操作超时会取消操作并关闭后端。 有副作用的操作绝不会自动重试。要运行另一个可独立控制的会话，受支持的方式是启动单独的 MCP 进程。

回归门禁与证据隐私

argus-regression http://localhost:3000 --output ./argus-reports

退出代码：0 未复现已知症状（或没有日志），1 仍复现已知症状， 2 运行或存储故障，3 结果不确定。退出代码为 0 并不能证明应用完全正确。 自动回归使用内置文本/HTTP 检查，绝不执行会产生写入的重放。

输入值（包括键入、粘贴和选择的值）会保存在会话专用的输入保险库中， 不会写入操作轨迹或导出的重放步骤。需要输入的导出步骤会标记为 requires_input； 不能将其当作真实值已取消遮盖的步骤来重放。胶囊有意包含凭据，并在 POSIX 系统上以仅所有者可访问的文件权限保存。报告和截图仍可能包含可见的应用数据；请参阅隐私。

Argus 的差异

让探索性测试拥有可重复的证据工作流。 Agent 可以使用 Argus 探查预先编写的检查之外的用户旅程、检查发生了哪些变化，并独立重新检查疑似症状。Agent 仍需判断观察到的行为是否违反应用的要求；复现凭证只是辅助证据，并不保证结果正确或完全没有误报。

对比

Microsoft 的 Playwright MCP 提供浏览器自动化，并支持可选的测试断言（--caps=testing），例如验证可见文本或元素值。Argus 则围绕整个测试流程构建：预先声明目标并持续跟踪证据、在写入后检查持久化、将问题与其背后的操作、检查和截图关联、独立重新检查，以及针对后续构建重新检查先前发现的问题。Argus 内置浏览器控制，也可以与其他工具配合运行。它不能替代宿主模型的判断，也不保证能发现所有缺陷。

配对评估使用相同的宿主和任务，对比了传统的 Playwright MCP 适配器与 Argus。该适配器不是官方 Playwright MCP 包，不得将这些结果表述为对第三方产品的排名。

基准测试

基准测试和评估需从源代码检出目录（argus_lab/）运行；它们不属于已安装的软件包。

$ python -m argus_lab.bench --target all

  buggytasks    22 / 22  = 100 %   ·  mechanical bugs (console errors, fake delete, auth bypass…)
  darkshop      12 / 12  = 100 %   ·  human-eye bugs (fake scarcity, lying toasts, stale state…)
  ──────────────────────────────────────────────────────────────────────
  total         34 / 34  = 100 %   ·  reproducible from git clone in two commands

34 / 34 是能力上限——通过工具接口可查找的内容，由确定性脚本测得。我们刻意将其与特定大模型多常能记得并善用这些工具区分开来；后者结果波动较大，以下会如实报告。

python test-site/app.py           # BuggyTasks  :5555
python human-eye-fixture/app.py   # DarkShop    :5556
python -m argus_lab.bench --target all

工具接口

argus-mcp 默认启动 web 配置，提供完整的测试循环：探索、操作、验证、记录、报告，并重新检查先前发现的问题。下文列出了所有公开工具。也可直接从已安装的服务端获取工具数量：

uvx --from argus-testing argus-mcp --list-tools
uvx --from argus-testing argus-mcp --tool-profile advanced --list-tools
uvx --from argus-testing argus-mcp --tool-profile screen --list-tools

较早的配置名称仍可用于启动服务端：agent 和 core 会加载 web 配置，因此它们的工具集会变化（19 → 28 和 30 → 28 个工具）。

报告会保留原始截图作为证据，并默认在 report-assets/ 下写入精简的 WebP 预览，而不是将每张全尺寸 PNG 都以 Base64 嵌入 HTML。如果单个自包含 HTML 文件比文件大小更重要，请设置 ARGUS_PORTABLE_REPORT=1。JSON 输出包含完整的复现回执、覆盖契约及其结构化证据引用、约束、审查模式、工具调用和记录步骤的计数、截图元数据，以及定性观察结果。JUnit 套件失败总数与生成的 <failure> 节点数一致。

uvx --from argus-testing argus-mcp --tool-profile advanced --unsafe

本地优先的安全与隐私

Argus 在你的机器上运行，不会向 Argus 运营的服务发送遥测数据。报告和屏幕截图默认保存在 ./argus-reports 下；你的 MCP 主机及其配置的模型提供商仍可能收到对话中包含的工具结果。浏览器操作和 macOS 原生控件可能造成真实影响，因此请尽可能使用测试账号和非生产数据。

在使用 Argus 测试敏感系统之前，请阅读完整的隐私披露和安全政策。

本地文件上传和 file:// 页面需要显式指定夹具目录； Cookie／存储检查默认会隐藏值。请在 MCP 主机的服务环境中配置这些功能， 而非通过页面内容或工具参数配置：

{
  "ARGUS_FILE_ROOTS": "[\"/absolute/path/to/test-fixtures\"]",
  "ARGUS_ALLOWED_ORIGINS": "[\"http://localhost:3000\"]"
}

可选的来源策略限制的是工具目标，而非浏览器的网络出口。 对于不可信目标，重定向和页面资源仍需通过网络隔离来防护。 只有在确实需要检查原始 Cookie／存储内容，且主机获准接收凭据时， 才启用 ARGUS_ALLOW_SENSITIVE_READS=1。

理念

项目布局

argus/
├── mcp_server.py      # process entry point and compatibility imports
├── entrypoints/mcp/   # public tool catalog, profiles and MCP adaptation
├── application/       # session manager and focused QA use cases
├── domain/            # models, errors, states, replay and verification contracts
├── adapters/          # monitoring, logs, file journal, report service and exporters, JS assets
├── bootstrap.py       # composition root: injected backend/repository factories
├── ports.py           # narrow lifecycle, observation, verification and storage protocols
├── settings.py        # validated, per-runtime configuration
├── browser.py         # Playwright adapter (public operations; private page ownership)
├── screen/            # macOS AX adapter, permissions, safety
├── resolver.py        # description → element (web + screen)
└── cli.py             # argus-regression and argus-cleanup commands
argus_lab/            # repository-only: not in the installed wheel
├── evaluation/        # paired schemas, isolated fixtures, opt-in host runner, adjudication
└── bench/             # deterministic capability benchmark
test-site/            # BuggyTasks  (22 mechanical bugs)
human-eye-fixture/    # DarkShop    (12 human-eye bugs)

实现边界、测试和扩展点请先阅读架构、设计决策 和贡献指南。共享回归测试不会导入或修改 MCP 服务。