剧作家MCP测试框架
一个智能的、支持人工智能的浏览器测试自动化框架，可以搭建桥梁 剧作家, TypeScript，以及 模型上下文协议（MCP）.通过JSON文件声明性地执行测试场景，通过MCP工具编排测试，并使AI模型（如Claude）能够智能地管理您的测试套件。
______________________________________________________________________
项目目标
使用以下工具执行和管理E2E测试 声明性JSON场景 和 MCP协议集成这使得：
- ✅ 无代码测试定义（基于JSON的场景）
- ✅ 人工智能编排的测试执行（Claude可以调用测试工具）
- ✅ 综合报告（JSON+截图）
- ✅ 多浏览器测试（Chromium、Firefox、WebKit）
- ✅ 使用MCP进行测试执行、上下文分段和定义测试配置
______________________________________________________________________
______________________________________________________________________
使用技术
- 剧作家 （v1.57.0）--多浏览器自动化（Chromium、Firefox、WebKit）
- TypeScript （v5.9.3）——类型安全测试定义和执行逻辑
- 模型上下文协议（MCP） （v1.25.3）——用于将测试工具暴露给Claude和其他AI客户端的AI就绪协议
- 温斯顿 （v3.19.0）--跨所有组件的结构化日志记录
- Node.js （v18+）--运行时环境
______________________________________________________________________
MCP集成（AI就绪）
MCP服务器将测试执行公开为 可发现的工具 对于AI模型：
可用工具
1.执行_场景
Tool: execute_scenario
Input: { scenarioPath: string, options?: ExecutionOptions }
Output: ScenarioResult with pass/fail status, duration, test details2.列表_场景
Tool: list_scenarios
Input: { directory?: string }
Output: Array of available scenario files3.验证场景
Tool: validate_scenario
Input: { scenarioPath: string }
Output: Validation result (passes/fails JSON schema check)4.健康
Tool: get_health
Output: Server health statusAI如何使用这些工具
当您运行MCP服务器时(npm run dev)，AI客户端（如Claude）可以：
- 列出场景 →
"Show me all available tests" - 执行测试 →
"Run the login test scenario" - 验证 →
"Check if my scenario JSON is valid" - 获取结果 → 接收带有截图的结构化执行结果
克劳德提示示例：
"Execute the login test scenario and show me the results"
→ Claude calls execute_scenario tool
→ MCP server runs test
→ Returns report with screenshots and assertions
→ Claude shows you the results页面对象模式
该框架实现了 页面抽象层 将测试逻辑与UI实现解耦：
PageActions（src/browser/page-actions.ts）
将所有浏览器交互封装在可重用的方法中：
// All UI interactions go through PageActions
await pageActions.navigate(page, baseUrl, '/login');
await pageActions.type(page, 'input#username', 'user');
await pageActions.click(page, 'button#login');
await pageActions.assert(page, [{ type: 'visible', target: 'h1', expected: 'true' }]);优点：
- 测试逻辑独立于选择器
- UI更改只需要更新PageActions
- 一致、可重用的交互方法
- 易于通过新操作进行扩展
______________________________________________________________________
项目结构
src/
├── browser/
│ ├── page-actions.ts # Browser interactions (navigate, click, type, assert)
│ ├── browser-manager.ts # Session & context lifecycle management
│ ├── locator-healer.ts # Self-healing selectors
│ ├── playwright-browser-provider.ts # Browser factory
│ ├── in-memory-session-store.ts # Session metadata storage
│ └── contracts.ts # Type-safe interfaces
├── server/
│ ├── index.ts # MCP server & tool handlers
│ └── scenario-executer.ts # Core test execution engine
├── reporter/
│ ├── report-generator.ts # Transform results to JSON reports
│ └── report-writer.ts # Persist reports to disk
├── types/
│ └── index.ts # Shared TypeScript interfaces
├── utils/
│ └── logger.ts # Winston-based structured logging
└── examples/
└── run-scenario.ts # Multi-scenario test runner
test-scenarios/
├── login.json # JSON test definitions
├── add-to-cart.json
└── checkout.json
test-results/
├── {scenarioId}/
│ ├── tc-001/ # Screenshots for test case 001
│ ├── tc-002/
│ └── report.json # Aggregated execution report______________________________________________________________________
设置和安装
先决条件
- Node.js v18或更高版本
- npm或纱线
安装
# Install dependencies and Playwright browsers
npm run setup
# Or manually:
npm install
npx playwright install环境变量（可选）
创建 .env 自定义设置文件：
MCP_SERVER_NAME=mcp-playwright-test
MCP_SERVER_VERSION=1.0.0
HEADLESS=true______________________________________________________________________
如何运行测试
运行所有场景（无头）
npm test执行所有操作 .json 文件在 test-scenarios/ 目录。
在浏览器可见的情况下运行测试
npm run test:headed在测试执行期间显示浏览器窗口（对调试很有用）。
验证场景JSON
npm run validate在不执行的情况下检查场景文件的结构正确性。
启动MCP服务器（AI集成）
npm run dev启动StdIO上的MCP服务器。Claude和其他AI客户现在可以调用测试工具。
构建TypeScript
npm run build将TypeScript编译为JavaScript dist/ 文件夹。
清洁构建工件
npm run clean______________________________________________________________________
示例：登录测试演练
场景结构
登录测试演示了完整的工作流程：
{
"scenarioId": "login-test-001",
"scenarioName": "Login Test Scenario",
"baseUrl": "https://www.saucedemo.com",
"browserType": "chromium",
"testCases": [
{
"id": "tc-001",
"name": "Navigate to Homepage",
"steps": [
{ "id": "step-001", "action": "navigate", "value": "/" },
{ "id": "step-002", "action": "assert", "assertions": [...] }
]
},
{
"id": "tc-002",
"name": "Execute Login",
"steps": [
{ "action": "type", "target": "input#user-name", "value": "standard_user" },
{ "action": "type", "target": "input#password", "value": "secret_sauce" },
{ "action": "click", "target": "#login-button" },
{ "action": "assert", "assertions": [
{ "type": "url", "expected": "/inventory.html" },
{ "type": "text", "target": "div.app_logo", "expected": "Swag Labs" }
] }
]
}
]
}看 测试场景/login.json 对于完整的示例。
测试执行流程
- 导航 → 加载登录页面(
/) - 验证 → 断言页面正文可见
- 输入 → 在中键入用户名
input#user-name - 输入 → 在中键入密码
input#password - 行动 → Click
#login-button - 断言 → 验证URL是否已更改为
/inventory.html - 断言 → 验证“Swag Labs”文本是否可见
结果
执行后：
- ✅ 每一步捕获的屏幕截图→
test-results/login-test-001/tc-001/*.png - ✅ 执行报告→
test-results/login-test-001/report.json - ✅ Logs →
logs/目录
______________________________________________________________________
测试场景格式
测试场景包括 声明性JSON文件 具有以下结构：
{
scenarioId: string; // Unique test identifier
scenarioName: string; // Human-readable name
baseUrl: string; // Base URL for navigation
browserType: 'chromium' | 'firefox' | 'webkit';
testCases: [
{
id: string; // Unique test case ID
name: string; // Test case description
priority: 'high' | 'medium' | 'low';
tags: string[]; // For filtering/categorization
steps: [
{
id: string;
action: 'navigate' | 'click' | 'type' | 'wait' | 'assert';
target?: string; // CSS selector
value?: string; // For navigate/type actions
assertions?: [
{
type: 'visible' | 'text' | 'attribute' | 'url' | 'count';
target: string; // CSS selector
expected: string | number;
}
];
timeout?: number; // Optional timeout in ms
}
];
}
];
}完整的TypeScript接口： src/types/index.ts
______________________________________________________________________
______________________________________________________________________
测试结果和报告
每次试运行后：
报告文件： test-results/{scenarioId}/report.json
{
"reportId": "uuid",
"reportGeneratedAt": "2026-01-28T10:30:45Z",
"scenario": {
"scenarioId": "login-test-001",
"scenarioName": "Login Test Scenario"
},
"execution": {
"startTime": "...",
"endTime": "...",
"duration": 45000,
"status": "passed",
"summary": { "passed": 2, "failed": 0, "skipped": 0 }
},
"testCaseResults": [...]
}屏幕截图： test-results/{scenarioId}/{testCaseId}/step-*.png
在每个步骤中捕获的全页屏幕截图用于可视化调试。
日志： logs/ 目录
带有时间戳、组件上下文和错误详细信息的结构化日志。
______________________________________________________________________
入门指南
# 1. Install & setup
npm run setup
# 2. Run a test scenario
npm test
# 3. Check results
ls test-results/
cat test-results/login-test-001/report.json
# 4. (Optional) Start MCP server for AI integration
npm run dev______________________________________________________________________
故障排除
常见问题
Q： Playwright未安装
npx playwright installQ： 测试超时
- 增加场景中的超时时间：
"timeout": 60000 - 检查测试站点的网络连接
- 使用
npm run test:headed观看处决
Q： MCP服务器无法启动
npm run build # Rebuild TypeScript first
npm run dev架构和总体流程
┌─────────────────────────────────────────────────────────┐
│ MCP Client (Claude, IDE, external tool) │
└────────────────────┬────────────────────────────────────┘
│ MCP Protocol (StdIO)
▼
┌─────────────────────────────────────────────────────────┐
│ MCPTestServer │
│ • Exposes test tools (execute_scenario, list_scenarios)│
│ • Routes tool calls to appropriate handlers │
└────────────────────┬────────────────────────────────────┘
│
▼
┌──────────────────────────────┐
│ ScenarioExecutor │
│ • Loads JSON scenario files │
│ • Executes test cases/steps │
│ • Manages test lifecycle │
└──────────┬───────────────────┘
│
▼
┌──────────────────────────────┐
│ BrowserManager │
│ • Session lifecycle │
│ • Context/Page management │
│ • Resource cleanup │
└──────────┬───────────────────┘
│
┌──────┴──────┬──────────┐
▼ ▼ ▼
navigate() click() type() wait() assert()
│ │
└────────┬───────────────┘
▼
┌──────────────────────────────┐
│ PageActions │
│ • Browser interactions │
│ • Assertion validation │
│ • Screenshot capture │
└──────────┬───────────────────┘
│
┌──────────┴───────────┐
│ LocatorHealer │
│ • Self-heal selectors
│ • Fuzzy selector matching
└──────────┬───────────┘
│
▼
┌──────────────────────────────┐
│ Playwright │
│ • Real browser automation │
│ • Screenshot capture │
└──────────┬───────────────────┘
│
▼
┌──────────────────────────────┐
│ ReportGenerator │
│ • Transform results to JSON │
│ • Link evidence paths │
│ • Persist reports │
└──────────────────────────────┘______________________________________________________________________
许可证
ISC
______________________________________________________________________
项目链接
- 主要回购结构： 看
src/文件夹 - 示例场景： 测试场景/
- TypeScript接口： src/types/index.ts
- MCP服务器： src/server/index.ts