bug0inc/qa-agent

Bug0 AI – AI駆動のPlaywright回帰テスト

概要 – Playwrightブラウザテストを自然言語で記述できるオープンソースのTypeScriptライブラリです。各ステップをLLM（Claude、Gemini、OpenAIのcomputer-use agentなど）に送信し、アクションを取得してブラウザで実行し、マルチモデル合意エンジンで結果を検証します。また、成功したステップをRedisにキャッシュするため、後続の実行が高速かつ低コストになります。

主な機能

機能	仕組み
自然言語ステップ	runSteps() は {description, data?, waitUntil?, ai?} オブジェクトの配列を受け取ります。説明は平易な英語（例: “Click Acme Circles T-Shirt”）です。ライブラリがプロンプトをフォーマットし、設定されたLLMを呼び出し、モデルの応答をPlaywrightアクションに変換します。
マルチモデルアサーションエンジン	各 assertion に対して、ライブラリはClaudeとGeminiを並行して呼び出します。意見が一致しない場合、3番目の「仲裁」モデル（設定可能）が決定を下すか、即座に失敗 (fail-on-disagreement) させることができます。
スマートキャッシュ	成功したステップの実行結果は、userFlow + step.description をキーとしてRedisに保存されます。キャッシュヒット時はLLM呼び出しなしでステップがリプレイされるため、レイテンシとコストが大幅に削減されます。
自動修復	キャッシュされたステップが失敗した場合、ライブラリはLLMにフォールバックしてアクションを再計算し、キャッシュを更新します。
ビデオアサーション	アサーションにオプションの video: true を設定すると、ステップ実行全体が記録され、.webm がGeminiのFiles APIにアップロードされます。Geminiはビデオに基づいてアサーションを評価します（トースト通知のような一時的なUIに便利です）。
AIゲートウェイサポート	Vercel AI Gateway、OpenRouter、Cloudflare AI Gateway経由でLLM呼び出しをルーティングするか、プロバイダー（Anthropic、Google、OpenAI）と直接通信できます。
CUAモード	mode: "cua" を選択すると、OpenAIのcomputer-use agent (gpt-5.5 + 内蔵 computer ツール) を使用した、視覚的でスクリーンショット駆動の自動化が行われます。
動的プレースホルダー	{{run.*}}、{{global.*}}、{{data.*}}、{{email.*}} を使用して、ランダムなメールアドレス、ID、または受信メールから抽出した値をステップに注入できます。
テレメトリとログ	オプションのOpenTelemetryトレース (Axiom) および構造化されたPinoログ。
メール抽出	内蔵の emailsink プロバイダー（使い捨て受信トレイ）またはカスタムプロバイダーを使用して、認証コードなどを取得できます。

典型的なワークフロー

1. Playwrightプロジェクトの作成 – npm init playwright@latest bug0-ai-project (TypeScriptを選択)。
2. ライブラリのインストール – npm install @bug0/ai dotenv。
3. LLM認証情報の追加 – 少なくとも1つのAnthropicキーと1つのGoogle Generative AIキー（またはゲートウェイ）が必要です。.env ファイルに追加します。
4. 設定 – テストスイートの先頭で configure({ ai: { gateway: "vercel", models: { … } }, redis: { url }, telemetry: { … } }) を呼び出します。
5. テストの記述 – runSteps({ page, userFlow, steps, assertions, test, expect }) を使用します。各ステップは平易な英語の説明で、アサーションも自然言語の文字列です。
6. 実行 – npx playwright test example.spec.ts --project chromium。レポートにはAIが生成した要約が含まれます。

テスト例 (TypeScript)

import { test, expect } from "@playwright/test";
import { runSteps, configure } from "@bug0/ai";

configure({
  ai: { gateway: "vercel" },
});

test("Shopping cart", async ({ page }) => {
  await runSteps({
    page,
    userFlow: "Add product to cart",
    steps: [
      { description: "Navigate to https://demo.vercel.store" },
      { description: "Click Acme Circles T-Shirt" },
      { description: "Select color", data: { value: "White" } },
      { description: "Add to cart", waitUntil: "My Cart is visible" },
    ],
    assertions: [{ assertion: "You can see My Cart with Acme Circles T-Shirt" }],
    test,
    expect,
  });
});

設定のポイント

• モデルスロット – 8つのスロット（ステップ実行、ユーザーフロー低/高、プライマリ/セカンダリ/仲裁アサーション、ユーティリティ、CUA）。デフォルトは低コストステップ用にGemini-flash、プライマリ用アサーションにClaude-4.5-haikuが設定されています。
• Redis – REDIS_URL を設定するか、configure({ redis: { url } }) を渡してキャッシュとグローバルプレースホルダーを有効にします。
• ゲートウェイ – 選択したゲートウェイに応じて AI_GATEWAY_API_KEY、OPENROUTER_API_KEY などを設定します。
• CUAモード – computer ツールへのアクセス権を持つ OPENAI_API_KEY が必要です。mode: "cua" および gateway: "none" を設定してください。
• テレメトリ – AXIOM_TOKEN/AXIOM_DATASET を提供するか、プログラムで設定してOpenTelemetryトレースを取得します。

対象ユーザー

• AIエージェント（例: Bug0のFactoryKit）でUIコードを生成しており、頻繁なDOM変更に耐えられる回帰テストスイートが必要なチーム。
• 壊れやすいセレクターを維持することなく、迅速にテストを記述したいQAエンジニア。
• LLM駆動の自動化と、キャッシュやビデオキャプチャといった従来のPlaywrightの信頼性機能を組み合わせたい開発者。

READMEに記載されている制限事項

• テストスイート自体はまだ小規模です。エッジケースのカバーを歓迎します。
• ビデオアサーションはゲートウェイをバイパスするため、直接のGoogle APIキーが必要です。
• CUAモードはゲートウェイと混在できません。OpenAIと直接通信する必要があります。
• マルチステップキャッシュは未実装です（単一ステップのアクションのみキャッシュされます）。

ライセンス – FSL-1.1-ALv2（寛容なオープンソースライセンス）。

---

上記のすべての情報はリポジトリのREADMEから直接取得したものであり、追加の機能は推測されていません。