fv-testlab-client

fv-test-lab のクライアント側ツール一式です。任意のプロジェクトに導入し、API キーで fv-test-lab（サーバ）に接続して E2E テストを 作成・実行・確認 します。

• src/ — MCP サーバ（stdio）。npx fv-testlab-mcp で起動。
• skills/ — Claude Code 用の skill 群（下記「skill 一覧」参照）。

サーバ（プラットフォーム）本体は別リポジトリです。このリポジトリは「テストを書く側」が使う 消費者向けクライアントで、秘密情報を含みません（FVTL_API_KEY は環境変数で渡します）。

全体像

[あなたの作業リポジトリ]
  ├─ .mcp.json               ← MCP サーバ（fv-testlab-mcp）を登録
  ├─ .claude/skills/         ← 必要な skill をコピー（下記一覧）
  └─ e2e/                    ← skill が生成するテスト仕様書・同期マニフェスト
       ├─ it/  st/           ← IT/ST テスト仕様書（fvtl-spec）
       ├─ fvtl-setup.md      ← 環境構築指示書（fvtl-setup）
       └─ .fvtl/sync.json    ← 同期マニフェスト（fvtl-sync）

Claude Code ──(MCP: register_test / run_case / …)──▶ fv-test-lab /api/v1 ──▶ 実ブラウザ実行(Batch)

skill 一覧

| skill | 役割 | 主な起動フレーズ | |-------|------|----------------| | fvtl-setup | fv-test-lab 側の環境構築指示書を生成（アプリ・アカウント・DB接続・テストファイルの差分チェックリスト） | 「testlab の環境構築指示書を作って」 | | fvtl-spec | IT/ST テスト仕様書（計画書＋UUID 付きケース md）を e2e/ 下に生成 | 「IT計画書/STテスト仕様書を作って」 | | fvtl-sync | ケース md を UUID キーで fv-test-lab に register/update 同期し、実行・修正まで回す | 「テストを testlab に同期して」 | | fv-testlab-author | テスト作成の規約・ステップ契約（steps 組み立て・修正ループの正）。単発のテスト作成依頼にも直接使う | 「fv-test-lab に◯◯のテストを作成して」 |

典型フロー: fvtl-setup（環境整備）→ fvtl-spec（仕様書生成）→ fvtl-sync（同期・実行）。 fvtl-sync は steps の組み立て・修正を fv-testlab-author の規約に委譲するため、4つセットでコピーするのを推奨。 各ケースの UUID がローカル md と fv-test-lab 側ケース（tags の uuid:<...>）を対応付けるため、 仕様書を編集して再同期すると同一ケースが update される（重複登録されない）。

セットアップ

1. API キーを発行

fv-test-lab の Web UI → 対象プロジェクト → 「API キー」→ 発行。 平文キー（fvtl_...）は発行時のみ表示されます。キー＝プロジェクト境界。

2. MCP サーバを Claude Code に登録

作業ディレクトリに .mcp.json を作成します（npx で clone 不要）:

{
  "mcpServers": {
    "fv-testlab": {
      "command": "npx",
      "args": ["-y", "fv-testlab-mcp"],
      "env": {
        "FVTL_API_KEY": "${FVTL_API_KEY}",
        "FVTL_API_BASE_URL": "https://<your-fv-test-lab-api>/api"
      }
    }
  }
}

• FVTL_API_KEY は環境変数に設定して ${FVTL_API_KEY} で参照（直書き・コミット禁止）。
• FVTL_API_BASE_URL は /api/v1 を含まないベース URL（例: https://xxxx.execute-api.ap-northeast-1.amazonaws.com/api）。
• CLI 登録も可: claude mcp add fv-testlab --env FVTL_API_KEY=... --env FVTL_API_BASE_URL=... -- npx -y fv-testlab-mcp
• ツール定義の更新後は Claude Code の再起動が必要。

3. skill を配置

このリポジトリの skills/ 配下を、作業ディレクトリの .claude/skills/ にコピーします （最低限 fv-testlab-author。IT/ST 仕様書運用をするなら4つ全て）。

cp -r <このリポジトリ>/skills/* <作業リポジトリ>/.claude/skills/

Claude に「fv-test-lab に◯◯のテストを作成して」と依頼すると skill が起動し、 register_test → run_case → get_run_status →（失敗時）get_run_result → update_test のループを回します。

MCP ツール

| ツール | 説明 | |--------|------| | list_apps / list_auth_accounts | 対象アプリ / 認証アカウント一覧（秘密情報なし） | | get_site_knowledge | サイトマップの画面知識（siteAnalysis） | | list_test_suites / list_test_cases / get_test_case | スイート / ケース参照 | | update_test_suite / delete_test_suite / delete_test_case | スイート更新・削除 / ケース削除 | | list_test_files / upload_test_file | 登録済みテストファイル一覧 / ローカルファイルの登録（upload 参照用） | | register_test / update_test | ケース登録 / 更新（修正ループは update_test） | | run_case | 実ブラウザで単体実行（非同期） | | get_run_status / get_run_result | 実行状態 / 結果（スクショ・実行時ページ URL・db_snapshot 結果 JSON・失敗時 DOM の署名付き URL） | | get_ssm_role_template | SSM 踏み台（クロスアカウント）用スイッチロール CFn テンプレート配布 |

ステップの契約は skills/fv-testlab-author/references/step-spec.md（縮約版）を参照。 完全版はサーバ本体リポジトリの doc/test-step-spec.md（乖離時は本体が正）。

前提

• 対象プロジェクトに 対象アプリと認証アカウント（verify 済み推奨）が登録されていること。
• 実行は非同期（数十秒〜数分）。get_run_status を 10〜30 秒間隔でポーリングします。

開発

npm ci
npm run build   # 構文チェック
npm test        # config の単体テスト

ライセンス

MIT