内容
# Playwright 智能质量工程框架
[](https://github.com/Jiten20/playwright-agentic-quality-engineering-framework/actions/workflows/playwright.yml)
基于 **Playwright**、**TypeScript**、**Playwright MCP** 和 **GitHub** 追踪的 AI 辅助质量工程框架。
该框架演示了用于 **测试规划、自动化生成、幻觉检测、故障诊断、人工审批、报告** 和 **GitHub Actions CI/CD** 的受控多智能体工作流。
---
## 📁 项目结构
```text
playwright-agentic-quality-engineering-framework/
│
├── .github/
│ ├── agents/
│ │ ├── playwright-test-planner.agent.md
│ │ ├── playwright-test-generator.agent.md
│ │ └── playwright-test-healer.agent.md
│ │
│ ├── ISSUE_TEMPLATE/
│ │
│ └── workflows/
│ └── playwright.yml
│
├── .vscode/
│ └── mcp.json
│
├── docs/
│ ├── automation-standards.md
│ ├── hallucination-guardrails.md
│ └── human-approval-process.md
│
├── fixtures/
│ └── baseTest.ts
│
├── pages/
│ ├── LoginPage.ts
│ ├── ProductsPage.ts
│ ├── CartPage.ts
│ └── CheckoutPage.ts
│
├── requirements/
│ ├── GH-001-successful-checkout.md
│ └── GH-002-hallucination-challenge.md
│
├── specs/
│ ├── GH-001-checkout-plan.md
│ └── rejected/
│ └── GH-002-unsupported-scenarios.md
│
├── test-data/
│ └── testData.ts
│
├── tests/
│ ├── smoke/
│ │ └── GH-001-checkout.spec.ts
│ ├── regression/
│ └── seed.spec.ts
│
├── playwright.config.ts
├── package.json
├── package-lock.json
├── tsconfig.json
├── .gitignore
└── README.md
```
生成的目录（例如 `playwright-report/` 和 `test-results/`）被排除在 Git 之外，并通过 GitHub Actions 作为执行工件发布。
---
## 🤖 智能 QA 工作流
```text
GitHub 问题 / 需求
↓
Playwright 测试规划器
↓
Playwright MCP 浏览器探索
↓
基于证据的测试计划
↓
幻觉验证
↓
高级 QA 审批
↓
Playwright 测试生成器
↓
POM + 夹具 + 自动化测试
↓
GitHub Actions 质量门控
↓
通过 → 报告 / 拉取请求
失败 → Playwright 测试修复器
↓
人工审查
```
该框架在 AI 生成的测试规划和自动化生成之间保留了一个人工 QA 审批门控。
---
## 🧠 多智能体职责
### Playwright 测试规划器
规划器智能体：
* 读取 GitHub 问题和验收标准
* 使用 Playwright MCP 探索 SauceDemo
* 生成结构化的测试场景
* 捕获需求和观察到的 UI 证据
* 确定假设和不支持的行为
* 不生成自动化代码
### Playwright 测试生成器
生成器智能体：
* 读取仅限 QA 批准的测试场景
* 生成 Playwright TypeScript 测试
* 创建或重用页面对象
* 使用自定义夹具和外部测试数据
* 添加 GitHub 问题追踪
* 执行和验证生成的测试
### Playwright 测试修复器
修复器智能体：
* 分析失败的测试、跟踪、截图和错误
* 在实时应用程序上重现故障
* 分类应用程序和自动化故障
* 提出最小的可维护的修正
* 重新运行失败和相关的测试
* 需要人工批准才能接受更改
---
## ✅ 测试结果摘要
| 需求 | 已批准的场景 | 通过 | 失败 |
| ---------------------------- | ------------ | ---- | ----- |
| GH-001 — 成功产品结账 | 5 | ✅ 5 | 0 |
| GH-002 — 幻觉验证 | 4 个被拒绝的建议 | ✅ 验证 | 0 |
| **自动 GH-001 场景总数** | **5** | ✅ **5** | **0** |
### GH-001 — 成功产品结账
| 场景 ID | 场景 | 状态 |
| -------- | -------------------------------------- | ------ |
| GH-001-SC01 | 使用有效凭证登录 | ✅ 通过 |
| GH-001-SC02 | 将 Sauce Labs 背包添加到购物车 | ✅ 通过 |
| GH-001-SC03 | 查看购物车并继续结账 | ✅ 通过 |
| GH-001-SC04 | 输入结账信息并继续 | ✅ 通过 |
| GH-001-SC05 | 完成订单并验证确认 | ✅ 通过 |
---
## 🛡️ 幻觉检测场景
该框架在以下路径下包含一个受控的幻觉验证需求：
```text
requirements/GH-002-hallucination-challenge.md
```
故意对以下利益相关者建议保持未经验证：
* 输入信用卡详细信息
* 选择支付方式
* 应用折扣码
* 验证电子邮件收据
测试规划器将每个建议与以下内容进行比较：
1. 批准的验收标准
2. 当前的 SauceDemo 行为
3. Playwright MCP 浏览器证据
所有四个建议都被归类为：
```text
REJECTED_UNSUPPORTED
```
被拒绝的场景记录在：
```text
specs/rejected/GH-002-unsupported-scenarios.md
```
不支持的要求不会生成 Playwright 自动化。
---
## 🔎 场景分类
每个 AI 生成的场景必须被归类为以下之一：
| 分类 | 含义 |
| -------------------- | --------------------------------------------------------------- |
| `VERIFIED` | 得到需求和观察到的应用程序行为的支持 |
| `ASSUMPTION_REQUIRES_REVIEW` | 可能的场景，但需求证据不完整 |
| `REJECTED_UNSUPPORTED` | 不得到需求或当前应用程序的支持 |
只有标记为 `VERIFIED` 并由高级 QA 批准的场景才会传递给测试生成器。
---
## ⚙️ 设置和安装
### 先决条件
* Node.js 20+
* npm
* VS Code
* Git
* GitHub Copilot 或另一个兼容的 MCP 启用代理环境
### 克隆仓库
```bash
git clone https://github.com/Jiten20/playwright-agentic-quality-engineering-framework.git
cd playwright-agentic-quality-engineering-framework
```
### 安装依赖项
```bash
npm ci
```
### 安装 Playwright 浏览器
```bash
npx playwright install
```
对于 Linux 或 CI 环境：
```bash
npx playwright install --with-deps
```
---
## 🚀 运行测试
| 命令 | 描述 |
| ------------------------- | ------------------------------------- |
| `npm test` | 运行所有 Playwright 测试 |
| `npm run test:smoke` | 运行冒烟测试 |
| `npm run test:regression` | 运行回归测试 |
| `npm run test:headed` | 在 headed 模式下运行测试 |
| `npm run test:debug` | 使用 Playwright 调试模式运行测试 |
| `npm run typecheck` | 验证 TypeScript |
| `npm run report` | 打开 Playwright HTML 报告 |
### 示例
```bash
# 运行所有测试
npm test
# 运行冒烟测试
npm run test:smoke
# 运行回归测试
npm run test:regression
# 在 headed 模式下运行
npm run test:headed
# 验证 TypeScript
npm run typecheck
# 打开最新的 HTML 报告
npm run report
```
---
## 🏷️ GitHub 问题追踪
测试映射到 GitHub 问题和场景 ID。
示例：
```typescript
test(
'完成订单并验证确认',
{
tag: ['@smoke', '@GH-1', '@GH-001-SC05'],
annotation: {
type: 'github-issue',
description: 'GH-001 — 成功产品结账'
}
},
async ({ loginPage, productsPage, cartPage, checkoutPage }) => {
// 测试实现
}
);
```
追踪流程：
```text
GitHub 问题
↓
需求文件
↓
规划器测试计划
↓
QA 批准的场景
↓
生成的 Playwright 测试
↓
GitHub Actions 结果
```
---
## 🏗️ 设计方法
### 页面对象模型
该框架使用 **页面对象模型** 将可重用的应用程序行为与测试逻辑分离。
```text
测试文件
↓
自定义夹具
↓
页面对象
↓
Playwright 定位器和操作
↓
浏览器
```
优点：
* 减少代码重复
* 集中维护定位器
* 可重用页面操作
* 更干净的测试实现
* 更容易的框架扩展
---
### 自定义夹具
自定义夹具直接将页面对象注入测试。
示例：
```typescript
test(
'验证结账',
async ({
loginPage,
productsPage,
cartPage,
checkoutPage
}) => {
// 测试实现
}
);
```
优点：
* 更干净的测试
* 减少设置代码
* 可重用的依赖项
* 更好的测试隔离
* 延迟夹具初始化
---
### 测试步骤
该框架使用 `test.step()` 来表示业务级别的操作。
```typescript
await test.step('使用有效凭证登录', async () => {
await loginPage.login(username, password);
});
await test.step('完成结账', async () => {
await checkoutPage.completeCheckout();
});
```
优点：
* 更易读的 HTML 报告
* 更容易的故障诊断
* 清晰的测试执行流程
* 更好的跟踪可读性
---
## 🎯 定位器策略
该框架遵循 Playwright 定位器最佳实践。
| 优先级 | 定位器类型 | 示例 |
| -------- | -------------------- | ---------------------------------------- |
| ✅ 1 | `getByRole()` | `getByRole('button', { name: '登录' })` |
| ✅ 2 | `getByLabel()` | `getByLabel('用户名')` |
| ✅ 3 | `getByPlaceholder()` | `getByPlaceholder('用户名')` |
| ✅ 4 | `getByText()` | `getByText('产品')` |
| ✅ 5 | `getByTestId()` | `getByTestId('结账')` |
| ⚠️ 6 | 稳定的 CSS 选择器 | `[data-test="结账"]` |
避免：
* 脆弱的 XPath 定位器
* 长的 CSS 链
* `nth-child()` 选择器
* 基于样式的类
* 任意的 `waitForTimeout()` 调用
SauceDemo 使用 `data-test` 属性。该框架配置：
```typescript
use: {
testIdAttribute: 'data-test'
}
```
这允许：
```typescript
page.getByTestId('login-button');
```
---
## 📊 报告
Playwright HTML 报告在执行后自动生成。
打开本地报告：
```bash
npx playwright show-report
```
### 生成的证据
* HTML 报告
* 业务级别测试步骤
* 失败时的截图
* Playwright 跟踪
* 视频录制
* 错误消息和堆栈跟踪
生成的报告被排除在 Git 之外，并作为 GitHub Actions 工件上传。
---
## 🔄 CI/CD 集成
该项目使用 **GitHub Actions** 作为 Playwright 质量门控。
工作流：
```text
.github/workflows/playwright.yml
```
### 管道触发器
工作流在以下情况下执行：
* 推送到配置的分支
* 针对 `main` 的拉取请求
* 手动工作流执行
* 重新运行已完成的工作流作业
### 管道步骤
1. 检出仓库
2. 设置 Node.js
3. 使用 `npm ci` 安装依赖项
4. 安装 Playwright 浏览器
5. 执行 TypeScript 验证
6. 运行 Playwright 测试
7. 上传 HTML 报告
8. 上传故障证据
---
## ▶️ 手动执行 GitHub Actions 工作流
确保工作流包含：
```yaml
on:
workflow_dispatch:
push:
branches:
- main
pull_request:
branches:
- main
```
然后：
1. 在 GitHub 上打开仓库。
2. 选择 **Actions**。
3. 选择 **Playwright Quality Gate**。
4. 点击 **Run workflow**。
5. 选择分支。
6. 再次点击 **Run workflow**。
要重新运行现有的执行：
1. 打开 **Actions**。
2. 打开已完成的工作流运行。
3. 选择 **Re-run jobs**。
4. 选择 **Re-run all jobs**。
---
## 🧪 Playwright 配置
在以下文件中配置：
```text
playwright.config.ts
```
| 设置 | 值 | 目的 |
| ----------------- | --------------------------------------- | --------------------------------- |
| `testDir` | `./tests` | 测试位置 |
| `fullyParallel` | `true` | 启用并行安全执行 |
| `forbidOnly` | 仅限 CI | 防止提交的聚焦测试 |
| `retries` | 2 在 CI 中 | 重试失败的 CI 测试 |
| `workers` | 1 在 CI 中 | 提高 CI 稳定性 |
| `screenshot` | `only-on-failure` | 捕获失败的截图 |
| `trace` | `on-first-retry` 或 `retain-on-failure` | 支持诊断 |
| `video` | `retain-on-failure` | 记录失败的执行 |
| `testIdAttribute` | `data-test` | 支持 SauceDemo 测试属性 |
---
## 📝 `.gitignore`
```gitignore
# 依赖项
node_modules/
# Playwright 输出
playwright-report/
test-results/
blob-report/
# 构建输出
dist/
# 环境变量
.env
.env.*
# 操作系统文件
.DS_Store
Thumbs.db
```
---
## 🛠️ 技术栈
| 工具 | 目的 |
| --------------- | --------------------------------------- |
| Playwright | 浏览器自动化和测试执行 |
| TypeScript | 框架实现 |
| Playwright MCP | 浏览器探索用于 AI 代理 |
| GitHub MCP | 仓库、问题和 PR 交互 |
| GitHub 问题 | 需求和追踪 |
| GitHub 项目 | 代理工作流和 QA 审批跟踪 |
| GitHub Actions | 持续集成 |
| HTML 报告 | 测试执行报告 |
| VS Code | 启用 MCP 的开发环境 |
---
## 🔐 人工审批和治理
该框架应用以下控制：
* 规划器输出必须由高级 QA 审查。
* 不支持的要求不得自动化。
* 只有明确批准的场景才能生成。
* 生成器不得更改已批准的预期结果。
* 修复器不得删除有效的断言以使测试通过。
* AI 生成的更改不得直接提交到 `main`。
* 在合并前需要拉取请求审查。
* MCP 配置不得包含机密或个人访问令牌。
---
## 🚀 未来增强
* 使用 GitHub MCP 自动进行 GitHub 问题评论
* 自动创建功能分支和拉取请求
* 结构化故障分析报告
* 受控的自愈定位器概念验证
* 跨浏览器执行
* 使用 Playwright 进行 API 测试
* DEV、QA 和 UAT 的环境支持
* Docker 执行
* Allure 报告
* 基于 RAG 的历史需求、缺陷和报告检索
---
## 📌 主要亮点
* Playwright + TypeScript
* Playwright MCP 浏览器探索
* 多智能体规划器、生成器和修复器工作流
* GitHub 问题追踪
* 基于证据的 AI 测试规划
* 人工 QA 审批门控
* 幻觉检测和拒绝
* 页面对象模型
* 自定义夹具
* Web-first 断言
* HTML 报告
* 失败时的截图、跟踪和视频
* GitHub Actions CI/CD 质量门控
* 可维护和可扩展的框架设计
连接信息
猜你喜欢
暂无推荐服务器