AWT (AI Watch Tester)

AWT — AI コーディングツールの目と手

AI コーディングツールは賢いですが、Web ページを見たりクリックしたりすることはできません。 AWT は実際のブラウザーを使えるようにし、指一本動かさなくてもテストやバグの発見、修正を行えるようにします。

AI API なしで動作します — YAML シナリオを手動で作成して、aat run を実行してください。API キーは不要です。AI コーディングツールがあると作業が簡単になりますが、必須ではありません。

---

AWT とは？

AWT は、AI を活用した E2E テストの実行エンジンです。AI コーディングツールがテストを設計し、AWT が Playwright を使って実際のブラウザーで実行します。

スキルモードの仕組み（追加の AI API キーは不要です）：

You: "Test the login flow on https://mysite.com"

Your AI coding tool:
  → Writes 5 YAML scenarios (30 steps)
  → Runs: aat run scenarios/
  → Reads failure: "Step 4: Dashboard text not visible"
  → Reads screenshot + source code
  → Fixes src/pages/login.js:23
  → Re-runs: aat run scenarios/
  → All 5 scenarios pass ✓

主な機能：

• 実行 — 人間のようなマウスやキーボードの操作で、実際のブラウザー上でテストを実行します
• 確認 — スクリーンショットを撮影し、OCR と画像マッチングで要素を検出します
• レポート — エラーの詳細とスクリーンショットを含む、ステップごとの成功・失敗を報告します
• 自己修復（CLI モード）— aat loop が独自の AI で失敗を自動修正します
• 学習 — 成功したマッチングを SQLite に保存し、使うほど処理が速くなります

インストール

まず aat コマンドをインストールしてください。以下のすべての方法で、このコマンドを使用します。

pip install aat-devqa
python -m playwright install chromium

Claude Code プラグイン（推奨）

このリポジトリはプラグインのバンドルです。awt スキルと、aat_* ツールを公開する MCP サーバーが含まれているため、一度のインストールで両方を利用できます。

claude plugin marketplace add ksgisang/awt-skill
claude plugin install ai-watch-tester@awt

MCP サーバーには Python MCP SDK が必要です。

pip install "mcp[cli]>=1.0.0"

インストールされた内容を確認してください。

claude plugin details ai-watch-tester@awt

Skills (1) awt と MCP servers (1) awt が表示されます。

スキルのみ

MCP サーバーを含めずにスキルだけを利用する場合：

npx skills add ksgisang/awt-skill --skill awt -g

または、グローバルもしくはプロジェクトごとに手動でコピーできます。

git clone https://github.com/ksgisang/awt-skill.git /tmp/awt-skill
cp -r /tmp/awt-skill/skills/awt ~/.claude/skills/awt   # or .claude/skills/awt
rm -rf /tmp/awt-skill

インストール後、テスト関連のプロンプトでスキルが自動的に起動します。

更新

claude plugin update ai-watch-tester@awt          # plugin
npx skills add ksgisang/awt-skill --skill awt -g -y  # skill only

手動でコピーしてインストールした場合：cd ~/.claude/skills/awt && git pull

他のテスト用スキルとの比較

機能	webapp-testing	playwright-skill	AWT
シナリオ形式	Python スクリプト	Python スクリプト	宣言型 YAML
コード不要のテスト作成	いいえ	いいえ	はい
自然言語 → テスト	いいえ	いいえ	はい
自己修復ループ	いいえ	いいえ	はい（DevQA ループ）
失敗時の自動修正	いいえ	いいえ	はい（AI → PR）
ビジュアルマッチング（OpenCV + OCR）	いいえ	いいえ	はい（OpenCV + OCR）
パターン学習	いいえ	いいえ	はい（SQLite）
サーバーのライフサイクル管理	はい	はい	はい（aat dashboard）
複数の AI プロバイダー	いいえ	いいえ	はい（5 プロバイダー）
人間のような操作	いいえ	いいえ	はい（ベジェ曲線マウス）
承認モード	いいえ	いいえ	はい（手動／ブランチ／自動）
コスト最適化	該当なし	該当なし	0.02～0.05 ドル／テスト
ライブスクリーンショット	いいえ	スクリーンショットのみ	はい（WebSocket ストリーム）
多言語 OCR	いいえ	いいえ	はい（10 以上の言語）
オフライン対応	いいえ	いいえ	はい（Ollama）
コスト追跡	いいえ	いいえ	はい（呼び出しごとのログ記録 + aat cost）
ソースコード分析	いいえ	いいえ	はい（スキル限定）
シナリオのキャッシュ	いいえ	いいえ	はい（同じ仕様なら再呼び出しなし）
ブラウザーテストのオーバーレイ	いいえ	いいえ	はい（ステップの進行状況をライブ表示）
依存関係の順序指定	いいえ	いいえ	はい（depends_on フィールド）
スキルモード（追加の AI コストなし）	いいえ	いいえ	はい
Canvas／Flutter の OCR フォールバック	いいえ	いいえ	はい（自動）
プラットフォームの自動検出	いいえ	いいえ	はい（7 フレームワーク）
構造化された失敗診断	いいえ	いいえ	はい（AI に依存しない）
複数ドキュメントの YAML	いいえ	いいえ	はい（--- 区切り）
厳密な検証	いいえ	いいえ	はい（aat validate --strict）

それぞれの使いどころ：

• webapp-testing — シンプルなページチェック用の、すぐに使える Playwright スクリプト
• playwright-skill — Playwright API をきめ細かく制御する必要がある場合
• AWT Skill Mode — AI コーディングツールがテストを設計し、AWT が実行します。追加の AI API キーは不要です。
• AWT CLI Mode — aat generate と aat loop を使った、CI/CD 向けの単体で動作する自動テスト

対応している AI コーディングツール

AWT は Agent Skills open standard に準拠しており、次のツールで動作します。

ツール	ステータス
Claude Code	対応
Cursor	互換
Codex	互換
Gemini CLI	互換
Amp	互換
Cline	互換
Aider	互換
Windsurf	互換
Roo Code	互換
PearAI	互換
Antigravity	対応

簡単な例

YAML シナリオ

id: "SC-001"
name: "User Login"
tags: ["auth", "login"]
depends_on: ["SC-000"]
steps:
  - step: 1
    action: navigate
    value: "{{url}}/login"
    description: "Go to login page"

  - step: 2
    action: find_and_type
    target:
      text: "Email"
      match_method: ocr
    value: "[email protected]"
    humanize: true
    description: "Enter email"

  - step: 3
    action: find_and_click
    target:
      text: "Login"
    description: "Click login button"

  - step: 4
    action: assert
    assert_type: text_visible
    expected:
      - type: text_visible
        value: "Welcome back"
    description: "Verify login success"

自然言語（Claude Code 内）

「[email protected] で mysite.com にログインして、ダッシュボードが読み込まれるか確認してください」

AWT はこれを YAML シナリオに変換し、自動的に実行します。

DevQA の 5 ステップのワークフロー

Scan → Plan → Review → Execute → Heal
  ↑                                 |
  └─── Loop back on failure ────────┘

1. スキャン — サイトをクロールし、DOM を分析して、機能を検出します
2. 計画 — AI が YAML テストシナリオを生成します
3. レビュー — 実行前にユーザーが確認・編集します
4. 実行 — Playwright がライブスクリーンショットを取得しながら実行します
5. 修復 — AI が失敗を分析 → 修正を提案 → 再テストします

AI プロバイダー

プロバイダー	ビジョン	コスト	オフライン
Claude（デフォルト）	対応	中	いいえ
OpenAI（GPT-4o）	対応	高	いいえ
Gemini（デフォルト：無料）	対応	無料枠	はい
DeepSeek	非対応	低	いいえ
Ollama	非対応	無料	はい

プロジェクト構成

awt-skill/                      # ← this repository is the plugin folder
├── .claude-plugin/
│   ├── plugin.json             # Plugin manifest
│   └── marketplace.json        # Marketplace entry for this one plugin
├── .mcp.json                   # Declares the bundled MCP server
├── skills/
│   └── awt/                    # ← Skill content (installed by npx skills)
│       ├── SKILL.md            # Main skill definition
│       ├── references/
│       │   ├── scenario-schema.md  # Full YAML schema reference
│       │   ├── cli-reference.md    # CLI command reference
│       │   └── config-reference.md # Configuration options
│       └── templates/
│           ├── scenario-template.yaml
│           └── config-template.yaml
├── mcp/
│   ├── server.py               # MCP server — the 12 aat_* tools
│   └── requirements.txt
├── server.json                 # MCP Registry entry
├── README.md
├── LICENSE
├── CONTRIBUTING.md
└── package.json

主な CLI コマンド

コマンド	説明
aat doctor	環境（Python、Playwright、Tesseract、AI）を確認します
aat init	プロジェクトの初期化、AI のセットアップ、環境チェックを行います
aat setup	AI プロバイダーと API キーを設定します
aat generate	AI でシナリオを生成します（コスト見積もりとキャッシュ機能付き）
aat run --learn	テストを実行し、修正から学習します（必ず --learn を使用してください）
aat loop	自己修復型 DevQA ループ
aat cost	AI API の使用コストを確認します
aat validate --strict	YAML と品質チェックを検証します
aat learn platform -p <key> -t <tip>	プラットフォーム固有のヒントを追加します

システム依存関係

macOS：

brew install [email protected] tesseract
pipx install aat-devqa
playwright install chromium

Linux（Ubuntu/Debian）：

sudo apt install python3.12 python3.12-venv tesseract-ocr
pipx install aat-devqa
playwright install chromium

Windows：

winget install Python.Python.3.12
choco install tesseract
pip install aat-devqa
playwright install chromium

インストール後、aat doctor を実行して、すべてが正常に動作することを確認してください。

OCR 言語パック。 Tesseract のインストールでは英語のみが追加されます。 別の言語のアプリをテストする場合は、その言語のパックもインストールしてください。インストールしないと、OCR にフォールバックするテキストのアサーションで、画面上にはっきり表示されているテキストに対しても not visible on page と報告されます。aat doctor が不足しているパックを示します。

brew install tesseract-lang                 # macOS, all languages
sudo apt install tesseract-ocr-kor          # Linux, one language

このプラグインの実行内容、送信内容、取得内容

以下はすべて、このリポジトリ内の読み取り可能なソースコードで確認できます。インストール時に、難読化されたコード、コンパイル済みコード、ダウンロードされたコードが実行されることはありません。

お使いのマシン上で実行されます。 mcp/server.py は python3 で起動し、引数リストを作成して、pip install aat-devqa でインストールした aat コマンドをサブプロセスとして実行するだけです。シェルは実行しないため、受け取った内容がコマンドとして再解析されることはありません。aat は Playwright を通じてローカルの Chromium を操作し、OCR にはローカルの tesseract バイナリを使用します。

ディスクに書き込みます。 プロジェクト内には、.aat/（設定、実行履歴、スクリーンショット、SQLite 学習データベース、追記専用の監査ログ）と reports/ が作成されます。ホームディレクトリには、セレクターが機能しなくなった後にターゲットを再検出できるよう、AWT が保存する要素画像の格納先として ~/.awt/templates/<host>/ が作成されます。

ネットワーク経由で送信します。 テレメトリーや分析情報の送信はありません。以下の送信先は、すべてお客様自身が指定したものか、AWT が自動で行う唯一の通信です。埋もれないよう、自動で行われる通信を先に記載しています。

• AWT 自身が 1 日に 1 回、api.github.com にアクセスします。 CLI は最新リリースを確認し、新しいバージョンがある場合にヒントを表示します。リクエストボディ、アカウント、マシン ID、バージョン文字列、テスト対象に関する情報は一切含まれません。すべてのユーザーに対して同一のリクエストです。3 秒でタイムアウトし、すべてのエラーは無視されるため、このホストへのアクセスをブロックしても問題はありません。AWT が開始する通信はこれだけです。
• テスト対象のサイト。 Chromium はシナリオで指定された URL を読み込みます。これがツールの目的であり、テスト実行時にほかのサイトへアクセスすることはありません。
• 必要なコマンドでのみ使用する AI プロバイダー — aat generate、aat loop、aat devqa、および Vision マッチング。リクエストにはページのテキストまたはスクリーンショットと、お客様のシナリオが含まれます。プロバイダーはお客様が選択し、キーもお客様が指定します。Ollama の場合、リクエストがマシンの外部に送信されることはありません。通常の aat run は AI プロバイダーに一切アクセスしません。
• 入力した URL（到達可能かどうかの確認用） — aat doctor と aat start は指定されたアドレスにリクエストを送信し、応答の有無を報告します。
• 開発サーバーの検出用の http://localhost:<port> — aat devqa はローカルポートのみをプローブします。
• お客様自身のシナリオに記載したエンドポイント。 api_call タイプの teardown ステップは、YAML に記載された URL のみにアクセスします。これにより、実行後にテストデータをクリーンアップします。

PRIVACY.mdには、これらの各項目に対応するファイル名と行番号が記載されています。

実行時の取得内容。 何もありません。このプラグインはインストール後にコードをダウンロードしません。

承認。 aat run は /dev/tty を直接読み取って確認を求めるため、パイプ経由の標準入力から承認を与えることはできません。また、すべての試行が .aat/audit.log に記録されます。--auto-approve フラグはなく、AI エージェントがお客様に代わって承認する方法もありません。デフォルトの manual モードでは、AI が提案したシナリオの変更がファイルに書き込まれることはありません。

リンク

• メインリポジトリ： github.com/ksgisang/AI-Watch-Tester
• クラウドデモ： ai-watch-tester.vercel.app
• エージェントスキル標準： agentskills.io

ライセンス

AGPL-3.0 — 全文については LICENSE ファイルをご覧ください。

AILoopLab が開発しました。