diff --git a/skills-dev/dev-test-plugin/skills/dev-test/SKILL.md b/skills-dev/dev-test-plugin/skills/dev-test/SKILL.md index d2cb350..bf8ad79 100644 --- a/skills-dev/dev-test-plugin/skills/dev-test/SKILL.md +++ b/skills-dev/dev-test-plugin/skills/dev-test/SKILL.md @@ -15,6 +15,7 @@ description: 软件测试技能。用于单元测试、集成测试、E2E测试 | `android-testing.md` | Android 测试 (JUnit + Espresso + Compose) | | `e2e-testing.md` | E2E Playwright：API Mock 冒烟测试（无后端）+ 全链路集成测试 | | `templates/go-integration-test.md` | Go 集成测试模板（多步骤 API 流程、中间件验证、租户隔离） | +| `templates/pdv-smoke-spec.md` | PDV 部署后验收 Playwright 模板（页面可达、菜单可见、API 连通） | --- @@ -50,6 +51,7 @@ description: 软件测试技能。用于单元测试、集成测试、E2E测试 | E2E (Mock 冒烟) | `npm run test:e2e:smoke-mock` | `e2e-testing.md` §API Mock | | E2E (全链路) | `npm run test:e2e` | `e2e-testing.md` §全链路 | | E2E (Coolbuy PaaS) | `make e2e` | `e2e-testing.md` §Coolbuy | +| E2E (部署后验收 PDV) | `E2E_BASE_URL= npx playwright test e2e/pdv/` | §PDV | --- @@ -145,6 +147,60 @@ ai-proj task append-doc --id --content "# 测试报告 --- +## 部署后 E2E 验收 (PDV — Post-Deploy Verification) + +部署后验收是独立于 TG4 的 E2E 冒烟模式，在 `/req deploy` 健康检查通过后执行。 + +### PDV vs TG4 区别 + +| 维度 | TG4 (开发阶段 E2E 冒烟) | PDV (部署后验收) | +|------|------------------------|-----------------| +| **触发时机** | `/req test` Gate 4 | `/req deploy` 步骤 6 | +| **环境** | 本地开发环境，API Mock | 真实部署环境 (staging/prod) | +| **目的** | 验证前端逻辑、UI 渲染 | 验证功能入口可达、基本可用 | +| **API** | `page.route()` 拦截 | 真实后端 API | +| **范围** | 回归冒烟 | 仅新功能可达性 | + +### PDV 检查项 + +| 检查项 | 说明 | 示例 | +|--------|------|------| +| **页面可达** | 需求涉及的前端页面返回 200 | `/okr/my`, `/okr/team` | +| **菜单可见** | 新增菜单项在侧栏中出现 | OKR 菜单对目标用户角色可见 | +| **基础渲染** | 页面无白屏/JS 报错 | 页面有预期的标题/组件 | +| **API 连通** | 关键 API 带 token 调用返回正常 | `GET /api/v1/okr/objectives` 返回 200 | + +### PDV 不做什么 + +- 不做完整回归测试（那是 TG4 的事） +- 不测试复杂业务流程（如多步骤表单提交） +- 不替代手动验收 +- 只做「功能入口可达 + 基本可用」的冒烟验证 + +### PDV 执行方式 + +```bash +E2E_BASE_URL=<部署环境URL> npx playwright test e2e/pdv/ --project=chromium +``` + +### PDV Spec 生成规则 + +AI 根据需求变更范围动态生成 Playwright spec，模板见 `templates/pdv-smoke-spec.md`。生成流程： + +1. 从需求关联任务提取前端变更范围（页面路由、菜单项、API 端点） +2. 登录测试账号（使用 storageState 或手动登录） +3. 验证新增菜单项可见（检查 `.ant-menu` 包含目标文本） +4. 导航到新页面，验证非白屏（title 不含 error/500/404） +5. 调用关键 API，验证返回状态码 < 500 +6. 每步截图保存为证据 + +### PDV 结果判定 + +- **全部 PASS** → 继续推进到 released +- **任一 FAIL** → 阻断推进，在部署文档记录失败项，通知修复 + +--- + ## TG2 集成测试检测 ### 模板映射 diff --git a/skills-dev/dev-test-plugin/skills/dev-test/e2e-testing.md b/skills-dev/dev-test-plugin/skills/dev-test/e2e-testing.md index 17f35bd..b9fc87a 100644 --- a/skills-dev/dev-test-plugin/skills/dev-test/e2e-testing.md +++ b/skills-dev/dev-test-plugin/skills/dev-test/e2e-testing.md @@ -1,14 +1,17 @@ # E2E 测试 (Playwright) -## 两种 E2E 测试模式 +## 三种 E2E 测试模式 | 模式 | 后端依赖 | 速度 | 适用场景 | 门禁阶段 | |------|---------|------|---------|---------| -| **API Mock 冒烟测试** | ❌ 无需后端 | 快（<30s） | UI 布局、路由、菜单、权限隔离 | E2E 冒烟门禁 | +| **API Mock 冒烟测试** | ❌ 无需后端 | 快（<30s） | UI 布局、路由、菜单、权限隔离 | TG4 E2E 冒烟门禁 | | **全链路集成测试** | ✅ 需完整后端+DB | 慢（分钟级） | CRUD 业务流程、数据持久化 | 手动/CI | +| **部署后验收 (PDV)** | ✅ 真实部署环境 | 中（<2min） | 功能入口可达、菜单可见、API 连通 | `/req deploy` 步骤 6 | **⚠️ 关键原则：E2E 冒烟门禁必须使用 API Mock 模式，不依赖后端。** 依赖后端的 E2E 在开发机上经常跑不通（后端没启动、DB 未初始化），导致门禁形同虚设。 +> **PDV 与 TG4 的区别**：TG4 在开发阶段用 API Mock 验证前端逻辑；PDV 在部署后用真实环境验证功能可达性。详见 `SKILL.md` §PDV 章节。 + > **与 req-test-gate 的关系**：本文档定义 E2E 测试的**执行技术**（怎么写 mock、怎么跑）。质量门禁流程（Gates 0-5、scope 分级、文档持久化）定义在 `req-test-gate` 技能中。 --- diff --git a/skills-dev/dev-test-plugin/skills/dev-test/templates/pdv-smoke-spec.md b/skills-dev/dev-test-plugin/skills/dev-test/templates/pdv-smoke-spec.md new file mode 100644 index 0000000..53b4542 --- /dev/null +++ b/skills-dev/dev-test-plugin/skills/dev-test/templates/pdv-smoke-spec.md @@ -0,0 +1,147 @@ +# PDV Smoke Spec 模板 + +部署后验收 (Post-Deploy Verification) Playwright 测试模板。AI 根据需求变更范围，基于此模板动态生成验收 spec。 + +## 使用方式 + +```bash +# 指定部署环境 URL 执行 +E2E_BASE_URL=https://staging.example.com npx playwright test e2e/pdv/ --project=chromium +``` + +## Spec 模板结构 + +```typescript +import { test, expect } from '@playwright/test'; + +const BASE_URL = process.env.E2E_BASE_URL || 'http://localhost:3000'; + +test.describe('PDV: {需求标题}', () => { + + test.beforeEach(async ({ page }) => { + // 方式 1: 使用 storageState（推荐，需预先保存登录状态） + // test.use({ storageState: 'e2e/.auth/user.json' }); + + // 方式 2: 手动登录 + await page.goto(`${BASE_URL}/login`); + await page.fill('input[name="username"]', '{测试账号}'); + await page.fill('input[name="password"]', '{测试密码}'); + await page.click('button[type="submit"]'); + await page.waitForURL('**/dashboard/**'); + }); + + test('菜单可见性: {菜单名}', async ({ page }) => { + await page.goto(`${BASE_URL}/`); + await page.waitForSelector('.ant-menu'); + + // 检查侧栏包含新菜单项 + const menu = page.locator('.ant-menu'); + await expect(menu).toContainText('{菜单名}'); + + // 截图证据 + await page.screenshot({ path: 'e2e-results/pdv-menu-{菜单名}.png', fullPage: false }); + }); + + test('页面可达: {页面路由}', async ({ page }) => { + const response = await page.goto(`${BASE_URL}{页面路由}`); + + // 验证 HTTP 状态 + expect(response?.status()).toBeLessThan(400); + + // 验证非白屏 — title 不含错误关键词 + await expect(page).not.toHaveTitle(/error|500|404|not found/i); + + // 验证页面有核心内容（非空白） + await expect(page.locator('{核心选择器}')).toBeVisible({ timeout: 10000 }); + + // 检查无 JS 报错（通过 console error 监听） + const errors: string[] = []; + page.on('console', msg => { + if (msg.type() === 'error') errors.push(msg.text()); + }); + await page.waitForTimeout(2000); + expect(errors.filter(e => !e.includes('favicon'))).toHaveLength(0); + + // 截图证据 + await page.screenshot({ path: 'e2e-results/pdv-page-{页面名}.png', fullPage: true }); + }); + + test('API 连通: {接口描述}', async ({ request }) => { + // 需要带认证 token 调用 + const resp = await request.get(`${BASE_URL}/api/v1/{路径}`, { + headers: { + 'Authorization': 'Bearer {token}', + }, + }); + + // 验证非 5xx 错误 + expect(resp.status()).toBeLessThan(500); + + // 可选：验证响应结构 + // const body = await resp.json(); + // expect(body).toHaveProperty('data'); + }); + +}); +``` + +## 占位符说明 + +| 占位符 | 含义 | 来源 | +|--------|------|------| +| `{需求标题}` | 需求名称 | `ai-proj req get --id ` | +| `{菜单名}` | 新增的菜单文本 | 从需求关联的前端任务中提取 | +| `{页面路由}` | 新增/变更的前端路由 | 从前端路由配置或 PRD 提取 | +| `{核心选择器}` | 页面核心内容的 CSS 选择器 | 如 `h1`, `.page-title`, `[data-testid="xxx"]` | +| `{测试账号}` / `{测试密码}` | 测试环境登录凭据 | 环境配置 | +| `{token}` | API 认证 token | 登录后获取 | +| `{接口描述}` / `{路径}` | 关键 API 端点 | 从后端路由或 PRD 提取 | +| `{页面名}` | 截图文件名标识 | 自定义 | + +## 生成示例（OKR 功能） + +```typescript +import { test, expect } from '@playwright/test'; + +const BASE_URL = process.env.E2E_BASE_URL || 'http://localhost:3000'; + +test.describe('PDV: OKR 团队/对齐/设置/评分功能', () => { + + test.beforeEach(async ({ page }) => { + await page.goto(`${BASE_URL}/login`); + await page.fill('input[name="username"]', 'testuser'); + await page.fill('input[name="password"]', 'TestPass123'); + await page.click('button[type="submit"]'); + await page.waitForURL('**/dashboard/**'); + }); + + test('菜单可见性: OKR', async ({ page }) => { + await page.goto(`${BASE_URL}/`); + await page.waitForSelector('.ant-menu'); + await expect(page.locator('.ant-menu')).toContainText('OKR'); + await page.screenshot({ path: 'e2e-results/pdv-menu-okr.png' }); + }); + + test('页面可达: /okr/my', async ({ page }) => { + const response = await page.goto(`${BASE_URL}/okr/my`); + expect(response?.status()).toBeLessThan(400); + await expect(page).not.toHaveTitle(/error|500|404/i); + await expect(page.locator('h1, .page-title')).toBeVisible({ timeout: 10000 }); + await page.screenshot({ path: 'e2e-results/pdv-page-okr-my.png', fullPage: true }); + }); + + test('页面可达: /okr/team', async ({ page }) => { + const response = await page.goto(`${BASE_URL}/okr/team`); + expect(response?.status()).toBeLessThan(400); + await expect(page).not.toHaveTitle(/error|500|404/i); + await expect(page.locator('h1, .page-title')).toBeVisible({ timeout: 10000 }); + await page.screenshot({ path: 'e2e-results/pdv-page-okr-team.png', fullPage: true }); + }); + + test('API 连通: OKR objectives', async ({ request }) => { + const resp = await request.get(`${BASE_URL}/api/v1/okr/objectives`); + expect(resp.status()).toBeLessThan(500); + }); + +}); +``` diff --git a/skills-req/req-plugin/skills/SKILL.md b/skills-req/req-plugin/skills/SKILL.md index 98a34c3..ce35816 100644 --- a/skills-req/req-plugin/skills/SKILL.md +++ b/skills-req/req-plugin/skills/SKILL.md @@ -108,9 +108,23 @@ Gate 4: 完整性检查 ── 三段式完整 + 验收标准 ≥ 2 条 + PRD |------|--------|------| | PRD | 01-PRD.md | `req-prd` | | 测试 | 02-测试报告.md | 自动生成 | -| 发布 | 03-发布记录.md | 自动生成 | +| 发布 | 03-发布记录.md | 自动生成（含 PDV 验收章节） | | 归档 | 04-生命周期总结.md | 自动生成 | +**03-发布记录.md 中 PDV 章节模板**： + +```markdown +### 部署后验收 (PDV) +| 检查项 | 结果 | 截图 | +|--------|------|------| +| 页面可达: /path/to/page | ✅ PASS | [截图] | +| 菜单可见: {菜单名} | ✅ PASS | [截图] | +| 基础渲染: 无白屏/JS 报错 | ✅ PASS | [截图] | +| API: /api/v1/{路径} | ✅ PASS | — | + +PDV 结论: ✅ 全部通过 / ❌ {N}项失败，阻断推进 +``` + ## 任务命名规范 | linkRole | 前缀 | 示例 | @@ -121,6 +135,7 @@ Gate 4: 完整性检查 ── 三段式完整 + 验收标准 ≥ 2 条 + PRD | code_review | 【代码评审】 | 【代码评审】CR: 代码审查 | | test | 【测试】 | 【测试】集成测试验证 | | deploy | 【部署】 | 【部署】部署到 staging | +| verification | 【验收】 | 【验收】PDV: OKR 功能部署验收 | | documentation | 【文档】 | 【文档】API 文档更新 | ## 阶段内容门禁（防空转） @@ -135,6 +150,24 @@ Gate 4: 完整性检查 ── 三段式完整 + 验收标准 ≥ 2 条 + PRD 未通过 → AskUserQuestion（补充文档 or 强制跳过+记录原因） +### 部署门禁（推进到 released 前） + +`/req deploy` 推进 `released` 前，必须通过 3 道门禁： + +``` +Deploy Gate 1: 健康检查 ── /health 返回 200，服务存活 +Deploy Gate 2: PDV 验收 ── linkRole=verification 的【验收】任务存在且 completed +Deploy Gate 3: 证据完整 ── 验收任务有文档，含检查项表格 + E2E 截图 + 通过/失败结论 +``` + +**PDV 验收任务生命周期**： +1. `/req deploy` 步骤 6 自动创建：`ai-proj task create --title "【验收】PDV: {需求标题}"` +2. 关联需求：`ai-proj req link --id --task-ids --link-role verification` +3. 执行 Playwright PDV 冒烟测试 +4. 附加验收文档（检查项表格 + 截图证据 + 结论）：`ai-proj task append-doc --id ` +5. **全部通过** → `ai-proj task complete --id ` → 门禁放行 +6. **任一失败** → 任务保持 in_progress，阻断推进，报告失败项 + ### CR 五视角扫描法 **核心原则**：实现阶段关注"怎么让它跑通"，评审阶段关注"怎么让它出错"。AI 必须**切换到对抗性思维**，逐一用以下 5 个视角扫描代码。 @@ -309,16 +342,26 @@ Gate 4: 完整性检查 ── 三段式完整 + 验收标准 ≥ 2 条 + PRD **`/req deploy [--project ] [--env production]`** — 项目级批量部署（Staging 已自动化，push develop 即触发）： 1. 收集待部署需求（delivery_stage=testing + 全 test 任务 completed） 2. AskUserQuestion 确认范围 -3. `ai-proj task create` 创建部署批次任务 +3. `ai-proj task create` 创建【部署】批次任务（linkRole=deploy） 4. 部署前检查（变更检测、数据库迁移） 5. 执行 `./scripts/build-and-push.sh prod --detect --deploy --wait --verify` -6. 部署后验证（截图 + 定向验证） -7. `ai-proj task append-doc` 记录部署文档 + 写入需求历史 -8. `ai-proj req advance --id --to released` 批量推进 +6. **Deploy Gate 1: 健康检查** — `/health` 返回 200 +7. **Deploy Gate 2+3: PDV 验收**（为每个需求创建独立验收任务）： + a. `ai-proj task create --title "【验收】PDV: {需求标题}"` 创建验收任务 + b. `ai-proj req link --id --task-ids --link-role verification` 关联需求 + c. 从需求关联任务中提取前端变更范围（页面路由、菜单项、关键 API） + d. 生成验收检查清单（页面可达 + 菜单可见 + 基础渲染 + API 连通） + e. 用 Playwright 对部署环境执行冒烟测试：`E2E_BASE_URL=<部署环境URL> npx playwright test e2e/pdv/ --project=chromium` + f. 收集截图证据 + g. `ai-proj task append-doc --id ` 附加验收文档（检查项表格 + 截图 + 结论） + h. **全部通过** → `ai-proj task complete --id ` → Gate 2+3 放行 + i. **任一失败** → 任务保持 in_progress，**阻断推进**，报告失败项 +8. `ai-proj task append-doc` 记录【部署】任务文档（构建日志 + 健康检查 + PDV 结果摘要） +9. `ai-proj req advance --id --to released` 批量推进（仅 Gate 1-3 全部通过的需求） **`/req done [REQ-ID]`** — 类型化归档门禁 + git commit + push + `ai-proj req archive --id `： - **推断类型**：有 implementation → code；无 implementation 有 prd/test → skill；仅 deploy → ops -- **code 检查**：delivery_stage=released + deploy 任务完成 + 部署文档 + 所有任务完成 +- **code 检查**：delivery_stage=released + deploy 任务完成 + verification 任务完成（PDV 通过） + 部署文档 + 所有任务完成 - **skill 检查**：delivery_stage≥testing + 所有任务完成 - **ops 检查**：deploy 任务完成 + 所有任务完成 @@ -347,6 +390,7 @@ ai-proj task append-doc --id 5214 --content "# PRD: 用户认证功能\n..." | review | 【约定】{约定名称}（bug 类需求，convention flow 自动创建） | documentation | | testing | 【测试】集成测试: {需求标题} | test | | deploy | 由 `/req deploy` 批量创建 | deploy | +| released | 【验收】PDV: {需求标题}（`/req deploy` 自动创建） | verification | ## 测试环境流程 @@ -365,7 +409,8 @@ ai-proj task append-doc --id 5214 --content "# PRD: 用户认证功能\n..." | implementation | 【开发】 | dev | 50% | | code_review | 【代码评审】 | review | 5% | | test | 【测试】 | testing | 15% | -| deploy | 【部署】 | staging/released | 10% | +| deploy | 【部署】 | staging/released | 5% | +| verification | 【验收】 | released | 5% | | documentation | 【文档】 | any | 5% | ## 标准任务结构 @@ -378,7 +423,9 @@ ai-proj task append-doc --id 5214 --content "# PRD: 用户认证功能\n..." ├── 🔍 review → 【代码评审】CR: {需求标题} (linkRole: code_review) ├── 🧪 testing → 【测试】集成测试: {需求标题} (linkRole: test) ├── 🚀 staging → 【部署】部署到 staging (linkRole: deploy) -└── 🏁 released → 【部署】部署到 prod (linkRole: deploy) +└── 🏁 released + ├── 【部署】部署到 prod (linkRole: deploy) + └── 【验收】PDV: {需求标题} (linkRole: verification) ``` ## ai-proj CLI 速查 @@ -402,7 +449,7 @@ ai-proj req tasks --id # 查看关联任务 **开发阶段**: `backlog`, `analysis`, `design`, `dev`, `review`, `integration`, `testing`, `staging`, `released` -**linkRole**: `prd`, `design`, `implementation`, `code_review`, `test`, `deploy`, `regression`, `documentation` +**linkRole**: `prd`, `design`, `implementation`, `code_review`, `test`, `deploy`, `verification`, `regression`, `documentation` ## 相关技能 diff --git a/skills-req/req-workflow-plugin/skills/SKILL.md b/skills-req/req-workflow-plugin/skills/SKILL.md index 17bdd38..72f1fad 100644 --- a/skills-req/req-workflow-plugin/skills/SKILL.md +++ b/skills-req/req-workflow-plugin/skills/SKILL.md @@ -25,7 +25,7 @@ description: 需求完整工作流。用于从创建到归档的完整流程、H 12. /req next → 推进到 staging 阶段 13. /req deploy staging → 部署 staging（创建【部署】任务, delivery_stage=staging） 14. /req next → 推进到 released 阶段 -15. /req deploy prod → 部署生产（创建【部署】任务, delivery_stage=released） +15. /req deploy prod → 部署生产 + PDV 验收（健康检查 → E2E 验收 → released） 16. /req done → 归档 (archived) ``` @@ -38,7 +38,7 @@ description: 需求完整工作流。用于从创建到归档的完整流程、H | PRD | 01-PRD.md | `req-prd` | | 开发 | 02-开发设计.md | `req-dev` | | 测试 | 03-测试报告.md | 自动生成 | -| 发布 | 04-发布记录.md | 自动生成 | +| 发布 | 04-发布记录.md | 自动生成（含 PDV 验收章节） | | 归档 | 05-生命周期总结.md | 自动生成 | > 注：Stitch 原型不单独编号，嵌入 01-PRD.md 的「4.2 界面原型」章节。 @@ -74,7 +74,7 @@ mcp__ai-proj__batch_sync_tasks_to_remote(taskIds) |------|------|----------| | 本机 | 开发调试 | `go test ./...` | | 预发布 | 集成测试 | API 验证 | -| 生产 | 最终验收 | API + 功能验证 | +| 生产 | 最终验收 | 健康检查 + PDV E2E 验收（页面可达、菜单可见、API 连通） | ## 任务关联规范 @@ -87,7 +87,8 @@ mcp__ai-proj__batch_sync_tasks_to_remote(taskIds) | implementation | 【开发】 | dev | 50% | | code_review | 【代码评审】 | review | 5% | | test | 【测试】 | testing | 15% | -| deploy | 【部署】 | staging/released | 10% | +| deploy | 【部署】 | staging/released | 5% | +| verification | 【验收】 | released | 5% | | documentation | 【文档】 | any | 5% | **进度计算**：按 link_role 权重统计已完成任务。 @@ -111,7 +112,7 @@ mcp__ai-proj__batch_sync_tasks_to_remote(taskIds) │ └── 【部署】部署到 staging (singapore) (linkRole: deploy) └── 🏁 released 阶段 ├── 【部署】部署到 prod (tools_ai_proj) (linkRole: deploy) - └── 【验收】功能验收确认 (linkRole: documentation) + └── 【验收】PDV: {需求标题} (linkRole: verification) ``` **命名规则**：所有任务标题必须以阶段前缀开头（如【评审】、【开发】、【部署】）。