内容
# Conduit Playwright 测试框架
这是一个全面的端到端测试框架，针对使用 Playwright 和 TypeScript 构建的 [Conduit](https://conduit.bondaracademy.com/) 应用程序。该企业级框架展示了测试自动化的最佳实践，包括页面对象模型、测试夹具、并行执行和全面报告。
## 目录
- [概述](#overview)
- [关键特性](#key-features)
- [项目结构](#project-structure)
- [先决条件](#prerequisites)
- [安装](#installation)
- [运行测试](#running-tests)
- [基本测试命令](#basic-test-commands)
- [高级测试命令](#advanced-test-commands)
- [环境变量](#environment-variables)
- [日志配置](#logging-configuration)
- [测试报告](#test-reports)
- [Playwright HTML 报告](#playwright-html-reports)
- [Allure 报告](#allure-reports)
- [认证系统](#authentication-system)
- [测试数据管理](#test-data-management)
- [页面对象模型](#page-object-model)
- [测试夹具](#test-fixtures)
- [工具与辅助脚本](#utilities--helper-scripts)
- [最佳实践](#best-practices)
- [CI/CD 集成](#cicd-integration)
- [故障排除](#troubleshooting)
## 概述
这个企业级测试框架自动化测试Conduit应用程序（一个Medium.com的克隆），重点关注可靠性、可维护性和性能。该框架遵循SOLID原则，并实施行业最佳实践以构建测试架构。
## 关键特性
- **🏗️ 架构**
- 页面对象模型（Page Object Model）以清晰分离关注点
- 使用 TypeScript 实现类型安全
- 工作者范围的身份验证以支持并行测试执行
- 单例模式用于资源管理
- 模块化和可扩展的设计
- **🔄 测试执行**
- 在多个工作者之间并行执行测试
- 跨浏览器测试（Chromium、Firefox、WebKit）
- 移动视口测试的设备仿真
- 可配置的重试机制以处理不稳定的测试
- 细粒度的测试过滤选项
- **📊 报告**
- 内置 Playwright HTML 报告
- Allure 报告提供丰富的测试分析
- 测试失败时截图捕获
- 调试用的追踪记录
- 测试历史跟踪
- **🔐 身份验证**
- 缓存的身份验证状态以加快测试执行
- 特定于工作者的身份验证以防止冲突
- 基于 API 的身份验证快捷方式
- 运行之间会话状态持久化
- **📝 测试数据**
- 动态测试数据生成
- 测试数据清理机制
- 用于调试的数据持久化
- 基于 API 的测试数据创建
- **🧩 扩展**
- 与 Playwright 的模型上下文协议（Model-Context Protocol, MCP）兼容
- Context7 集成能力
- 自定义命令行工具
## 项目结构
```
conduit-playwright-tests/
├── playwright.config.ts # Playwright 配置
├── package.json # 项目依赖
├── run-playwright-tests.sh # 运行测试的 Shell 脚本，带选项
├── src/
│ ├── fixtures/ # 测试夹具
│ │ ├── AuthFixture.ts # 认证夹具
│ │ ├── BaseFixture.ts # 所有测试的基础夹具
│ │ ├── PageFixture.ts # 页面对象夹具
│ │ ├── TestDataFixture.ts # 测试数据夹具
│ │ └── globalSetup.ts # 测试的全局设置
│ ├── manager/ # 管理器
│ │ └── PageManager.ts # 页面对象的中央管理器
│ ├── pages/ # 页面对象模型
│ │ ├── BasePage.ts # 具有通用功能的基础页面
│ │ ├── EditorPage.ts # 文章编辑页面
│ │ ├── HomePage.ts # 首页
│ │ ├── LoginPage.ts # 登录页面
│ │ └── RegisterPage.ts # 注册页面
│ └── utils/ # 工具函数
│ ├── ApiClient.ts # 后端调用的 API 客户端
│ ├── AuthManager.ts # 认证管理器
│ ├── TestDataGenerator.ts # 测试数据生成
│ └── TestDataManager.ts # 测试数据管理和清理
└── tests/ # 测试文件
├── article-creation.spec.ts # 文章创建测试
├── auth.setup.ts # 认证设置
└── registration.spec.ts # 用户注册测试
```
## 先决条件
- Node.js (v16+)
- npm 或 yarn
- 用于 Allure 报告的 Java 运行环境 (JRE)
- 支持的浏览器将由 Playwright 自动安装
## 安装
1. 克隆代码库：
```bash
git clone <repository-url>
cd conduit-playwright-tests
```
2. 安装依赖：
```bash
npm install
```
3. 安装浏览器：
```bash
npx playwright install
```
4. 安装 Allure 命令行工具（可选，用于高级报告）：
```bash
npm install -g allure-commandline
```
## 运行测试
### 基本测试命令
以无头模式运行所有测试：
```bash
npx playwright test
```
以 UI 模式运行测试：
```bash
npx playwright test --ui
```
在特定浏览器中运行测试：
```bash
npx playwright test --project=chromium
npx playwright test --project=firefox
npx playwright test --project=webkit
```
运行特定测试文件：
```bash
npx playwright test tests/registration.spec.ts
```
按标题过滤运行测试：
```bash
npx playwright test -g "should register a new user"
```
### 高级测试命令
使用有头浏览器运行测试：
```bash
npx playwright test --headed
```
使用调试模式运行测试：
```bash
npx playwright test --debug
```
使用特定并发运行测试：
```bash
npx playwright test --workers=4
```
运行带有追踪记录的测试：
```bash
npx playwright test --trace=on
```
运行带有视频录制的测试：
```bash
npx playwright test --video=on
```
使用带有常见选项的 shell 脚本运行测试：
```bash
./run-playwright-tests.sh --browser=chromium --headless --retries=2
```
该 shell 脚本支持以下选项：
- `--browser`: chromium, firefox, webkit 或 all（默认值：all）
- `--headless`: true 或 false（默认值：true）
- `--retries`: 失败测试的重试次数（默认值：1）
- `--workers`: 并行工作线程的数量（默认值：CPU 核心的 50%）
- `--reporter`: 使用的报告工具（默认值：list,allure-playwright）
### 环境变量
该框架支持以下环境变量：
| 变量 | 描述 | 默认值 |
| ------------------ | ------------------------------------ | ---------------------------------- |
| BASE_URL | 应用程序的基础 URL | https://conduit.bondaracademy.com |
| TIMEOUT | 默认超时时间（毫秒） | 30000 |
| RETRY_COUNT | 失败测试的重试次数 | 1 |
| BROWSER | 测试使用的浏览器 | chromium |
| CLEANUP_TEST_DATA | 是否清理测试数据 | false |
| DEBUG_LOGS | 启用详细调试日志 | false |
| TEST_ENV | 测试环境（dev/staging/prod） | dev |
示例：
```bash
BASE_URL=https://staging.conduit.com BROWSER=firefox npx playwright test
```
### 日志配置
该框架默认为发布版本提供了清晰的日志记录。为了调试目的，您可以启用额外的日志：
```bash
DEBUG_LOGS=true npx playwright test
```
要获得最少的日志输出，可以使用安静选项运行测试：
```bash
npx playwright test --quiet
```
## 测试报告
### Playwright HTML 报告
要在测试执行后查看 Playwright HTML 报告：
```bash
npx playwright show-report
```
这将会在您的默认浏览器中打开 HTML 报告，显示：
- 测试结果摘要
- 测试执行时间线
- 测试失败的截图
- 详细日志和错误信息
- 用于调试的 Trace viewer
示例输出：
```
Running 25 tests using 5 workers
✓ registration.spec.ts:18:3 › should register a new user (1.2s)
✓ registration.spec.ts:42:3 › should show validation error for existing username (1.8s)
...
```
### Allure 报告
该框架提供全面的 Allure 报告，以便进行高级测试分析：
生成并查看 Allure 报告：
```bash
```
# 从结果生成 Allure 报告
npx allure generate allure-results --clean
# 本地服务报告（自动在浏览器中打开）
npx allure serve allure-results
```
#### 使用 Allure 报告运行测试
要运行测试并在一个命令中自动生成 Allure 报告，可以使用以下命令：
```bash
```
# 运行测试并生成 Allure 报告
npx playwright test && npx allure generate allure-results --clean && npx allure open allure-report
```
或者使用以下单独步骤：
```bash
# 步骤 1：运行测试（Allure 结果会自动生成）
npx playwright test
# 步骤 2：从结果生成 HTML 报告
npx allure generate allure-results --clean
# 步骤 3：在默认浏览器中打开报告
npx allure open allure-report
```
对于 CI（持续集成）环境，您可以使用：
```bash
# 使用显式的 Allure reporter 配置运行测试
npx playwright test --reporter=list,allure-playwright
```
#### 在测试运行之间管理 Allure 结果
⚠️ **重要提示：** Allure 结果在测试运行之间会累积，这可能导致报告产生误导。例如，仅运行 chromium 测试可能会显示之前 firefox 或 webkit 运行的结果。
为了确保您的报告仅显示当前测试运行的结果，请在运行测试之前清空 allure-results 目录：
```bash
```
# 在运行测试之前清除之前的结果
rm -rf allure-results/* && npx playwright test --project=chromium
# 然后生成报告
npx allure generate allure-results --clean && npx allure open allure-report
```
对于 macOS/Linux 用户，您可以使用以下一体化命令：
```bash
rm -rf allure-results/* && npx playwright test --project=chromium && npx allure generate allure-results --clean && npx allure open allure-report
```
对于 Windows 用户：
```bash
rmdir /s /q allure-results && mkdir allure-results && npx playwright test --project=chromium && npx allure generate allure-results --clean && npx allure open allure-report
```
Allure 报告提供：
- 测试执行统计和趋势
- 环境信息
- 测试用例持续时间细分
- 失败分析
- 截图和追踪集成
- 分类的测试失败
## 认证系统
该框架实现了一个复杂的认证系统，具有几个关键特性：
### 工作线程范围的身份验证
并行运行的测试每个都有自己的认证用户：
```typescript
// 来自 BaseFixture.ts 的示例
workerAuth: [
async ({ browser, testData }, use, workerInfo) => {
const workerAuthPath = path.join(AUTH_DIR, `worker-auth-${workerInfo.workerIndex}.json`);
// 加载或创建该工作线程的身份验证状态
// ...
await use({ context, credentials, testUser });
},
{ scope: 'worker' },
],
```
### 认证状态缓存
认证状态被缓存到磁盘，以加快测试执行速度：
```typescript
// 保存认证状态
await context.storageState({ path: workerAuthPath });
// 加载现有的认证状态
context = await browser.newContext({
storageState: workerAuthPath,
});
```
### API 认证快捷方式
对于不需要 UI 登录的测试：
```typescript
// 测试中的示例用法
test('使用认证用户创建文章', async ({ authenticatedPage }) => {
const { page, pageManager, credentials } = authenticatedPage;
// 测试可以立即使用认证用户
});
```
## 测试数据管理
### 动态测试数据生成
```typescript
// 生成唯一的测试数据
const username = TestDataGenerator.generateUsername();
const email = TestDataGenerator.generateEmail();
const password = TestDataGenerator.generatePassword();
const title = TestDataGenerator.generateArticleTitle();
```
### 测试数据清理
该框架包括自动清理测试数据的功能：
```typescript
// 示例用法
await testDataManager.cleanupTestData(24); // 清理超过24小时的数据
```
### 基于API的数据创建
为了更快的测试设置：
```typescript
// 通过API创建文章，而不是通过UI
const article = await testDataManager.createArticle(author, true);
```
## 页面对象模型 (Page Object Model)
页面对象模型是一种设计模式，旨在提高自动化测试的可维护性和可读性。在这种模式中，每个页面都被表示为一个对象，封装了与该页面相关的操作和元素。通过将页面的操作与测试逻辑分离，页面对象模型使得测试代码更加简洁和易于理解。
### 优点
- **可维护性**：当页面发生变化时，只需更新页面对象，而不必修改所有测试用例。
- **可重用性**：页面对象可以在多个测试用例中重用，减少代码重复。
- **可读性**：测试用例更接近于自然语言，易于理解。
### 实现
在实现页面对象模型时，通常会创建一个类来表示每个页面，并在该类中定义与页面元素交互的方法。例如：
```python
class LoginPage:
def __init__(self, driver):
self.driver = driver
self.username_input = driver.find_element_by_id("username")
self.password_input = driver.find_element_by_id("password")
self.login_button = driver.find_element_by_id("login")
def login(self, username, password):
self.username_input.send_keys(username)
self.password_input.send_keys(password)
self.login_button.click()
```
在测试用例中，可以使用页面对象来执行操作：
```python
def test_login():
login_page = LoginPage(driver)
login_page.login("user", "pass")
```
通过这种方式，测试用例的逻辑与页面的实现细节分离，使得测试更加稳定和易于维护。
### 页面管理器模式
该框架使用集中式的页面管理器来访问页面对象：
```typescript
// 测试中的示例用法
test('应该创建一篇文章', async ({ page, pageManager }) => {
const editorPage = pageManager.editorPage;
await editorPage.navigate();
await editorPage.fillArticleForm(title, description, content);
await editorPage.publishArticle();
});
```
### 基于接口的设计
所有页面对象实现接口以提高可维护性：
```typescript
export interface IEditorPage {
navigate(): Promise<void>;
fillArticleForm(title: string, description: string, body: string, tags?: string[]): Promise<void>;
publishArticle(): Promise<void>;
}
export class EditorPage extends BasePage implements IEditorPage {
// 实现
}
```
## 测试夹具
该框架提供了几个自定义夹具，以增强测试的可靠性：
### 基础夹具
```typescript
// 使用夹具的示例测试
test('应当使用经过身份验证的用户创建文章', async ({ authenticatedPage, baseURL }) => {
const { page, pageManager, credentials } = authenticatedPage;
// 测试代码
});
```
### 测试数据固定装置
```typescript
// 测试数据固定装置的示例用法
test('应该创建一篇文章', async ({ testData }) => {
const user = await testData.registerAndLoginUser();
const article = await testData.createArticle(user);
// 测试代码
});
```
## 工具与辅助脚本
### 分割测试工具
将测试文件分割成单独的文件以增加并行性：
```bash
node split-tests.js
```
这将在子目录中创建单独的测试文件：
- `tests/registration/` - 分割注册测试
- `tests/articles/` - 分割文章测试
### 测试数据管理器
`TestDataManager` 类提供以下功能：
- 创建测试用户
- 创建测试文章
- 管理测试数据
- 清理旧的测试数据
```typescript
// 示例用法
const manager = TestDataManager.getInstance(baseUrl);
const user = await manager.createUser(true); // true = 通过 API 注册
const article = await manager.createArticle(user, true);
```
## 最佳实践
该框架遵循以下最佳实践：
### KISS（保持简单，愚蠢）
- 干净、可读的测试代码
- 发布模式下最小化日志记录
- 每个组件单一职责
### DRY（不要重复自己）
- 共享的固定装置用于常见功能
- 页面对象模型（Page Object Model）用于用户界面交互
- 用于常见任务的辅助工具
### SOLID 原则
- 单一职责原则：每个类只有一个职责
- 开放/封闭原则：框架可以在不修改的情况下扩展
- 里氏替换原则：页面接口可以被替换
- 接口隔离原则：为每个组件提供特定的接口
- 依赖倒置原则：高层模块依赖于抽象
## CI/CD 集成
该框架旨在在 CI（持续集成）环境中运行，具备以下功能：
### 并行执行
配置并行工作者的数量：
```bash
npx playwright test --workers=4
```
### 报告集成
生成 Playwright 和 Allure 报告：
```bash
```
# 添加到您的 CI 脚本
```
npx playwright test --reporter=list,allure-playwright
npx allure generate allure-results --clean
```
### 重试逻辑
为不稳定的测试配置重试：
```bash
npx playwright test --retries=2
```
### CI 示例
GitHub Actions 示例：
```yaml
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
- name: 安装依赖
run: npm ci
- name: 安装 Playwright 浏览器
run: npx playwright install --with-deps
- name: 运行测试
run: npx playwright test
- name: 生成 Allure 报告
if: always()
run: npx allure generate allure-results --clean
# 上传工件
- uses: actions/upload-artifact@v3
if: always()
with:
name: playwright-report
path: playwright-report/
retention-days: 30
```
## 故障排除
### 常见问题
**认证问题**
- 删除 `.auth` 目录以重置认证状态
- 检查应用程序的 API 端点是否已更改
**测试数据问题**
- 清空 `.test-data` 目录以重置测试数据
- 检查应用程序是否已重置或数据是否已清理
**报告问题**
- 确保已安装 Java 以支持 Allure 报告
- 清空 `allure-results` 目录以生成新的报告
### 调试模式
在调试模式下运行测试以诊断问题：
```bash
DEBUG_LOGS=true npx playwright test --debug
```
### 跟踪查看器
使用跟踪查看器分析测试执行：
```bash
npx playwright test --trace=on
npx playwright show-report
```
然后点击任意测试的跟踪图标以打开跟踪查看器。
### 使用 Playwright Trace Viewer
Playwright 提供了一个强大的追踪查看器，通过捕获详细的执行信息来帮助调试测试失败。
#### 从 HTML 报告中打开追踪
查看追踪的最简单方法是直接从 HTML 报告中：
1. 生成带有追踪的 HTML 报告：
```bash
npx playwright test --trace=on
```
2. 打开 HTML 报告：
```bash
npx playwright show-report
```
3. 在报告中导航到一个测试，并点击“Trace”按钮（链条图标）以打开追踪查看器。
#### 打开下载的追踪文件
您还可以从 HTML 报告中下载追踪文件 (.zip) 并稍后查看：
1. 在 HTML 报告中，点击您想要保存的追踪旁边的下载图标。
2. 使用 Playwright 的追踪查看器命令打开下载的追踪文件：
```bash
npx playwright show-trace path/to/trace.zip
```
3. 例如，要打开 test-results 文件夹中的追踪：
```bash
npx playwright show-trace test-results/my-test/trace.zip
```
#### Trace Viewer 功能
Playwright 的 trace viewer 提供了几个强大的功能：
- **时间线视图**：在时间线上可视化操作、事件和截图。
- **快照**：查看每个操作点的 DOM 快照。
- **网络**：检查测试执行期间发出的网络请求。
- **控制台**：查看测试期间发生的控制台日志。
- **源代码**：查看触发每个操作的测试源代码。
- **错误**：快速识别和分析测试期间发生的错误。
#### 配置追踪选项
项目的 `playwright.config.ts` 配置追踪记录如下：
```typescript
trace: 'on-first-retry'; // 选项：'on', 'off', 'on-first-retry', 'retain-on-failure'
```
要为所有测试运行启用追踪：
```bash
npx playwright test --trace=on
```
要获取更详细的追踪，包括截图和快照：
```bash
npx playwright test --trace=on --trace-screenshots=on
```
### 手动浏览器启动
用于直接调试：
```bash
npx playwright open https://conduit.bondaracademy.com
```
连接信息
猜你喜欢
暂无推荐服务器