Playwright Agent MCP Starter

编剧代理MCP初级

 

生产就绪启动器 UI+API测试自动化 通过MCP使用Playwright、TypeScript、页面对象模型和AI驱动的Claude Code代理。

______________________________________________________________________

这是给谁的

• Jr QA工程师 谁想要一个干净、有主见的剧作家+TypeScript的起点
• 高级SDET 谁想要一个包含AI代理工具和MCP集成的电池模板
• 团队 需要可重复的公关工作流程——小范围、稳定的选择器、没有不稳定的睡眠

______________________________________________________________________

包含什么

• UI测试 --使用页面对象模型、自定义夹具、跨浏览器（Chromium、Firefox、WebKit）进行剧作家测试
• API测试 --通过Playwright进行快速HTTP测试的专用无浏览器项目 request API
• 身份验证设置项目 --在UI测试之前运行一次，保存 storageState 因此，每次测试都会开始进行身份验证
• 测试数据工厂 --生成具有可选覆盖的唯一用户、地址、产品和订单
• 超时常数 --命名值(Timeouts.SHORT, .LONG, .NAVIGATION)而不是神奇的数字
• 11个AI代理 --Claude Code代理用于测试设计、PR卫生、安全扫描、薄片分类、覆盖率分析等
• 2台MCP服务器 — @playwright/mcp （浏览器自动化）+Playwright测试MCP（测试运行器）
• 文档库 --QA惯例、提示库、PR工作流程、安全净化、MCP设置

______________________________________________________________________

5分钟快速入门

# 1. Use this template (click "Use this template" on GitHub) — or clone directly
git clone https://github.com/ErkanBarin/playwright-agent-mcp-starter.git
cd playwright-agent-mcp-starter

# 2. Install dependencies
npm install

# 3. Set up environment
cp .env.example .env
# Edit .env → set BASE_URL to your app (defaults to http://localhost:3000)

# 4. Set up MCP (optional, for Claude Code / AI agent users)
cp .mcp.json.example .mcp.json
# MCP servers run via npx — no extra install needed

# 5. Install browsers + Playwright CLI
npx playwright install
npm install -g @playwright/cli@latest  # optional, for codegen/open/screenshot

# 6. Run one UI test (proof it works)
npx playwright test tests/ui/smoke.spec.ts --project=chromium

# 7. Run API tests (no browser launched — fast)
npx playwright test --project=api

# 8. See the HTML report
npm run report

注： UI默认为 http://localhost:3000，API默认为 https://httpbin.org。所有测试都直接针对这些公共URL通过。请在 .env 指向您的应用程序。

Windows用户： 此仓库使用符号链接(.claude/agents 和 .claude/skills 指向 ai/).跑 git config core.symlinks true 在克隆之前，请在Windows设置中启用开发人员模式。

______________________________________________________________________

存储库结构

├── ai/                  # Shared AI workspace (canonical location)
│   ├── agents/          # AI agent definitions (test design, PR hygiene, security, etc.)
│   ├── skills/          # Reusable prompt skills (MCP scout, prompt library)
│   ├── prompts/         # Prompt templates
│   └── knowledge/       # Domain knowledge and reference material
├── .claude/
│   ├── agents -> ai/agents   # Symlink — Claude Code reads from ai/
│   └── skills -> ai/skills   # Symlink — Claude Code reads from ai/
├── docs/
│   ├── QA_CONTEXT.md    # Scope, selectors, waits, PR slicing
│   ├── PROMPT_LIBRARY.md
│   ├── PR_WORKFLOW.md
│   ├── SECURITY_SANITIZATION.md
│   └── MCP_SETUP.md
├── pages/               # Page Object Models (base + login example)
├── tests/
│   ├── auth.setup.ts    # Auth setup (runs before UI projects)
│   ├── fixtures/        # Custom Playwright fixtures
│   ├── ui/              # UI test specs (smoke.spec.ts)
│   └── api/             # API test specs (health.spec.ts)
├── utils/
│   ├── index.ts         # Barrel — import everything from '../utils'
│   ├── timeouts.ts      # Named timeout constants (SHORT, MEDIUM, LONG, etc.)
│   ├── data-factory.ts  # Test data generators (user, product, order, etc.)
│   ├── api-helpers.ts   # API response assertion helpers
│   └── env.ts           # Typed environment variable access
├── .mcp.json.example    # MCP server config template
├── playwright.config.ts
└── package.json

______________________________________________________________________

脚本

______________________________________________________________________

项目架构

配置定义了5个按特定顺序运行的项目：

setup → chromium, firefox, webkit (parallel)
                                        api (independent, no browser)

• 设置 --验证一次，将浏览器状态保存到 .auth/state.json
• chromium/firefox/webkit --加载已保存的身份验证状态的UI测试（每次测试无登录）
• 接口 --对抗 tests/api/ 无浏览器——纯HTTP请求

在运行之间缓存身份验证状态——如果Cookie仍然有效，则跳过登录（~96ms而不是~1.7s）。状态存储在 .auth/ （外面 test-results/)所以剧作家不会擦掉它。

公用工程（桶装进口）

所有utils重新导出自 utils/index.ts --一切只需一次导入：

import { Timeouts, TestData, assertStatus, getBaseUrl } from '../utils';

超时

await page.click(selector, { timeout: Timeouts.SHORT });   // 3s
await expect(locator).toBeVisible({ timeout: Timeouts.MEDIUM }); // 5s
await page.goto(url, { timeout: Timeouts.NAVIGATION });    // 15s

测试数据工厂

使用可选覆盖生成独特、真实的测试数据：

import { TestData } from '../utils';

const user = TestData.user();                        // random user
const admin = TestData.user({ role: 'admin' });      // override role
const product = TestData.product({ price: 9.99 });   // override price
const order = TestData.order();                      // random order
const email = TestData.email('signup');               // signup.k8f3x2@example.com

______________________________________________________________________

AI工作区

所有AI资源都存在于 ai/ 目录——Claude Code、GitHub Copilot和其他人工智能工具的共享工作区。Claude Code通过符号链接读取代理和技能(.claude/agents → ai/agents, .claude/skills → ai/skills).

所有人工智能工具的惯例在 AGENTS.md 在repo根目录下。GitHub Copilot阅读 这一点可以追溯到 AGENTS.md.

代理

包括12个代理，以加速QA工作流程：

复制粘贴提示

Design UI tests for the login page following POM pattern. Check existing
page objects first, then create missing ones. Tag all tests @ui @smoke.

Scan this repo for hardcoded secrets, API keys, tokens, and internal URLs.
Report findings with file paths and line numbers.

Analyze test coverage gaps. Map page objects and API endpoints to existing
tests. Show what's untested and prioritize by risk.

看 docs/PROMPT_LIBRARY.md 获取完整的提示库。

______________________________________________________________________

MCP设置

两个MCP服务器将Claude Code连接到您的浏览器和测试运行器：

cp .mcp.json.example .mcp.json

看 docs/MCP_SETUP.md 对于先决条件、VS代码扩展和健全性检查演练。

______________________________________________________________________

持续集成

此仓库包含一个GitHub Actions工作流，该工作流在每次推送和PR时运行所有Playwright测试 main.

它开箱即用，无需配置。

看 对于工作流定义。

______________________________________________________________________

文档

• 代理商.md --人工智能代理惯例和项目标准
• MCP设置 --MCP服务器配置和健全性检查
• QA背景和惯例 --作用域、选择器、等待、PR切片
• 提示库 --代理的复制粘贴提示
• PR工作流程 --标准PR流
• 安全消毒 --预发布检查表

______________________________________________________________________

贡献

看 贡献.md.

安全

看 安全.md.

许可证

麻省理工学院