Argus — Testing for Coding Agents

Argus

実際のテストエンジニアのようにアプリをテストする MCP サーバーです。ユーザージャーニーを探索し、スクリプト化されていないバグを発見し、各発見事項を報告前に検証します。

Argus は MCP サーバーです。Claude Code、Codex、Cursor、または任意の MCP ホストに、ホスト側エージェントの役割やより広範なコーディングタスクを引き継ぐことなく、証拠を重視したブラウザー QA を追加します。エージェントは探索、調査、永続化の確認、再現可能なバグの記録を行います。認定された発見事項はすべて、報告前にクリーンなページ読み込みから独立して再確認されます。

製品ページ · クイックスタート · Argus が異なる理由 · 比較 · ツール · ベンチマーク

出力

URL を渡すと、バグのレポートが得られます。それぞれに、Argus が独立して再現したのか、単に観察しただけなのかが示されます。

緑色のバッジこそが重要なポイントです。LLM にバグを主張させることなら誰にでもできます。Argus はページを最初から読み込み直し、症状を再確認してからVERIFIEDと判定します。そのため、このレポートは仕分けが必要な推測の一覧ではなく、信頼できるバグの一覧です。

仕組み

flowchart LR
    A(["observe"]) --> B{"looks wrong?"}
    B -->|not sure| C["act: click · type · resize · verify"]
    C --> A
    B -->|bug| D["verify_persistence — reload from a clean state"]
    D -->|symptom repeats| E(["VERIFIED"])
    D -->|symptom gone or uncertain| F(["not certified"])
    E --> G[["report: HTML · JSON · JUnit · SARIF"]]

インテリジェンスを担うのはエージェントです。Argus は簡潔な QA ガイダンス、説明文をキーにしたツール群（click(7)ではなくclick_what("Login button")）、目標カバレッジ台帳、そして「モデルがこれをバグだと思っている」を「このバグは実在します。これが証拠です」に変える再現証明エンジンを提供します。

証明が確認するのは、指定された観測可能な症状であり、考えられるすべての根本原因ではありません。クリーンな読み込みでは、デフォルトで認証状態とブラウザーのストレージが保持されます。再生によって、実際の書き込みが再実行される場合があります。定性的な観察や結論が出ない確認は、検証済みの発見事項とは区別されます。

クイックスタート

uv がインストールされていれば、Python パッケージをグローバルにインストールする必要はありません。Chromium を一度インストールします。

uvx --from playwright playwright install chromium

次に、Argus を MCP クライアントに接続します。

Claude Code

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

Codex と ChatGPT デスクトップアプリ

Codex CLI、Codex IDE 拡張機能、ChatGPT デスクトップアプリは、同じローカル MCP 設定を使用します。

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

Cursor

このボタンで Argus を Cursor に追加できます。初回テストの前に、上記の Chromium インストールコマンドを一度実行してください。

あらゆる stdio MCP クライアント

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

デフォルトの core プロファイルでは、ホストに専門ツールをすべて読み込ませることなく、主要な Web テストのワークフローを利用できます。選択中のプロファイルを確認するには uvx --from argus-testing argus-mcp --list-tools を実行します。ネイティブ macOS のテストには --tool-profile screen を、上級者向け機能をすべて利用するには --tool-profile full を指定します。環境変数 ARGUS_TOOL_PROFILE でも同じ設定ができます。

あとは、エージェントとのセッションでこう依頼するだけです。

「http://localhost:3000 のアプリをテストして、実際のバグを見つけてください。」

これで完了です。操作はエージェントが進め、Argus が結果の信頼性を保ちながらレポートを作成します。

範囲を絞ってレビューする場合、ホストは start_session に明示的な goals、constraints、および参考値としての time_budget_minutes を渡せます。Argus はテストプロトコル全体を一度だけ返し、その後の観測でも未達成の目標と検出済みのページを確認できるようにします。各目標の検証に進む前に in_progress とし、coverage_update で exercised または blocked に変更する際には、具体的な説明が必要です。また、Argus はそのテスト期間中に生成された URL、値を伏せたアクション、スクリーンショット、永続性チェック、バグ、観測結果を自動的に関連付けます。最終的な HTML および JSON レポートには完了済みと未完了の両方のカバレッジが記録され、不完全なテストを網羅的なものと誤解させません。

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

# Uses a LiteLLM-backed planner. Set a provider key (OPENAI_API_KEY, DEEPSEEK_API_KEY, …).
uvx --from argus-testing argus http://localhost:3000 --model deepseek/deepseek-chat

# Higher recall: union N independent passes (deduped, proven instance kept)
uvx --from argus-testing argus http://localhost:3000 --passes 3

pip install 'argus-testing[mac]'
brew install cliclick          # keystroke / coordinate fallback
argus-mcp --doctor             # check 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 件）、同時に接続できる SSE サブスクライバーは最大 32 件です。

ランタイム設定は起動時に検証されます。明示的なコマンドラインオプションが環境変数より優先され、環境変数はデフォルト値より優先されます。

1 つのランタイムが所有できるアクティブなセッションは 1 つです。アクションとライフサイクルの変更は順次実行されます。操作がタイムアウトすると、アクションをキャンセルしてバックエンドを終了します。副作用のあるアクションが自動的に再試行されることはありません。別のセッションを独立して制御するには、別個の MCP プロセスを実行する方法がサポートされています。

回帰テストのゲートとエビデンスのプライバシー

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

終了コード：0 既知の症状が再現されなかった（またはジャーナルがない）、1 既知の症状が引き続き再現される、2 運用上またはストレージ上の失敗、3 判断不能。終了コードが 0 でも、アプリケーションが完全に正しいことを証明するものではありません。自動回帰テストでは組み込みのテキスト／HTTP チェックを使用し、書き込みを伴うリプレイは行いません。

入力、貼り付け、選択された値はセッション内でのみ使われる入力ボルトに保持され、アクショントレースやエクスポートされたリプレイ手順には含まれません。入力が必要なエクスポート済み手順には requires_input の印が付き、秘匿された値を実際の値として扱ってリプレイすることはできません。カプセルには意図的に認証情報が含まれており、POSIX では所有者のみがアクセスできるファイル権限で保存されます。レポートやスクリーンショットには、引き続きアプリケーションの表示データが含まれる場合があります。プライバシーをご覧ください。

Argus の違い

既存のテストツールでテストできるのは、スクリプトに書いた内容だけです。 Playwright と Cypress は、記述したアサーションを実行します。Argus は、テスト対象として思いつかなかったバグを 発見 し、さらに LLM だけでは信頼して任せられないこと、つまり、バグを証明します。

比較

バグを見つけるうえで重要な軸、つまり 自律的に発見し、独立して検証し、報告する という点で、Argus はブラウザー MCP 系ツールとは異なる位置づけです。

これらは「劣った」ツールではなく、役割が異なります。Playwright MCP はエージェントに優れた操作能力を提供し、Chrome DevTools MCP は Argus にはない詳細なネットワーク／パフォーマンス／メモリの検査機能を提供します。Argus は 何がバグかを判断し、それを立証する レイヤーです。併用してください。

ベンチマーク

$ python -m argus.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 は、決定論的なスクリプトで測定した機能上の上限、つまりツールのインターフェイスを通じて 発見可能なもの を示します。これは、特定の LLM がどれだけうまくツールを使うかを示す 実際の頻度 とは意図的に分けており、その結果はばらつきが大きいため、以下で率直に報告します。

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

ツール一覧

argus-mcp は、用途を絞った core Web プロファイルで起動します。公開されている各ツールについて、以下で説明します。ツール数は、インストール済みサーバーから直接確認することもできます。

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

レポートでは元のスクリーンショットをエビデンスとして保持し、デフォルトでは、フルサイズの PNG をすべて HTML に Base64 で埋め込む代わりに、コンパクトな WebP プレビューを report-assets/ に出力します。サイズよりも単一の自己完結型 HTML ファイルを優先する場合は、ARGUS_PORTABLE_REPORT=1 を設定してください。JSON 出力には、完全な再現レシート、カバレッジ契約と構造化されたエビデンス参照、制約、レビューモード、ツール呼び出し数と記録済みステップ数、スクリーンショットのメタデータ、定性的な観察結果が含まれます。JUnit のスイート失敗数は、出力された <failure> ノードの数と一致します。

uvx --from argus-testing argus-mcp --tool-profile full --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 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
├── reporter.py        # atomic report orchestration and exporter registry
├── resolver.py        # description → element (web + screen)
├── cli.py             # autonomous exploration and shared regression entry point
└── bench/             # deterministic capability + optional real-LLM harness
test-site/            # BuggyTasks  (22 mechanical bugs)
human-eye-fixture/    # DarkShop    (12 human-eye bugs)

実装の境界、テスト、拡張ポイントについては、まずアーキテクチャ、設計上の決定事項、 コントリビューションガイドをご覧ください。自律型の LiteLLM 探索ループは独立したワークフローです。 共有回帰テストが MCP サーバーをインポートしたり変更したりすることはありません。