playwright-generate-mcp

エンタープライズグレードのModel Context Protocol（MCP）サーバーであり、AIコーディングアシスタント（Cursor、Claude Desktop、Antigravity、Roo Codeなど）による堅牢で保守性が高く、フレークに強いPlaywright E2Eテストの生成、スコアリング、実行、自動修復を支援します。

ドメイン駆動のPage Object Model（POM）アーキテクチャを強制し、ファイル横断品質スコアリングを提供し、リッチなシングルターン障害診断を抽出し、厳格なWebファーストの耐フレーク性ルールに準拠します。

✨ 主要機能

• 🏗️ ドメイン駆動POMアーキテクチャ: 宣言型スペック、ページオブジェクト、カスタムフィクスチャ、動的データファクトリの間で関心の分離を強制します。

• 🔍 ファイル横断POM品質スコアリング: score_test_quality と run_playwright_test は、インポート依存関係（.spec.ts $\rightarrow$ .fixture.ts $\rightarrow$ *.page.ts / *.component.ts）を自動的にたどり、関連するすべてのファイルにわたってロケーターとアンチパターンをスコアリングします。

• ⚡ シングルターンのリッチ診断: テストが失敗すると、run_playwright_test は、正確な位置、エラーカテゴリ、失敗前の最後の3〜5アクションステップ、ブラウザコンソールログ、失敗したHTTPリクエスト（4xx/5xx）、スクリーンショットパスを単一のターンで即座に返します。

• 🛡️ 厳格な耐フレーク性ルール: 任意のスリープ（waitForTimeout、setTimeout）、awaitされていないアクション、networkidle への依存、手動のテキスト抽出を検出して非推奨とし、Webファーストの自動再試行アサーションを優先します。

• 🧭 ステートレスなルート自動検出: 手動のパス設定を必要とせずに、親ディレクトリを自動的に走査して playwright.config.{ts,js,mjs,cjs,mts,cts} を検出します。

• 💬 適応型インタラクティブ確認: テスト修復を適用する前に、インタラクティブUIモーダル（ask_question、vscode_askQuestions）またはフォーマットされた番号付きリストをサポートします。

Related MCP server: Limetest MCP Server

📁 アーキテクチャ標準

このMCPは、AIエージェントがクリーンなドメイン駆動の階層構造でテストを整理できるように導きます。

tests/e2e/
├── domain/                      # Grouped by business features
│   └── {feature}/
│       ├── pages/               # Page Objects / Component Objects
│       │   └── {step}.page.ts
│       └── {feature}.fixture.ts # Custom Fixture injecting Page Objects & Data
├── factory/                     # Dynamic test data builders
│   └── {entity}.factory.ts      # Unique data per run (timestamp / Faker)
└── specs/                       # Declarative, readable test specs
    └── {feature}.spec.ts

コア設計ルール

1. 厳格な分離: *.spec.ts ファイル内では、生のロケーターや直接のDOM操作を禁止します。すべてのUI操作はページ/コンポーネントオブジェクト内に置きます。

2. カスタムフィクスチャ: スペック内での手動の new Page() インスタンス化の代わりに、test.extend<Fixtures>() を使用してページオブジェクトとテストデータを注入します。

3. 動的データファクトリ: 実行ごとに一意のテストデータを生成し、テストの再実行時にデータベースの一意制約の衝突を防ぎます。

4. セマンティックロケーター: getByRole > getByLabel / getByPlaceholder > getByText > getByTestId を優先します。深くネストされたCSS（div > div > span）は厳禁です。

5. タグ付け規約:

   • @smoke: 重要なハッピーパス。

   • @regression: 包括的なユーザーフロー。

   • @ui: page.route() を使用してAPIレスポンスをスタブする純粋なUI/フロントエンドテスト。

   • @integration: 実際のバックエンドAPIに対して検証するテスト。

🛠️ MCPツール

📋 MCPプロンプト

• playwright_e2e_workflow: AIエージェントに、ドメイン駆動POMアーキテクチャ、コード生成シーケンス（ステップAからステップE）、厳格な耐フレーク性記述ルール、シングルターン診断、安全な修復ワークフローを指示するための完全なエンドツーエンドプロンプト。

🚀 インストールとセットアップ

1. ソースからビルド

git clone https://github.com/your-username/playwright-generate-mcp.git
cd playwright-generate-mcp
npm install
npm run build

2. MCPクライアントの設定

サーバーをMCP設定ファイル（例: claude_desktop_config.json、Cursorの設定、AntigravityのMCP設定）に追加します:

{
  "mcpServers": {
    "playwright-generate": {
      "command": "node",
      "args": ["/absolute/path/to/playwright-generate-mcp/dist/index.js"]
    }
  }
}

またはNPMに公開した場合:

{
  "mcpServers": {
    "playwright-generate": {
      "command": "npx",
      "args": ["-y", "playwright-generate-mcp"]
    }
  }
}

🧑💻 開発

npm run dev     # tsx watch mode
npm run build   # Compile TypeScript to dist/
npm start       # Run compiled MCP server

📄 ライセンス

MIT