Jayakumar-lab/Enterprise-Playwright-Framework-TypeScript-

# 企业级 Playwright 框架 (TypeScript) 生产级、对 CI 友好的 Playwright Test 框架脚手架，包含 UI E2E、API 测试、组件测试（如适用）、无障碍检查（axe-core）以及视觉回归示例。 ## 功能 - **多项目 Playwright 配置**：Chromium/Firefox/WebKit，并行 worker - **可靠性**： - 健壮的 locator + 确定性的导航 - 失败时输出 traces/截图/视频 - 重试策略（对 CI 友好） - 全局 setup hooks - **框架分层**： - `src/config` — 环境加载 + 类型安全的 config - `src/core` — fixtures、日志、correlation id、全局 setup/teardown - `src/pages` — POM 抽象 - `src/api` — 类型安全的 API client 封装 + schema 校验 - `src/assertions`, `src/utils` — 可复用的 helper（如果存在） - **测试分类**（通过诸如 `@smoke`、`@api` 等 tag 划分） - **可观测性产物**： - `playwright-report/` - `test-results/` - 每次测试运行的 trace/视频/截图产物 - **MCP 集成**： - `/.vscode/mcp.json` 注册了 Playwright MCP server，以支持 Copilot Agent Mode ## 前置条件 - Node.js（推荐 LTS 版本） - Playwright 浏览器 - （可选）Docker，用于类似网格的执行环境 ### 安装浏览器 ``` npx playwright install --with-deps ``` ## 快速开始 ### 1) 安装依赖 ``` npm ci ``` ### 2) 运行 UI 冒烟测试 (Chromium) ``` npx playwright test src/ui/automationExercise.spec.ts --project=chromium ``` ### 3) 运行全套测试（所有项目中的所有测试） ``` npx playwright test ``` ### 4) 打开 HTML 报告 ``` npx playwright show-report ``` ## 配置 ### 环境变量 环境由 `src/config/env.ts` / `src/config/app.ts` 加载。 常用变量： - `BASE_URL` — 覆盖示例测试使用的默认 base URL。 如果未设置 `BASE_URL`，框架将默认使用： - `https://automationexercise.com/test_cases` ### 敏感信息处理（安全友好） - Secret 必须通过环境变量提供。 - 不得将任何 secret 提交到代码仓库。 ## 仓库结构 关键目录： - `playwright.config.ts` — Playwright 项目 + reporter + 产物规则 - `src/core` — fixtures、全局 hooks、日志/correlation - `src/config` — 环境 config + 类型安全的 config 加载器 - `src/pages` — 页面对象模型（selectors/actions/assertions 分离） - `src/api` — request-context client 封装 + schema 校验 - `src/ui` — UI E2E 示例 - `src/api` — API 示例 - `src/component` — 组件测试示例（隔离 harness） - `src/accessibility` — axe-core 检查 - `src/visual` — 视觉快照示例 - `/.vscode/mcp.json` — Playwright MCP 注册 ## 运行子集 ### 列出测试 ``` npx playwright test --list ``` ### 仅运行 Chromium ``` npx playwright test --project=chromium ``` ### 分片执行（示例） ``` npx playwright test --shard=1/3 ``` ## 产物与调试 失败时，框架配置为输出以下内容： - **HTML 报告**：`playwright-report/` - **JUnit**：`test-results/junit/results.xml` - **单次测试产物**： - 截图 - 视频 - trace ### 产物位置 - `playwright-report/` - `test-results/` - `playwright-artifacts/` ## 添加新测试 ### 1) UI E2E 测试 (POM) 模式： - 在 `src/pages/**` 下创建/扩展页面对象 - 在 `src/ui/**` 下添加测试 - 使用 tag： - `@smoke`, `@regression`, `@ui` 等 ### 2) API 测试 使用 Playwright `request` fixture（通过框架 fixtures 提供）并保持： - endpoint 封装位于 `src/api/**` - 通过 `src/api/schemas.ts` 中的 schema 校验进行响应验证 ### 3) 无障碍测试 在 `src/accessibility/**` 下添加测试并运行 axe-core 检查。 ### 4) 视觉快照测试 使用 snapshot matcher 在 `src/visual/**` 下添加测试。 ## 故障排除 ### 常见问题 **1) 导航超时 / base URL 错误** - 确认 `BASE_URL` 设置正确。 - 默认 base URL 为 `https://automationexercise.com/test_cases`。 **2) 缺少 storage state** - 框架对 storageState 的使用进行了保护，这样在全新环境中如果不存在认证状态也不会失败。 **3) 不稳定的 locator** - 优先使用稳定的属性（`data-testid`、语义化 role） - 尽可能避免脆弱的 XPath - 如果存在动态内容，请使用 Playwright 的确定性等待（例如 `locator.waitFor()`） ### 调试工作流 - 附带 trace 重新运行失败的测试： ``` npx playwright test --project=chromium --trace on ``` - 通过 Playwright 报告从测试输出中打开 trace。 ## CI/CD 本仓库包含 CI 配置示例： - **GitHub Actions**：`/.github/workflows/ci.yml` - **Azure DevOps**：`/.azure-pipelines/`（如果存在） - **Jenkins**：`./jenkins/`（如果存在） ### 预期的 CI 行为 - 使用 `npm ci` - 缓存 `~/.cache/ms-playwright`（或等效的 Playwright 缓存） - 上传 `test-results/` 和 `playwright-report/` ## MCP：Playwright MCP server (VS Code Copilot Agent Mode) 本仓库包含一个 VS Code MCP 注册文件： - `/.vscode/mcp.json` 它使用 `@playwright/mcp` 注册了 Playwright MCP，以支持 agent 工作流。 ### 如何使用带有 Playwright MCP 的 Copilot Agent Mode Agent 提示示例： 1. **用户旅程 → 生成 Playwright 测试** - “导航到 ，使用 登录，创建实体 ，验证 ，生成 Playwright 测试代码。” 2. **基于无障碍访问改进 locator** - “使用 MCP 工具检查无障碍树 (accessibility tree)，并提出稳定的 locator。” 3. **从清单生成冒烟测试套件** - “根据用户旅程清单生成冒烟测试套件。” ## 合规 / 安全说明 - 切勿提交 secret。 - 如果您添加了请求/响应的日志记录，请确保掩盖敏感值（例如，Authorization header、cookie）。 ## 命令参考 - 运行：`npx playwright test` - 列出：`npx playwright test --list` - 报告：`npx playwright show-report` - 打开 JUnit：`test-results/junit/results.xml`

标签：API测试, LNA, MITM代理, Playwright, TypeScript, UI测试, 可访问性测试, 后端开发, 安全插件, 特征检测, 端到端测试, 请求拦截