GhostQA

SpecterQA

AI ペルソナがアプリを操作し、実際のユーザーがつまずかないようにします。

SpecterQA は、AI ペルソナをアプリケーション内で操作させます。画面を確認し、行動を決め、実際の人間のように操作します。テストスクリプトもセレクターも必要ありません。ペルソナとジャーニーを YAML で記述すれば、あとは SpecterQA が処理します。

$ specterqa run -p myapp

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ SpecterQA Run                                                    ┃
┃ Product: myapp   Budget: $5.00   Viewport: 1280x720            ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

  ✓ Step 1/4: Navigate to homepage       PASS   3.2s   $0.0081
  ✓ Step 2/4: Click signup link          PASS   2.1s   $0.0043
  ✓ Step 3/4: Fill registration form     PASS   8.7s   $0.0312
  ✓ Step 4/4: Verify dashboard loads     PASS   4.5s   $0.0127

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ALL TESTS PASSED                                                ┃
┃ Steps: 4/4   Findings: 0   Duration: 18.5s   Cost: $0.0563     ┃
┃ Run ID: GQA-RUN-20260222-143052-a1b2                            ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

---

これは何ですか？

従来の E2E テストは壊れやすいものです。セレクターを記述しても、すぐに動かなくなります。スクリプトを保守しても、すぐに陳腐化します。SpecterQA は異なるアプローチを採用しています。AI ビジョンモデルが実際の UI を確認し、人間と同じように操作します。

ペルソナ（アプリを利用する人）とジャーニー（その人が達成しようとしていること）を定義します。SpecterQA のエンジンはスクリーンショットを撮影し、Claude のビジョンモデルに送信します。モデルは判断（「このボタンをクリックする」「このフィールドに入力する」）を返し、エンジンは Playwright 経由で実行します。その後、もう一度スクリーンショットを撮影し、目標が達成されるか問題が発生するまで繰り返します。

問題が発生した場合は、証拠を確認できます。スクリーンショット、UX に関する観察結果、コストの内訳、重要度別に分類された調査結果が得られます。

インストール

SpecterQA は PyPI で配布されており、Python 3.10 以降が必要です。

pip install specterqa

インストール後、Playwright のブラウザーバイナリーをダウンロードします。

specterqa install

macOS ネイティブアプリのテストと iOS Simulator のサポートには、オプションの native エクストラをインストールします。

pip install specterqa[native]

MCP サーバーをサポートするには（Claude Desktop、Cursor、その他の MCP クライアントで SpecterQA をツールとして統合する場合）、次を実行します。

pip install specterqa[mcp]

テストを実行するには、Anthropic API キーも必要です。

export ANTHROPIC_API_KEY=sk-ant-...

インストールを確認するには、次を実行します。

specterqa --version
specterqa init       # scaffold a sample project
specterqa run -p demo

クイックスタート

pip install specterqa
specterqa install          # downloads Playwright browsers
specterqa init             # scaffolds .specterqa/ with sample configs
specterqa run -p demo      # runs the sample journey

Anthropic API キーが必要です。

export ANTHROPIC_API_KEY=sk-ant-...

これで完了です。3 つのコマンドと API キーだけで始められます。

仕組み

基本的なループはシンプルです。

screenshot --> vision model --> action decision --> execute --> repeat

1. スクリーンショット -- Playwright が現在のページの状態を PNG としてキャプチャします
2. 判断 -- Claude のビジョンモデルがスクリーンショット、ペルソナのコンテキスト、目標を受け取り、構造化された JSON アクション（click、fill、navigate、scroll、keyboard、wait、done、stuck）を返します
3. 実行 -- Playwright がアクションを実行します（座標を指定してクリック、テキスト入力、URL への移動など）
4. 繰り返し -- 目標が達成されるか、エージェントが行き詰まるか、予算が尽きるまでループします

ペルソナのプロフィールによって、AI の振る舞いが変わります。「技術に詳しい開発者」と「初めて利用する不満を抱えたユーザー」では、探索の仕方が異なります。ペルソナの忍耐力、技術への習熟度、不満点はすべて、システムプロンプトに影響します。

モデルの振り分けによって、コストを抑えられます。単純な操作（クリック、スクロール）には Haiku を使用します。複雑な操作（フォーム入力、初期評価）には Sonnet を使用します。また、単純なナビゲーションでは、簡単な操作をローカルの Ollama モデル（llava:13b）に振り分けることで、API コストをゼロにすることもできます。

特長

• ペルソナベースのテスト -- 背景、目標、不満、技術への慣れ具合を備えた AI ユーザーを定義できます。単にスクリプトに従うのではなく、画面に表示された内容に反応します。
• ビジョン機能を活用 -- セレクターも DOM クエリも不要です。AI が人間のようにスクリーンショットを解釈します。セレクターベースのテストでは見逃す視覚的な問題やレイアウトの問題も検出できます。
• YAML で設定 -- 製品、ペルソナ、ジャーニーはすべて YAML ファイルで管理します。PM でも内容を確認できます。保守するコードはありません。
• 予算の適用 -- 実行ごと、日ごと、月ごとのコスト上限を設定できます。上限に達するとエンジンが即時停止します。予想外の請求はありません。
• JUnit XML 出力 -- --junit-xml results.xml を追加すれば、あらゆる CI システムに接続できます。
• 段階的なモデルの振り分け -- 低コストのナビゲーションには Haiku、複雑な推論には Sonnet、単純なアクションにはオプションでローカルの Ollama を使用できます。
• マルチプラットフォーム -- Web アプリ（Playwright 経由）、macOS ネイティブアプリ（Accessibility API + pyobjc 経由）、iOS Simulator（simctl 経由）に対応しています。同じ YAML 形式で、ランナーを切り替えて利用できます。
• エビデンスの収集 -- 実行ごとにスクリーンショット、調査結果レポート、コストの内訳、構造化された JSON 結果が生成されます。すべてエビデンスディレクトリに保存されます。
• 行き詰まりの検出 -- AI が同じアクションを繰り返した場合や、UI に変化がない場合、エンジンはより高性能なモデルに切り替え、それでも解決しなければ中断します。無限ループは発生しません。
• テンプレート変数 -- ジャーニーのステップで {{persona.credentials.email}} を使用できます。実行時に、ペルソナ設定から変数が解決されます。
• 前提条件のチェック -- テスト実行前にサービスの稼働状況を確認できます。API 呼び出しを無駄にすることなく、明確なエラーを表示してすぐに失敗します。

設定

SpecterQA は、.specterqa/ に保存される 3 種類の YAML 設定ファイルを使用します。

製品（products/myapp.yaml）

product:
  name: myapp
  display_name: "My Application"
  base_url: "http://localhost:3000"

  services:
    frontend:
      url: "http://localhost:3000"
      health_endpoint: /

  viewports:
    desktop:
      width: 1280
      height: 720
    mobile:
      width: 375
      height: 812

  cost_limits:
    per_run_usd: 5.00

ペルソナ（personas/alex-developer.yaml）

persona:
  name: alex_developer
  display_name: "Alex Chen"
  role: "Full-Stack Developer"
  age: 28
  tech_comfort: high
  patience: medium
  preferred_device: desktop

  goals:
    - "Evaluate the app from a developer's perspective"
    - "Check for common UX anti-patterns"

  frustrations:
    - "Unclear error messages"
    - "Missing loading indicators"

  credentials:
    email: "[email protected]"
    password: "TestPass123!"

ジャーニー（journeys/onboarding.yaml）

scenario:
  id: onboarding-happy-path
  name: "Onboarding Happy Path"
  description: "New user signs up, completes onboarding, reaches dashboard."
  tags: [onboarding, critical_path, smoke]

  personas:
    - ref: alex_developer
      role: primary

  preconditions:
    - service: frontend
      check: /
      expected_status: 200

  steps:
    - id: visit_homepage
      mode: browser
      goal: "Navigate to the homepage and verify it loads"
      checkpoints:
        - type: text_present
          value: "Welcome"

    - id: navigate_signup
      mode: browser
      goal: "Find and click the signup link"

    - id: fill_signup_form
      mode: browser
      goal: "Complete the signup form with test credentials"

    - id: verify_dashboard
      mode: browser
      goal: "Verify signup succeeded and the dashboard loads"

詳しいリファレンスは docs/configuration.md を参照してください。

YAML スキーマのサポート

SpecterQA には、製品の YAML ファイル用の JSON Schema が schemas/product.schema.json に含まれています。

# yaml-language-server: $schema=../../schemas/product.schema.json

CI との統合

SpecterQA は CI 向けに構築されています。デフォルトでヘッドレス実行し、適切な終了コードを返します。

# Basic CI run
specterqa run -p myapp --junit-xml results.xml

# Smoke test (runs first scenario only, fast)
specterqa run -p myapp --level smoke --budget 2.00

# JSON output for programmatic consumption
specterqa run -p myapp --output json > results.json

終了コード：

• 0 -- すべてのテストに合格
• 1 -- 1 件以上のテストが失敗
• 2 -- 設定エラー
• 3 -- インフラストラクチャエラー（依存関係がない、API に到達できない）

GitHub Actions、GitLab CI、CircleCI の例は docs/ci-integration.md を参照してください。

コスト

SpecterQA は Anthropic の Claude API を使用します。実行ごとに費用が発生します。目安は以下のとおりです。

モデル	役割	入力（100 万トークンあたり）	出力（100 万トークンあたり）
Claude Haiku 4.5	単純なナビゲーション	$0.80	$4.00
Claude Sonnet 4	複雑な推論	$3.00	$15.00
Ollama llava:13b	ローカルのフォールバック	無料	無料

実行あたりの一般的なコスト：

• 3 ステップのスモークテスト：約 $0.30-0.60
• 5 ステップの標準的なジャーニー：約 $0.50-1.50
• フォームを含む複雑な 10 ステップのジャーニー：約 $1.00-3.00

デフォルトの予算は実行あたり $5.00です。予算を超えるとエンジンは即時停止し、超過を通知せずに続行することはありません。日ごと、月ごとの上限も設定できます。

毎回 --budget を渡さずに済むよう、環境変数でデフォルトの予算を設定することもできます。

export SPECTERQA_BUDGET=2.00
specterqa run -p myapp          # uses $2.00 budget
specterqa run -p myapp --budget 5.00  # uses $5.00 budget (CLI flag wins)

モデルの振り分けもコスト削減に役立ちます。単純なクリックやスクロールには Haiku（アクションあたり約 $0.01）、フォーム入力や初期評価には Sonnet（アクションあたり約 $0.03-0.05）を使用します。ローカルの Ollama インスタンスがあれば、単純なアクションをそこに振り分けて API コストをゼロにできます。

詳しいコストの内訳と予算設定の方法は docs/cost-guide.md を参照してください。

マルチプラットフォーム

SpecterQA はウェブ専用ではありません。同じペルソナ／ジャーニーの YAML 形式で、複数のプラットフォームに対応します。

ウェブアプリ（デフォルト） -- ブラウザーの自動化には Playwright を使用します。

macOS ネイティブアプリ -- pyobjc 経由で macOS Accessibility API を使用します。AI はアクセシビリティツリーとスクリーンショットを読み取り、AX アクションを通じてクリックとキー入力を実行します。

product:
  name: my-mac-app
  app_type: native_macos
  app_path: /Applications/MyApp.app
  bundle_id: com.example.myapp

iOS シミュレーター -- スクリーンショットとタッチ操作のシミュレーションに simctl を使用します。物理デバイスを使わずに iOS アプリをテストするのに便利です。

product:
  name: my-ios-app
  app_type: ios_simulator
  bundle_id: com.example.myiosapp
  simulator_device: "iPhone 15 Pro"
  simulator_os: "17.2"

ネイティブアプリとシミュレーターのサポートには、オプションの依存関係 native が必要です。

pip install specterqa[native]

AI エージェント向け

AI エージェントを使用している場合や、エージェント向けツールを構築している場合、SpecterQA はプログラムから利用できる構造化インターフェースを提供します。

JSON 出力対応の CLI

specterqa run -p myapp --output json

構造化された JSON を標準出力に返します。

{
  "passed": true,
  "run_id": "GQA-RUN-20260222-143052-a1b2",
  "step_reports": [
    {
      "step_id": "visit_homepage",
      "passed": true,
      "duration_seconds": 12.3
    }
  ],
  "findings": [],
  "cost_usd": 0.4521
}

Python API

from specterqa.config import SpecterQAConfig
from specterqa.engine.orchestrator import SpecterQAOrchestrator

config = SpecterQAConfig()
config.project_dir = Path(".specterqa")
config.products_dir = Path(".specterqa/products")
config.personas_dir = Path(".specterqa/personas")
config.journeys_dir = Path(".specterqa/journeys")
config.evidence_dir = Path(".specterqa/evidence")
config.anthropic_api_key = "sk-ant-..."
config.budget = 5.00
config.headless = True

orchestrator = SpecterQAOrchestrator(config)
report_md, all_passed = orchestrator.run(product="myapp", level="smoke")

フェデレーションプロトコル

SpecterQA には protocols.py モジュールがあり、Python の Protocol クラス（AIDecider、ActionExecutor）を提供します。これにより、独自の AI モデルやアクションバックエンドに差し替えられます。

from specterqa.engine.protocols import AIDecider, Decision

class MyCustomDecider:
    def decide(self, goal, screenshot_base64, **kwargs) -> Decision:
        # Your logic here
        ...

MCP サーバー

SpecterQA には MCP（Model Context Protocol）サーバーが付属しています。MCP 互換のエージェント（Claude Desktop、Cursor、Cline、カスタムのエージェント向けツールなど）は、CLI を呼び出さずに SpecterQA をツールとして検出し、実行できます。テストの実行、結果の読み取り、設定の管理などが可能です。

MCP クライアントの設定（claude_desktop_config.json など）に追加します。

{
  "specterqa": {
    "command": "specterqa-mcp",
    "args": []
  }
}

利用可能なツール：

ツール	説明
specterqa_run	製品に対して動作テストを実行します。同期処理のため、45～300 秒かかる場合があります。API コストが発生します（デフォルトの予算：$5.00）。
specterqa_list_products	設定済みの製品と、利用可能なジャーニーを一覧表示します
specterqa_get_results	実行 ID を指定して、以前の実行結果の構造化データ全体を取得します
specterqa_init	新しい SpecterQA プロジェクトディレクトリを初期化します

プログラム向け API のリファレンス全体と MCP 統合の詳細については、docs/for-agents.md を参照してください。

API リファレンス

完全な API リファレンスは specterqa.synctek.io/docs で確認できます。

主なクラス

クラス	モジュール	説明
SpecterQAConfig	specterqa.config	ルート設定オブジェクトです。プロジェクトディレクトリ、API キー、予算、モデルのルーティング設定を指定します。
SpecterQAOrchestrator	specterqa.engine.orchestrator	プログラムから実行する際のメインエントリーポイントです。orchestrator.run(product, level) を呼び出してジャーニーを実行します。
AIDecider	specterqa.engine.protocols	Protocol クラスです。独自のビジョンモデルや判断バックエンドに差し替える場合に実装します。
ActionExecutor	specterqa.engine.protocols	Protocol クラスです。独自のアクション実行バックエンドに差し替える場合に実装します（例：Playwright の置き換え）。
RunReport	specterqa.models	orchestrator.run() が返す構造化された結果です。ステップレポート、検出事項、コストの内訳が含まれます。
Finding	specterqa.models	実行中に記録された個別の UX 問題です。重要度、ステップ ID、スクリーンショットの参照先、説明が含まれます。

CLI リファレンス

コマンド	説明
specterqa run -p PRODUCT	製品のすべてのジャーニーを実行します
specterqa run -p PRODUCT --level smoke	smoke タグ付きのジャーニーのみを実行します
specterqa run -p PRODUCT --junit-xml results.xml	CI 用に JUnit XML を出力します
specterqa run -p PRODUCT --output json	構造化された JSON を標準出力に出力します
specterqa init	サンプル設定を含む .specterqa/ プロジェクトディレクトリを生成します
specterqa install	Playwright のブラウザーバイナリをダウンロードします
specterqa list	設定済みの製品とジャーニーを一覧表示します
specterqa results RUN_ID	以前の実行のレポート全体を表示します
specterqa-mcp	MCP サーバーを起動します

MCP ツール

ツール	説明
specterqa_run	動作テストを実行します。パラメーター：product（str）、level（str、任意）、directory（str、任意）。RunReport JSON オブジェクトを返します。
specterqa_list_products	すべての製品と設定済みのジャーニーを一覧表示します。パラメーターは不要です。
specterqa_get_results	run_id を指定して、以前の実行レポートを取得します。
specterqa_init	指定した directory に新しい SpecterQA プロジェクトを初期化します。

スキーマ定義、型スタブ、フェデレーションプロトコルの詳細については、docs/for-agents.md を参照してください。

セキュリティ

ディレクトリアクセス： 環境変数 SPECTERQA_ALLOWED_DIRS が設定されていない場合、SpecterQA MCP サーバーは、プロセスがアクセス可能なファイルシステム上の任意のパスを specterqa_run の directory パラメーターに指定できます。共有環境やマルチユーザー環境、または MCP サーバーが信頼できないエージェントに公開される環境では、この変数に明示的な許可リストを設定してください。

export SPECTERQA_ALLOWED_DIRS="/home/user/projects:/ci/workspaces"

設定すると、MCP サーバーは、指定されたプレフィックスのいずれかに含まれない directory の値を拒否します。これにより、SECURITY_ADVISORY.md（GHSA-SPECTERQA-001）で説明されている MCP のディレクトリトラバーサルの脆弱性を緩和できます。

コマンドインジェクションの修正（v0.2.1）： 製品 YAML のサービス定義から check_command フィールドが削除されました。このフィールドは重大なコマンドインジェクション脆弱性の原因でした。現在、事前条件チェックは安全な TCP 接続チェックと HTTP ヘルスエンドポイントチェックに限定されています。詳細は SECURITY_ADVISORY.md を参照してください。

認証情報の除去： 実行時の成果物（JSON 結果ファイル、ログ出力）は、ディスクに書き込む前に、取得したコンテンツから既知の認証情報パターン（API キー、トークン、パスワード）を自動的に除去します。

脆弱性の報告： セキュリティ上のバグについて、公開の課題を作成しないでください。[email protected] にメールするか、開示ポリシーの全文を SECURITY.md で確認してください。

制限事項

このソフトウェアでできることとできないことを正直に把握してください。

• Anthropic API キーが必要です。 API キーがなければテストできません。SpecterQA 自体には無料プランがありません。
• 費用がかかります。 実行のたびに API 呼び出しが発生します。一般的な 3 ステップのジャーニーでは、0.30～0.60 ドルかかります。予算制限により想定外の出費を防げますが、費用は常に発生しています。
• ビジョンモデルは完璧ではありません。 AI が小さな文字を読み間違えたり、誤った要素をクリックしたり、複雑なレイアウトに混乱したりすることがあります。性能は良好ですが、間違いがないわけではありません。偽陽性や偽陰性が発生する場合があります。
• 単体テストの代わりにはなりません。 SpecterQA は、動作に関する UX フローをテストします。ビジネスロジック、データの整合性、エッジケースの処理はテストしません。既存のテストスイートの代わりではなく、併用してください。
• macOS のネイティブテストには pyobjc が必要です。 specterqa[native] エクストラをインストールすると、pyobjc パッケージ（約 200 MB）が追加されます。macOS ネイティブおよび iOS Simulator のテストにのみ必要です。
• アルファ版ソフトウェアです。 バージョン 0.4.0 です。API やファイル構成が変更される可能性があります。未完成な部分があることをご了承ください。
• 現時点では、ジャーニーごとにペルソナは 1 つです。 複数のペルソナによる並行テスト（例：2 人のユーザー間のチャットのシミュレーション）はロードマップにありますが、まだサポートされていません。
• 決定論的な再現は困難です。 AI が実行時に判断するため、アクションの正確な順序は実行ごとに異なります。同じジャーニー、同じペルソナでも、クリックが少し異なります。これはより多くの問題を検出するための設計ですが、完全に同じ状態を再現するのは難しくなります。

貢献

貢献を歓迎します。リポジトリは github.com/SyncTek-LLC/specterqa にあります。

git clone https://github.com/SyncTek-LLC/specterqa.git
cd specterqa
pip install -e ".[dev]"
pytest

大規模な PR に着手する前に、課題を作成してください。まずはアプローチについて相談したいと考えています。

ライセンス

MIT -- 詳細は LICENSE を参照してください。

---

SyncTek LLC が開発しました。