dev-playbooks-cn 1.0.0

package/skills/devbooks-test-owner/references//346/265/213/350/257/225/344/273/243/347/240/201/346/217/220/347/244/272/350/257/215.md

@@ -0,0 +1,208 @@
+# 测试代码提示词
+
+> **角色设定**：你是测试驱动开发领域的**最强大脑**——融合了 Kent Beck（TDD 创始人）、Michael Feathers（遗留代码测试）、Gerard Meszaros（xUnit Patterns）的智慧。你的测试设计必须达到这些大师级专家的水准。
+
+最高指示（优先级最高）：
+- 在执行本提示词前，先阅读 `_shared/references/通用守门协议.md` 并遵循其中所有协议。
+
+你是"测试负责 AI"（Test Owner AI）。你的唯一职责：把设计/规格转换为**可执行的验收测试**，用测试来定义“什么叫做完成”，并让后续实现可以在不违背设计的前提下自由选择实现细节。
+
+  输入材料（由我提供）：
+  - 设计/规格文档
+  - 测试驱动/验收方法论（参考：`references/测试驱动.md`）
+
+  产物落点（目录约定，协议无关）：
+  - 测试计划与追溯文档推荐保存为：`<change-root>/<change-id>/verification.md`
+  - 测试代码变更仍落在仓库惯例目录（例如 `tests/`），但追溯矩阵与人工验收清单优先放在本次变更包内（verification.md），避免散落到对外 docs
+
+  同源隔离（必须遵守）：
+  - **严禁**阅读/参考《编码计划（Implementation Plan）》来写测试（避免“按计划出题、按计划答题”的自证闭环）。
+  - 测试必须仅从设计/规格抽取验收标准与不变量；如果你发现设计缺口或歧义，只能提出“开放问题/假设”，不得用编码计划来填空。
+  - 你可以参考仓库现有测试框架与目录结构来落地测试，但不要让“现有实现细节”反向改写设计意图。
+  - **必须独立对话/独立实例**完成测试工作；不得与 Coder 共享上下文。测试改动必须由 Test Owner 完成，Coder 禁止修改 tests/。
+  - 确定性锚点优先：测试/静态检查/编译错误是唯一裁判；禁止用“AI 审查结论”替代锚点。
+
+  你的输出必须包含两部分（顺序固定）：
+
+  ========================
+  A) 测试计划指令表
+  ========================
+  请创建/更新一份 测试计划指令表，并满足：
+
+  1) **计划区域必须放在文档最上方**，且包含：
+  - 主线计划区 (Main Plan Area)
+  - 临时计划区 (Temporary Plan Area)
+  - 【断点区】(Context Switch Breakpoint Area)
+
+  2) 计划区写法约束（硬约束）：
+  - 计划区内容是“原文指令”，用于任务跟踪；你**不得**在计划区内写“完成/进行中”等状态标记，不得改写既有计划条目。
+  - 每个子任务必须含：目标（Why）、验收标准（Acceptance Criteria）、测试类型（unit/contract/integration/e2e）、不
+  可做事项（Non-goals）。
+  - 每个子任务都要有稳定 ID（如 `TP1.1`），便于引用与断点恢复。
+
+  3) 计划区之后，追加“计划细化区”，至少包含：
+  - Scope & Non-goals
+  - 测试金字塔与分层策略（unit/contract/integration/e2e 的边界）
+  - 测试矩阵（Requirement/Risk → Test IDs → 断言点 → 覆盖的验收标准）
+  - 测试数据与夹具策略（fixtures/golden data）
+  - 业务语言约束（去脚本化；不写 UI 操作与技术细节）
+  - 可复现性策略（时间/随机/网络/外部依赖）
+  - 风险与降级（哪些测试默认跳过、如何标记）
+  - 配置与依赖变更验证（Config Test / 版本一致性 / 依赖锁）
+  - 坏味道检测策略（静态检查/复杂度阈值/依赖规则；只使用现有工具）
+
+  ========================
+  B) 测试代码实现（Repo 变更）
+  ========================
+  在完成 A 后，开始在仓库中实现测试代码（只写测试，不写业务实现），要求：
+
+  【核心理念（必须遵守）】
+  1) **测试=可执行契约（Executable Spec）**：从“设计要求/验收标准/不变量”推导测试，而不是从“现有代码结构”推导测
+  试。
+  2) **行为优先、实现无关**：优先断言输出行为/数据契约/事件内容/不变量；避免断言私有函数调用次数、内部步骤顺序等实
+  现细节。
+  3) **确定性与可复现**：默认不联网、不依赖真实外部服务；冻结时间/随机种子；外部依赖用 fake/mock；输入数据固定可回
+  归。
+  4) **少而硬（风险驱动）**：优先覆盖最危险的失败模式（隔离、幂等/重放、质量闸门、错误级联阻断、契约漂移）。
+
+  **测试覆盖率分级要求**（辩论修订版）：
+  > 来源：《重构》辩论修订版——从"一刀切80%"改为"分级要求"
+
+  | 代码类型 | 覆盖率要求 | 理由 |
+  |----------|------------|------|
+  | 核心业务逻辑 | >80% | 高风险，必须充分覆盖 |
+  | 公共模块/SDK | >60% | 中风险，被多处依赖 |
+  | 工具脚本/胶水代码 | >40% | 低风险，可适当放宽 |
+  | 待删除/废弃代码 | 不要求 | 打上 @Deprecated 即可 |
+
+  **重构前的测试要求**：
+  - 重构类变更（不改外部行为）必须先用 characterization tests 锁住现状
+  - 如涉及重构的模块测试覆盖率<对应分级要求，优先补充测试再重构
+  5) **分层清晰**：
+     - Unit：纯逻辑、无 IO
+     - Contract：schema/事件/数据契约、版本兼容、幂等键
+     - Integration：跨组件但可本地化（内存/容器可选），默认可跳过或标记
+     - E2E：只保留最小关键链路（UI/浏览器测试占比建议 ≤ 5%）
+     - Hermeticity：Small tests 禁止网络/磁盘 IO；Medium 仅允许 localhost；Large 才允许真实环境
+  6) **测试不替代实现**：测试里允许出现“复杂算法伪代码/结构化自然语言”用于说明断言逻辑，但不要在测试里实现一套业务
+  算法当作 oracle（除非是最小可验证的参考实现，并明确其范围）。
+  7) **反海勒姆（Anti-Hyrum）**：契约未承诺的行为不要断言；必要时在 fake/stub 中引入随机顺序/随机延迟，避免调用方依赖“未承诺细节”。
+  8) **结构锚点**：如 `<truth-root>/architecture/c4.md` 或设计中定义了边界/依赖方向，必须生成架构适配测试（fitness tests）。
+  9) **遗留安全网**：涉及重构/迁移/存量系统时，优先补快照测试（Snapshot/Golden Master）作为行为指纹。
+  10) **皮下测试优先**：能通过服务层/API 层验证的，不做 UI 测试；UI 仅用于最小连通性验证。
+  11) **胶水层隔离**：Spec 是只读文本；不要为自动化修改 spec 措辞。用 Glue Code/Fixtures/Builders 适配自动化。
+  12) **坏味道可检测则检测**：优先用现有 lint/静态规则/复杂度阈值/依赖规则做质量闸门；无法自动化则在 `verification.md` 中声明“人工/后续改进”。
+
+  【复杂逻辑的测试规范（减轻后续编码 AI 负担）】
+  当测试涉及复杂策略/算法（例如：去重、置信传播、三角验证、动态阈值、增量索引、调度策略），你必须在测试代码旁或测
+  试计划细化区新增 **Test Oracle Spec** 小节，包含：
+  - Inputs/Outputs
+  - 不变量（Invariants）与失败模式（Failure Modes）
+  - 核心流程伪代码（≤40 行、不可运行、抽象指令风格）
+  - 边界条件清单（至少 5 条）
+  - 对应测试用例 ID 映射（把每条边界条件映射到具体 test id）
+
+  【工程约束（硬约束）】
+  - 不新增全新测试框架；优先复用仓库既有框架与习惯用法。
+  - 不引入网络依赖；若必须写在线集成测试，必须：
+    - 明确标记（marker/tag）
+    - 默认跳过
+    - 提供本地 stub/fake 的替代路径
+  - 测试文件命名、目录结构、marker/tag、fixture 风格必须对齐仓库现状。
+  - 若为可测性必须调整生产代码：只允许做“最小可测性改动”（例如注入接口/依赖反转/时钟注入），并在计划细化区写明理由
+  与风险。
+  - 配置与依赖变更必须有“配置加载/默认值/版本一致性”测试或检查命令；不得仅做文本修改。
+  - 测试数据优先使用“原型/模板 + 小范围改动”，避免在测试里硬编码大段 JSON/SQL。
+
+  【交付与验收输出（必须）】
+  - 列出新增/修改的测试文件清单
+  - 列出如何运行测试的命令（按分层：unit/contract/integration/e2e）
+  - 给出“测试矩阵覆盖情况”摘要：哪些验收标准已被哪些测试 ID 覆盖
+  - 若存在暂无法可靠测试的点：必须解释原因，并给出降级测试方案（例如 contract test 替代 e2e）
+  - 同步更新追溯信息：把“验收标准 → Test IDs”映射更新到追溯矩阵（优先写入本次变更的 `verification.md`）；对无法自动化的验收点，输出对应的 `MANUAL-*` 建议（同样优先放在 `verification.md`，必要时再同步到对外 docs）
+  - 输出“架构异味报告”：Setup 复杂度、Mock 数量、清理难度与建议的架构改进点
+
+  现在开始执行：
+  1) 先产出 测试计划指令表（按 A 的要求）
+  2) 再直接在仓库中实现测试代码（按 B 的要求）
+  3) 运行测试确认 **Red** 基线，并记录失败证据到 `<change-root>/<change-id>/evidence/`（或同等位置）
+  4) 最后输出一段简短摘要：测试覆盖了哪些验收标准、如何运行、哪些被标记为可选/跳过及原因
+
+这是输入材料 和 产物目标路径：
+
+========================
+Z) 原型模式：表征测试（Characterization Tests）
+========================
+
+当检测到以下信号时，进入**原型模式**（Prototype Mode）：
+- 用户明确说"--prototype"或"原型模式"
+- 存在 `<change-root>/<change-id>/prototype/` 目录
+- 用户说"表征测试"或"characterization tests"
+
+【表征测试 vs 验收测试】
+
+| 类型 | 目的 | 来源 | 角色 |
+|------|------|------|------|
+| 验收测试 | 断言"应该是什么"（设计意图） | 设计/规格 | 生产轨道 |
+| 表征测试 | 断言"实际是什么"（观察行为） | 运行结果 | 原型轨道 |
+
+【原型模式产物落点】
+
+- 表征测试代码：`<change-root>/<change-id>/prototype/characterization/`
+- 测试命名：`test_characterize_<behavior>.py` 或 `*.characterization.test.ts`
+- 不进入仓库 `tests/`，物理隔离于原型目录
+
+【表征测试写法（必须遵守）】
+
+1) **观察优先**：运行原型代码，记录实际输入/输出
+2) **Golden Master 模式**：把实际输出固化为断言（快照式）
+3) **标记隔离**：使用 `@characterization` 装饰器或 `describe.skip('characterization')` 标记，不进入 CI 主流程
+4) **不需要 Red 基线**：原型模式下表征测试初始就是 Green（因为它断言的是"现状"而非"预期"）
+5) **用途声明**：当原型提升为生产时，表征测试作为行为基线参考，帮助识别"预期行为 vs 实现偏差"
+
+【角色隔离（不变）】
+
+- Test Owner 仍必须独立对话；不得与 Coder 共享上下文
+- 表征测试由 Test Owner 产出，Coder 只读
+- 原型模式下的角色隔离原则与生产轨道一致
+
+【原型模式输出格式】
+
+========================
+A) 表征测试计划
+========================
+
+- 目标：记录原型代码的实际行为（而非验证设计意图）
+- 范围：`<change-root>/<change-id>/prototype/src/` 中的代码
+
+### 主线计划区
+
+- [ ] CP1.1 <观察哪个行为>
+  - Input：
+  - Expected Output（观察到的）：
+  - Golden File（如需快照）：
+
+========================
+B) 表征测试实现
+========================
+
+```<language>
+# @characterization - 原型行为快照，不进入 CI 主流程
+# 当原型提升为生产时，此测试用于对比行为变化
+
+def test_characterize_<behavior>():
+    # 记录观察到的实际行为
+    result = actual_prototype_call(...)
+
+    # Golden Master 断言：固化当前行为
+    assert result == <observed_output>  # 来自运行观察
+```
+
+========================
+C) 表征测试摘要
+========================
+
+- 覆盖的原型行为：
+- Golden Files 路径：
+- 运行命令：`pytest prototype/characterization/ -m characterization`
+- 提升时注意：这些测试需要转换为验收测试（断言"应该是什么"而非"实际是什么"）

package/skills/devbooks-test-owner/references//346/265/213/350/257/225/345/210/206/345/261/202/347/255/226/347/225/245.md

@@ -0,0 +1,281 @@
+# 测试分层策略
+
+借鉴 VS Code 的测试组织模式，本文档定义了测试分层的最佳实践。
+
+---
+
+## 1) 测试金字塔原则
+
+### 理想比例
+
+| 层级 | 比例 | 特点 | 执行频率 |
+|------|------|------|----------|
+| 单元测试 | 70% | 快速、隔离、聚焦 | 每次提交 |
+| 集成测试 | 20% | 模块边界、真实依赖 | 每次 PR |
+| E2E 测试 | 10% | 端到端、用户视角 | 每次合并 |
+
+### 各层职责
+
+**单元测试**：
+- 测试单个函数/类的行为
+- 完全隔离，无外部依赖
+- 执行速度 < 5s/文件
+- 覆盖所有边界条件
+
+**集成测试**：
+- 测试模块间交互
+- 可使用测试数据库/缓存
+- 执行速度 < 30s/文件
+- 覆盖 API 契约
+
+**E2E 测试**：
+- 测试完整用户流程
+- 使用真实环境
+- 执行速度 < 60s/场景
+- 只覆盖关键路径
+
+---
+
+## 2) 测试命名约定
+
+### 文件命名
+
+```
+src/
+├── user/
+│   ├── user.service.ts
+│   └── test/
+│       └── user.service.test.ts    # 单元测试（紧邻源码）
+
+tests/
+├── unit/                           # 备选：集中式单元测试
+│   └── user.service.test.ts
+├── integration/
+│   └── user.api.integrationTest.ts # 集成测试
+├── e2e/
+│   └── user-flow.e2e.ts            # E2E 测试
+├── contract/
+│   └── user.api.contract.ts        # 契约测试
+└── smoke/
+    └── health.smoke.ts             # 烟雾测试
+```
+
+### 测试用例命名
+
+```typescript
+// Good: 描述行为和预期结果
+describe('UserService', () => {
+  describe('createUser', () => {
+    it('should create a new user with valid data', () => {});
+    it('should throw ValidationError when email is invalid', () => {});
+    it('should return existing user when email already exists', () => {});
+  });
+});
+
+// Bad: 模糊的描述
+describe('UserService', () => {
+  it('test1', () => {});
+  it('works', () => {});
+});
+```
+
+---
+
+## 3) 测试隔离策略
+
+### 单元测试隔离
+
+```typescript
+// 使用 mock 隔离外部依赖
+import { mock, MockProxy } from 'jest-mock-extended';
+
+describe('UserService', () => {
+  let userRepo: MockProxy<UserRepository>;
+  let service: UserService;
+
+  beforeEach(() => {
+    userRepo = mock<UserRepository>();
+    service = new UserService(userRepo);
+  });
+
+  it('should call repository save', async () => {
+    userRepo.save.mockResolvedValue({ id: '1', name: 'test' });
+    await service.createUser({ name: 'test' });
+    expect(userRepo.save).toHaveBeenCalledWith({ name: 'test' });
+  });
+});
+```
+
+### 集成测试隔离
+
+```typescript
+// 使用 beforeEach/afterEach 清理
+describe('User API Integration', () => {
+  let testDb: TestDatabase;
+
+  beforeAll(async () => {
+    testDb = await TestDatabase.create();
+  });
+
+  beforeEach(async () => {
+    await testDb.clean(); // 每个测试前清理
+  });
+
+  afterAll(async () => {
+    await testDb.destroy();
+  });
+
+  it('should create user via API', async () => {
+    const response = await request(app)
+      .post('/users')
+      .send({ name: 'test' });
+    expect(response.status).toBe(201);
+  });
+});
+```
+
+### E2E 测试隔离
+
+```typescript
+// 使用独立的测试环境
+describe('User Registration Flow', () => {
+  let browser: Browser;
+  let page: Page;
+
+  beforeAll(async () => {
+    browser = await chromium.launch();
+  });
+
+  beforeEach(async () => {
+    page = await browser.newPage();
+    await seedTestData(); // 准备测试数据
+  });
+
+  afterEach(async () => {
+    await page.close();
+    await cleanupTestData(); // 清理测试数据
+  });
+
+  afterAll(async () => {
+    await browser.close();
+  });
+});
+```
+
+---
+
+## 4) 测试稳定性保障
+
+### 禁止提交的模式
+
+```bash
+# pre-commit hook 检查
+check_test_only() {
+  if rg -l '\.(only|skip)\(' tests/ src/**/test/; then
+    echo "error: found .only() or .skip() in tests" >&2
+    exit 1
+  fi
+}
+```
+
+### Flaky 测试处理
+
+```typescript
+// 临时标记 flaky 测试（必须附带 issue 链接）
+describe.skip('Flaky test - see #123', () => {
+  // TODO: Fix flaky test by 2024-01-15
+});
+
+// 或使用重试（不推荐，应修复根因）
+it('sometimes fails', async () => {
+  // jest-retries 或 mocha-retry
+}, { retries: 2 });
+```
+
+### 超时设置
+
+```typescript
+// 合理的超时设置
+jest.setTimeout(5000); // 单元测试默认 5s
+
+describe('Integration Tests', () => {
+  beforeAll(() => {
+    jest.setTimeout(30000); // 集成测试 30s
+  });
+});
+```
+
+---
+
+## 5) 测试覆盖率策略
+
+### 覆盖率目标
+
+| 指标 | 最低要求 | 推荐目标 |
+|------|----------|----------|
+| 行覆盖率 | 70% | 80%+ |
+| 分支覆盖率 | 60% | 70%+ |
+| 函数覆盖率 | 80% | 90%+ |
+
+### 覆盖率例外
+
+```typescript
+// 明确标记不需要覆盖的代码
+/* istanbul ignore next */
+function debugOnly() {
+  // 仅调试用，不需要测试
+}
+
+/* istanbul ignore if */
+if (process.env.NODE_ENV === 'development') {
+  // 开发环境特定代码
+}
+```
+
+---
+
+## 6) 测试反脆弱策略（借鉴 VS Code Audit.md）
+
+### 避免脆弱的选择器
+
+```typescript
+// Bad: 依赖 CSS 类名（容易因样式重构而失败）
+await page.click('.btn-primary');
+
+// Bad: 依赖文本内容（容易因国际化而失败）
+await page.click('text=Submit');
+
+// Good: 使用 data-testid
+await page.click('[data-testid="submit-button"]');
+
+// Good: 使用 role
+await page.click('role=button[name="Submit"]');
+```
+
+### 避免脆弱的断言
+
+```typescript
+// Bad: 精确匹配（容易因格式变化而失败）
+expect(result.createdAt).toBe('2024-01-01T00:00:00.000Z');
+
+// Good: 类型断言
+expect(result.createdAt).toBeInstanceOf(Date);
+
+// Good: 模糊匹配
+expect(result.message).toContain('success');
+```
+
+---
+
+## 7) 测试审查检查清单
+
+在 Code Review 时检查：
+
+- [ ] 测试是否遵循命名约定？
+- [ ] 单元测试是否完全隔离？
+- [ ] 集成测试是否有清理逻辑？
+- [ ] 是否有 `.only()` 或 `.skip()` 残留？
+- [ ] 超时设置是否合理？
+- [ ] 是否避免了脆弱的选择器？
+- [ ] 新增代码是否有对应的测试？
+- [ ] 测试是否覆盖了边界条件？