前言¶
前端项目上线前，单元测试能覆盖函数逻辑，却常常覆盖不了「用户真的点得动、页面真的打得开」。端到端（E2E）测试用真实浏览器走一遍关键流程，是质量保障里性价比很高的一环。但要把 Playwright 装起来、写好 playwright.config.ts、补 smoke test、配 npm 脚本、接 GitHub Actions，往往要翻好几份文档，还容易漏掉 .gitignore 或 CI 里浏览器依赖的安装步骤。
如果你已经在用 Cursor、Claude Code 等 AI 编程工具，可以把这套流程交给 Agent——前提是它知道「从零搭 E2E」的标准步骤。adding-e2e-tests 就是为此写的一份 Agent Skill：一份 SKILL.md 指令文件，教 Agent 按固定流程在你的项目里落地 Playwright 测试。
这是什么¶
adding-e2e-tests 出自社区维护的 awesome-cursor-skills 仓库，由 spencerpauly 整理收录，归类在仓库的 Testing 分类下。它遵循通用的 Agent Skills 格式（SKILL.md + YAML frontmatter），可在 Cursor、Claude Code、Codex CLI 等支持该格式的 AI 编程工具中使用。
Skill 的官方描述是：Set up Playwright end-to-end testing in a project, including test configuration, example tests, and CI integration. 换句话说，它不是帮你「跑一下现有测试」，而是指导 Agent 从零搭建 Playwright E2E 基础设施——安装依赖、生成配置、写示例用例、接 CI，一步不漏。
与同仓库里的 recording-browser-flow-as-test（把浏览器操作录制成测试）互补；与 Anthropic 官方的 webapp-testing（侧重用 Playwright 验证已运行的 Web 应用）相比，adding-e2e-tests 更聚焦「项目里还没有 E2E 框架时，如何一次性搭好」。
核心功能与亮点¶
根据官方 SKILL.md，Agent 在加载该 Skill 后，会按以下能力协助你：
1. Playwright 安装与初始化
- 新项目推荐
npm init playwright@latest，自动生成playwright.config.ts、tests/目录并安装浏览器。 - 若项目已有其他测试框架，可手动安装：
npm install -D @playwright/test
npx playwright install
2. 配置文件规范
- 设置
baseURL指向本地开发服务器（如http://localhost:3000）。 - 配置
webServer，让测试前自动启动 dev server：
webServer: {
command: "npm run dev",
url: "http://localhost:3000",
reuseExistingServer: !process.env.CI,
},
- 本地开发只启用 Chromium 以提速；CI 环境启用全部浏览器做跨浏览器验证。
3. Smoke Test 与 Page Object
- 生成基础冒烟测试，验证首页能否加载：
import { test, expect } from "@playwright/test";
test("homepage loads", async ({ page }) => {
await page.goto("/");
await expect(page).toHaveTitle(/.+/);
});
- 对较大应用，建议创建
tests/pages/目录，用 Page Object 模式封装选择器与操作。
4. npm 脚本与忽略规则
- 在
package.json中添加：
{
"test:e2e": "playwright test",
"test:e2e:ui": "playwright test --ui"
}
- 在
.gitignore中排除test-results/、playwright-report/、blob-report/。
5. CI 集成
- 在 GitHub Actions 中执行
npx playwright install --with-deps，再跑npm run test:e2e。 - 失败时用官方
actions/upload-artifact上传 HTML 报告，便于排查。
6. 编写最佳实践（Notes）
- 选择器优先用
data-testid，避免依赖易变的 CSS class。 - 用
test.describe分组相关用例。 - 可用
npx playwright codegen交互式录制测试。
测试自动化是 AI Agent 最有价值的应用场景之一：Agent 能按 Skill 逐步执行命令、改配置、写文件，比每次口头描述「帮我加 E2E」更稳定、可复现。
安装与启用¶
方式一：手动复制（Cursor 官方推荐路径）¶
awesome-cursor-skills README 说明，Skill 文件可复制到 .cursor/skills/ 目录，Agent 会自动发现。操作步骤：
- 从仓库下载
resources/adding-e2e-tests/SKILL.md。 - 放到项目目录：
.cursor/skills/adding-e2e-tests/SKILL.md（全局可用则放到~/.cursor/skills/）。
方式二：使用 npx skills CLI¶
vercel-labs/skills 是 Agent Skills 生态的通用安装工具，skills.sh 上也可查到该 Skill 的安装命令：
# 安装到 Cursor
npx skills add spencerpauly/awesome-cursor-skills --skill adding-e2e-tests -a cursor
# 安装到 Claude Code
npx skills add spencerpauly/awesome-cursor-skills --skill adding-e2e-tests -a claude-code
-g 可安装到用户全局目录；-y 跳过交互确认，适合脚本化场景。
触发条件¶
官方 Skill 写明：当用户要求 添加端到端测试、浏览器测试、集成测试，或搭建 Playwright 时，Agent 应启用此 Skill。你可以在对话中直接说：
给这个项目加上 Playwright E2E 测试，包括 CI。
Agent 会按 Skill 中的七步流程执行，而不是随意跳过配置或 CI 步骤。
典型用法示例¶
下面是一次完整对话可能触发的 Agent 行为（步骤均来自官方 SKILL.md）：
第一步：安装 Playwright
Agent 执行 npm init playwright@latest（或手动安装路径），创建配置文件与 tests/ 目录。
第二步：改写 playwright.config.ts
填入 baseURL、webServer，并按本地/CI 区分浏览器项目。
第三步：写 smoke test
在 tests/ 下创建首页加载测试，确保最基础的路径可跑通。
第四步（可选）：Page Object
若项目页面较多，在 tests/pages/ 下为登录页、仪表盘等封装 page object。
第五步：package.json 脚本
添加 test:e2e 与 test:e2e:ui，本地调试可用 UI 模式：
npm run test:e2e:ui
第六步：.gitignore
排除 Playwright 运行产物，避免误提交大体积报告。
第七步：GitHub Actions
在 workflow 中加入浏览器依赖安装与测试命令；失败时上传 playwright-report 供下载查看。
整个流程与 Playwright 官方文档 一致，Skill 的价值在于把分散的文档要点收成 Agent 可执行的 checklist，减少遗漏。
适用场景与注意事项¶
适合谁用¶
- 前端 / 全栈项目尚未接入 E2E，希望快速建立 Playwright 基线。
- 团队刚引入 AI 编程助手，想把「搭测试环境」标准化，避免每人 prompt 不一致。
- 需要 CI 门禁：Skill 明确要求 GitHub Actions 集成，适合已用 GitHub 的项目。
使用注意¶
- 技术栈：Skill 示例基于 Node.js + npm；若项目用 pnpm/yarn，dev server 命令与安装命令需 Agent 按项目实际情况调整，Skill 本身未写死包管理器。
- 与 webapp-testing 的分工：Anthropic 的 webapp-testing 偏「已有服务时的验证与调试」；adding-e2e-tests 偏「脚手架与工程化落地」。两者可并存，不冲突。
- 端口与 URL：
baseURL、webServer.url需与项目真实 dev server 一致；Skill 以3000为例，Agent 应结合package.json的dev脚本修改。 - CI 环境：务必使用
npx playwright install --with-deps，否则 Linux runner 上常因缺少系统库而失败。 - 选择器策略：Skill 强调
data-testid；若现有代码未埋点，Agent 可能需在组件中补充属性，或与你确认是否改用 role/text 定位。
同仓库相关 Skill¶
awesome-cursor-skills 测试类还有 writing-tests（单元/集成测试）、api-smoke-testing（API 冒烟）等。E2E 搭好后，可再配合 grinding-until-pass 让 Agent 循环修测直到通过。
小结¶
adding-e2e-tests 把「Playwright 从零到 CI」拆成 Agent 可逐步执行的七步清单：安装、配置、冒烟测试、脚本、忽略规则、流水线集成，外加选择器与 codegen 等实践建议。对经常让 AI 改前端、又希望质量门禁跟上的开发者来说，装一份 Skill 比每次重新口述需求更省事。
官方 Skill 与源码地址：
https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/adding-e2e-tests
