前言¶
前端項目上線前，單元測試能覆蓋函數邏輯，卻常常覆蓋不了「用戶真的點得動、頁面真的打得開」。端到端（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
