k11 Playwright QA

k11 Playwright QA — MCP サーバー & Claude Code プラグイン

ユーザーストーリーを実際に通る Playwright テストに変換し、デザイン変更で壊れたテストを修正します。

AI コーディングアシスタントは Playwright テストをすばやく作成できますが、セレクターは推測で選びます。テストは正しそうに見えても、最初の実行で失敗したり、誰かが CSS クラス名を変更すると次回には壊れたりします。この MCP サーバーは、アシスタントが推測できない情報を提供します。

• 検証済みロケーター。 実際のページを開き、要素に正確に 1 つだけ一致するロケーターを、安定性の高い順（getByTestId、getByRole、getByLabel、…）に返します。
• ストーリー → 仕様。 「私は…として…したい。なぜなら…だから」という形式、Gherkin シナリオ、または受け入れ条件の箇条書きを、Playwright Test のひな形に変換します。各シナリオにテストを 1 つ、各ステップに test.step を 1 つ作成します。
• 構造化されたテスト実行。 Playwright を実行し、失敗したテストが待機していた正確なロケーターを含む、テストごとの結果を返します。
• 自己修復ロケーター。 UI が変更されると、テストが意図していた要素を見つけ、信頼度スコアとその理由を添えて検証済みの置き換え候補を提案します。テストを黙って編集することはありません。

Claude Code（/story-to-test と /heal-tests コマンドを備えたプラグインとして）、Claude Desktop、その他の MCP クライアントで動作します。公式の MCP Registry に io.github.K11-Software-Solutions/playwright-qa として登録されています。

---

修復の様子を見る

デモアプリには 2 つのバージョンがあります。v2 ではデザイン変更によりすべての ID が変更され、ボタンのテキストが「Sign in」から「Log in」に変わり、CSS クラスが入れ替わり、「Continue with Google」ボタンが追加されました。page.locator('#login-btn') を使うテストは失敗します。heal_locator は次の結果を返します（一部抜粋）。

{
  "status": "healed",
  "original": "page.locator('#login-btn')",
  "suggestion": "page.getByRole('button', { name: 'Log in' })",
  "confidence": 0.87,
  "reasons": [
    "name equivalent: \"Sign in\" → \"Log in\"",
    "id similar (50%): \"login-btn\" → \"signin-submit\"",
    "role matches", "type matches", "tag matches",
    "classes similar (64%): \"btn btn-primary\" → \"cta cta-primary\""
  ],
  "candidates": [
    { "locator": "page.getByRole('button', { name: 'Log in' })", "score": 0.87 },
    { "locator": "page.getByRole('button', { name: 'Continue with Google' })", "score": 0.42 },
    { "locator": "page.getByRole('heading', { name: 'Log in to Acme Store' })", "score": 0.15 }
  ],
  "referenceSource": "baseline"
}

見た目が似ている別のボタンではなく、正しいボタンを選びました。また、提案されたロールベースのロケーターを使えば、そもそもデザイン変更の影響を受けずに済みます。

ツール

ツール	機能
explore_page	URL を開き、正確に 1 つの要素に一致することを検証済みのロケーターとともに要素を一覧表示します。
check_locator	ページ上でロケーターに一致する要素の数（1 = 適切）と、表示されているかどうかを確認します。
parse_user_story	ユーザーストーリー → 構造化されたシナリオ + Playwright Test のひな形。
write_test	tests/ に仕様ファイルを書き込みます。このディレクトリ外のパスは拒否し、指示がない限り上書きしません。
run_tests	Playwright Test を実行し、失敗したロケーターを含むテストごとの結果を返します。
capture_baseline	テストが通る間に、各ロケーターが一致する要素のフィンガープリントを記録します（.qa-mcp/baselines.json）。
heal_locator	UI の変更後に意図された要素を見つけ、検証済みの置き換え候補を提案します。
save_login_state	数ステップで一度ログインし、ほかのツールやテストで使えるようセッションを保存します。

explore_page、check_locator、capture_baseline、heal_locator は、ログインが必要なページや、フローを数ステップ進めた先のページにアクセスするためのオプションのセッションを受け付けます。

プロンプト：ストーリーからテストの成功までを案内するワークフロー、story_to_playwright。

自己修復の仕組み

1. ベースライン。 テストが成功している間に、capture_baseline が各要素のフィンガープリント（ロール、アクセシブル名、テスト ID、id、name、type、ラベル、プレースホルダー、クラス、テキスト、href）を記録します。
2. 検出。 run_tests が失敗を報告すると、Playwright が待機していたロケーターも含まれます。
3. 照合。 heal_locator は、現在のページ上に表示されているすべての要素をフィンガープリントと照合してスコアを付けます。安定した属性には完全一致を使い、テキストと ID にはあいまい一致と同義語を考慮した照合を使います（「Sign in」≈「Log in」、btn ≈ button）。
4. 検証。 最も一致度の高い候補に対して、ライブページ上で要素が 1 つだけに完全一致する、最も安定したロケーターを取得します。
5. 判定。 信頼度が 0.55 以上で、次点候補を明確に上回る場合にのみ healed と報告します。それ以外の場合は、上位候補とともに needs_review を報告します。元の要素に似たものが何もない場合は not_found を報告します。ベースラインがない場合は、ロケーター自体が示す内容を使い、その旨を報告します。

CI で自己修復が機能するように、.qa-mcp/baselines.json をリポジトリにコミットしてください。ログインセッションを保持する .qa-mcp/auth/ はコミットしないでください。save_login_state が .gitignore に追加します。

ログインが必要なページと複数ステップのフロー

すべてのページツールは session を受け取ります。

{
  "url": "https://shop.example.com/login",
  "session": {
    "storage_state": ".qa-mcp/auth/default.json",
    "steps": [
      { "action": "click", "locator": "page.getByRole('link', { name: 'My orders' })" },
      { "action": "wait_for", "locator": "page.getByRole('heading', { name: 'Order history' })" }
    ]
  }
}

• storage_state は保存済みのログイン状態です。save_login_state で作成するか（手順を実行して一度ログインします）、Playwright のグローバルセットアップにあるファイルを再利用します。プロジェクト内に置く必要があります。
• steps は開始ページの読み込み後に実行されます。goto、click、fill、press、select、check、uncheck、wait_for を最大 25 個まで指定できます。ロケーターは、ほかの箇所と同じ安全な方法で解析されます。
• シークレットはプロンプトやログに残りません。 "value": "${ENV:APP_PASSWORD}" と記述すると、値は環境変数から読み込まれます。結果にはプレースホルダーが表示され、リテラルの入力値は ••• でマスクされます。
• ベースラインはステップの終了ページに保存されるため、同じセッションを使ってキャプチャと自己修復を行うと整合します。

CI での自己修復と監査証跡

heal-ci は UI の変更で壊れたロケーターを修復し、変更内容をすべて説明するプルリクエストを作成します。

npx -y k11-playwright-qa-mcp heal-ci --apply

1. Playwright テストスイートを実行します。
2. ロケーターが原因の失敗ごとに、テストが実行されていたページを特定します（.qa-mcp/heal.config.json またはテスト内の page.goto(...) から判断します）。設定で指定されている場合は、先にログインしてから、コミット済みのベースラインを使って修復します。
3. 信頼度が 0.7（--min-confidence）以上で、次点候補を明確に上回る場合にのみ変更を適用します。
4. 修復したテストを再実行し、引き続き失敗する変更は元に戻します。 各変更は個別に評価し、適用するか元に戻すかを決定します。
5. ロケーターが原因ではない失敗には手を加えません。実際のバグである可能性があります。
6. プルリクエストの説明となる heal-report.md と、詳細な証拠を含む heal-report.json を書き出します。

--apply を指定しない場合はドライランとなり、提案のみを報告します。デモアプリの再設計で生成された実際のレポートの例です。

修復して検証済み 1 件、提案 0 件、元に戻した変更 1 件、要レビュー 1 件、見つからなかった項目 0 件、ロケーターが原因ではない失敗 1 件。

テスト	変更前のロケーター	変更後のロケーター	信頼度	次点候補	再実行
アカウント › 注文が表示される	page.locator('#view-orders')	page.getByRole('button', { name: 'View orders' })	82%	View returns ボタン（59%）	成功

人による確認が必要： 「Edit profile」リンク → 最適候補は「Account settings」（45%）。変更するには信頼度が不十分です。「Open cart」は信頼度 85% で修復されましたが、カートのメッセージも変更されていたため、テストは引き続き失敗し、変更は元に戻されました。

ロケーターが原因ではない失敗： 「has the account title」（ページタイトルが変更されていました）。変更なし。

docs/heal-locators.yml をアプリの .github/workflows/ にコピーすると、スケジュールに従って実行し、プルリクエストを自動で作成できます。また、docs/heal.config.example.json を .qa-mcp/heal.config.json にコピーして、ログイン方法を指定してください。

Microsoft の Playwright MCP との比較

Playwright MCP を使うと、AI がブラウザーを操作してあらゆるタスクを実行でき、Playwright のテストエージェント（プランナー、ジェネレーター、ヒーラー）はこれを基盤として構築されています。幅広い探索や自動化には、これらをお使いください。監査可能なテストメンテナンスが必要な場合は、k11 Playwright QA をお使いください。

	Playwright MCP とテストエージェント	k11 Playwright QA
修復の根拠	エージェントの推論	信頼度スコア、具体的な理由、次点候補をレポートに記載
参照点	現在のページ	テストが最後に成功したときに保存されたフィンガープリント
同じ入力に対する同じ結果	実行やモデルによって異なります	はい
テストの編集	エージェントが編集します	検証済みで信頼度の高い変更のみを適用し、それ以外は人に引き継ぎます
CI の出力	エージェントのセッション	監査レポート付きのプルリクエスト

両者を組み合わせると効果的です。Playwright MCP でフローを操作し、k11 Playwright QA でテストスイートを健全に保ちましょう。

インストール

Node 20 以降が必要です。

まず、マシンごとに一度だけ、サーバーが使用する Chromium ビルドをインストールします。

npx -y k11-playwright-qa-mcp install-browsers

Claude Code：プラグイン（推奨）

MCP ツールと /story-to-test および /heal-tests コマンドを追加します。

/plugin marketplace add K11-Software-Solutions/k11techlab-playwright-qa-mcp
/plugin install playwright-qa@k11-qa-tools

Claude Code：MCP サーバーのみ

アプリのプロジェクトフォルダーから実行します。

claude mcp add playwright-qa -- npx -y k11-playwright-qa-mcp

Claude Desktop およびその他の MCP クライアント

{
  "mcpServers": {
    "playwright-qa": {
      "command": "npx",
      "args": ["-y", "k11-playwright-qa-mcp"],
      "env": { "QA_MCP_ROOT": "/path/to/your/app" }
    }
  }
}

ソースから

git clone https://github.com/K11-Software-Solutions/k11techlab-playwright-qa-mcp
cd k11techlab-playwright-qa-mcp
npm install && npx playwright install chromium
claude mcp add playwright-qa -- node /path/to/k11techlab-playwright-qa-mcp/dist/cli.js

サーバーは、QA_MCP_ROOT に指定されたプロジェクト、または未設定の場合は現在のディレクトリのプロジェクトを対象に動作します。run_tests を実行するには、そのプロジェクトに @playwright/test がインストールされている必要があります。

試してみる

Claude Code で、アプリのリポジトリ内から実行します。

/story-to-test http://localhost:3000/login As a customer, I want to sign in so that I can see my orders.
- Valid credentials show "Welcome back"
- A wrong password shows an error and keeps me on the login page

UI を変更した後：

/heal-tests tests/login.spec.ts

安全性

• ロケーター文字列は解析され、eval されません。 単一の getByRole／getByTestId／getByLabel／getByPlaceholder／getByText／locator(css) 式のみ受け付けます。
• 書き込み先は tests/ に限定され、 .spec／.test ファイルのみが対象です。また、依頼がない限り上書きされません。
• テストはプロジェクト独自の Playwright CLI を Node で直接実行し、 シェルを介さないため、引数によるコマンドの注入はできません。
• 修復は提案のみです。 変更内容は、あなた自身、またはレビューを行うエージェントが決定します。

開発

npm install
npx playwright install chromium
npm test        # unit, browser, login-flow, heal-ci and MCP-protocol tests (31)
npm run build

ロードマップ

• Playwright トレースから各テストのページを自動的に学習し、heal.config.json がほとんど不要になるようにする
• 修復シグナルを補強するビジュアル（スクリーンショット）フィンガープリント
• 連結およびフィルター付きロケーター（.filter()、.nth()、ネストされたロケーター）の修復
• 公式 MCP Registry およびコミュニティディレクトリへの掲載

---

K11 Software Solutions が開発しました。K11 Tech Lab のエージェント型 QA シリーズの一部です。MIT ライセンス。