playwright-generate-mcp

엔터프라이즈급 Model Context Protocol (MCP) 서버로, AI 코딩 어시스턴트(Cursor, Claude Desktop, Antigravity, Roo Code 등)가 강력하고 유지보수 가능하며 플레이크(flake)에 강한 Playwright E2E 테스트를 생성, 점수화, 실행, 자동 치유할 수 있도록 지원합니다.

이 서버는 도메인 주도 페이지 객체 모델(POM) 아키텍처를 강제하고, 파일 간 품질 점수화를 제공하며, 풍부한 단일 턴 실패 진단을 추출하고, 엄격한 웹 우선 플레이크 방지 규칙을 준수합니다.

✨ 주요 기능

• 🏗️ 도메인 주도 POM 아키텍처: 선언적 스펙(Declarative Specs), 페이지 객체(Page Objects), 커스텀 픽스처(Custom Fixtures), 동적 데이터 팩토리(Dynamic Data Factories) 간의 관심사 분리를 강제합니다.

• 🔍 파일 간 POM 품질 점수화: score_test_quality 및 run_playwright_test는 import 의존성(.spec.ts $\rightarrow$ .fixture.ts $\rightarrow$ *.page.ts / *.component.ts)을 자동으로 순회하며 관련된 모든 파일의 로케이터와 안티패턴을 점수화합니다.

• ⚡ 단일 턴 풍부한 진단: 테스트가 실패하면 run_playwright_test가 정확한 파일 및 줄 위치, 오류 범주, 실패 직전의 마지막 3–5개 액션 단계, 브라우저 콘솔 로그, 실패한 HTTP 요청(4xx/5xx), 스크린샷 경로를 단일 턴에 즉시 반환합니다.

• 🛡️ 엄격한 플레이크 방지 규칙: 임의의 대기(waitForTimeout, setTimeout), await되지 않은 액션, networkidle 의존성, 수동 텍스트 추출을 감지하고 지양하며, 웹 우선 자동 재시도 어서션을 권장합니다.

• 🧭 무상태 루트 자동 탐색: 수동 경로 설정 없이 상위 디렉터리를 자동으로 순회하여 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 아키텍처, 코드 생성 순서(Step A to Step 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