uiai Web Test

自然言語でテストシナリオを記述し、PlaywrightでWebアプリケーションのUIテストを自動実行するスキル。

特徴

• 自然言語シナリオ - セレクタ不要、日本語でアクションを記述
• 自動要素特定 - アクセシビリティツリーから自動的にクリック位置を判定
• Vision検証 - Claude Visionで期待結果を自然言語で検証
• 厳格モード - DOMのテキスト完全一致で厳密に検証可能
• マルチブラウザ - Chromium, Firefox, WebKit対応

シナリオ形式

name: "ログインテスト"
app:
  android: "com.example.app"
  ios: "com.example.App"
  web: "https://example.com"

steps:
  - id: "ログイン"
    actions:
      - do: "Open /login page"
      - do: "Enter '[email protected]' in email field"
      - do: "Enter 'password123' in password field"
      - do: "Click 'Login' button"
      - then: "Dashboard is displayed"
        strict: true

使用方法

# テスト実行
/uiai-web-test scenarios=test/scenarios/login.yaml

# 複数シナリオ
/uiai-web-test scenarios=test/scenarios/*.yaml

# ブラウザ指定
/uiai-web-test scenarios=test/scenarios/login.yaml browser=firefox

# ヘッドレスモード無効（ブラウザ表示）
/uiai-web-test scenarios=test/scenarios/login.yaml headless=false

# 厳格モード（全ステップで完全一致検証）
/uiai-web-test scenarios=test/scenarios/login.yaml strict=true

Execution Requirement (MUST)

各シナリオは必ずTaskツールでサブエージェントとして実行すること。

for each scenario_file:
  1. Task tool → web-test-runner (実行)
  2. Task tool → web-test-evaluator (評価)

複数シナリオがある場合、各シナリオを独立したTaskとして実行する。これにより：

• コンテキスト分離（シナリオ間の状態汚染を防止）
• エラー隔離（1シナリオの失敗が他に影響しない）
• 並列実行可能（独立したシナリオは同時実行可）

詳細は [execution-flow.md](./references/execution-flow.md) を参照。

ステップの書き方

アクション（do）

検証（then）

厳格モード（strict）

通常はVision APIで「意味的に」検証するが、strict: true を指定するとDOMのテキスト完全一致で検証する。

# シナリオ全体に適用
config:
  strict: true

# または do/then 個別に適用
steps:
  - id: "確認"
    actions:
      - do: "Click 'Submit' button"
        strict: true  # このdoのみ厳格に要素特定
      - then: "'Order confirmed' is displayed"
        strict: true  # このthenのみ完全一致検証

strictの優先順位: 個別指定 > config.strict > false（デフォルト）

セクションID（id）

テストをグループ化するための識別子。各セクションは actions リストを持つ：

steps:
  - id: "ログイン"
    actions:
      - do: "..."
      - then: "..."

  - id: "データ確認"
    actions:
      - do: "..."
      - then: "..."

リプレイ（replay）

過去のセクションの do アクションを再実行する。then はスキップされる。

steps:
  - id: "ログイン"
    actions:
      - do: "Open /login"
      - do: "Click 'Login' button"
      - then: "Dashboard is displayed"

  - id: "リプレイ確認"
    replay:
      from: "ログイン"
      to: "ログイン"
    actions:
      - then: "再実行後も正常に動作すること"

注意: リプレイ先に replay がある場合は再帰的に実行される。

Web固有の注意事項

ナビゲーション

要素特定

PlaywrightはアクセシビリティツリーとDOMを使用して要素を特定：

待機処理

Playwrightは自動待機が組み込まれているため、多くの場合明示的な待機は不要：

# 自動待機される操作
- do: "Click 'Submit' button"  # 要素が表示されるまで自動待機

# 明示的な待機が必要な場合
- do: "Wait 3 seconds"         # 固定時間待機
- do: "Wait for loading to finish"  # ローディング完了を待機

内部処理

1. ページ取得 - page.goto(url) でページを開く
2. 要素特定 - 自然言語の説明からUI要素を自動特定

- テキスト一致: 「Login」→ getByText('Login') または getByRole('button', { name: 'Login' }) - ラベル一致: 「email field」→ getByLabel('email') または getByPlaceholder('email')

1. アクション実行 - click(), fill(), selectOption() 等を実行
2. 検証 - スクリーンショット + Vision APIで期待結果を確認

出力

.web-test/
└── results/
    └── <timestamp>/
        ├── summary.md           # 全体サマリー
        └── <scenario-name>/
            ├── report.md        # テストレポート
            ├── result.json      # 結果JSON
            ├── step_01_before.png  # スクリーンショット（実行前）
            ├── step_01_after.png   # スクリーンショット（実行後）
            ├── step_01_dom.html    # DOM スナップショット
            └── step_01_a11y.json   # アクセシビリティツリー

前提条件

• Node.js がインストールされていること（v16以上推奨）
• Playwright がインストールされていること

# Playwrightのインストール
npm install -D playwright

# ブラウザのインストール
npx playwright install

関連エージェント

• web-test-runner - テスト実行とエビデンス収集
• web-test-evaluator - 結果評価とレポート生成

リファレンス

• [シナリオスキーマ](./references/scenario-schema.md)
• [Playwrightコマンド](./references/playwright-commands.md)
• [環境チェック](./references/environment.md)
• [実行フロー](./references/execution-flow.md)