@umacloud/knowledge 1.0.1

package/testing/02-playbooks/testing-strategy-playbook.md

@@ -0,0 +1,126 @@
+---
+id: testing-strategy-playbook
+title: 测试策略实战手册（金字塔模型 + 现代实践）
+domain: testing
+category: 02-playbooks
+difficulty: advanced
+tags: [testing, unit, integration, e2e, test-pyramid, coverage, mocking, tdd, bdd, playwright, jest, enterprise]
+quality_score: 93
+maintainer: qa-team@umadev.com
+last_updated: 2026-06-15
+---
+
+# 测试策略实战手册
+
+> 基于 [TestRail Testing Pyramid](https://www.testrail.com/blog/testing-pyramid/) + [CircleCI Strategy](https://circleci.com/blog/testing-pyramid/) + [Bunnyshell E2E 2025](https://www.bunnyshell.com/blog/best-practices-for-end-to-end-testing-in-2025/)
+
+## 测试金字塔
+
+```
+          /\
+         /E2E\          少量（关键路径，< 5%）
+        /------\
+       /Integra-\        适量（服务边界，~25%）
+      /  tion   \
+     /------------\
+    /    Unit      \      大量（业务逻辑，~70%）
+   /----------------\
+```
+
+### Unit Tests（单元测试）
+- 测什么：纯函数、业务逻辑、数据转换
+- 工具：Jest/Vitest（JS）, pytest（Python）, `#[test]`（Rust）
+- 速度：< 100ms/测试
+- Mock：外部依赖（DB/API）全部 mock
+```typescript
+// ✅ 纯函数测试（快、确定、无副作用）
+describe('calculateTotal', () => {
+  it('sums line items with tax', () => {
+    const items = [{ price: 100, qty: 2 }, { price: 50, qty: 1 }];
+    expect(calculateTotal(items, 0.1)).toBe(275);
+  });
+});
+```
+
+### Integration Tests（集成测试）
+- 测什么：模块间交互、API 端点、DB 查询
+- 工具：Supertest（API）, Testcontainers（DB）
+- 速度：< 2s/测试
+- 用真实 DB（测试容器）而非 mock
+```typescript
+// ✅ API 端点集成测试（真实 DB container）
+describe('POST /api/orders', () => {
+  it('creates an order and returns 201', async () => {
+    const res = await request(app)
+      .post('/api/orders')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ productId: 'p1', quantity: 2 });
+    expect(res.status).toBe(201);
+    expect(res.body.id).toBeDefined();
+    // 验证 DB 确实写入了
+    const order = await db.query(Order).findById(res.body.id);
+    expect(order).toBeTruthy();
+  });
+});
+```
+
+### E2E Tests（端到端测试）
+- 测什么：完整用户流程（注册→下单→支付）
+- 工具：Playwright/Cypress
+- 速度：< 30s/测试
+- 少而精——只测关键业务路径
+```typescript
+// ✅ Playwright E2E（真实浏览器）
+test('user can place an order', async ({ page }) => {
+  await page.goto('/login');
+  await page.fill('[name=email]', 'test@example.com');
+  await page.fill('[name=password]', 'password');
+  await page.click('button[type=submit]');
+  await page.click('text=Products');
+  await page.click('text=Add to Cart');
+  await page.click('text=Checkout');
+  await expect(page.locator('text=Order confirmed')).toBeVisible();
+});
+```
+
+## 测试原则
+
+1. **Arrange-Act-Assert** — 每个测试三段式
+2. **一个测试一个断言重点** — 失败时立刻知道哪里错
+3. **测试独立** — 不依赖其他测试的执行顺序
+4. **确定性** — 同样输入永远同样结果（不依赖时间/随机/网络）
+5. **Fast feedback** — Unit 全量 < 10s，CI 全量 < 5min
+
+## Mock 策略
+
+```typescript
+// ✅ Mock 边界（外部依赖），不 mock 内部逻辑
+// Mock 的：数据库、HTTP API、文件系统、时间
+// 不 Mock 的：被测函数本身、纯业务逻辑
+
+// ❌ 过度 mock（测了 mock 不是代码）
+it('creates order', async () => {
+  db.insert = jest.fn().mockReturnValue({ id: 1 });  // mock 了 DB
+  const result = await createOrder({ productId: 'p1' });
+  expect(result.id).toBe(1);  // 这只测了 mock 返回什么...
+});
+
+// ✅ 合理 mock（只 mock 外部边界）
+it('creates order with valid data', async () => {
+  // 用 testcontainer 真实 DB
+  const result = await createOrder({ productId: 'p1', quantity: 2 });
+  expect(result.id).toBeDefined();
+  expect(result.status).toBe('pending');
+});
+```
+
+## 覆盖率目标
+
+| 层级 | 目标 | 说明 |
+|------|------|------|
+| 行覆盖率 | ≥ 80% | 每行代码至少被测一次 |
+| 分支覆盖率 | ≥ 70% | 每个 if/else 分支 |
+| 关键路径 | 100% | 支付/认证/权限 |
+| 工具类 | ≥ 90% | 纯函数工具 |
+
+**覆盖率不是目的**——80% 覆盖率但测试都是无意义的 `expect(true)` 毫无价值。测**关键行为**比追求数字重要。

package/testing/03-checklists/test-strategy-checklist.md

@@ -0,0 +1,208 @@
+---
+id: test-strategy-checklist
+title: 测试策略检查清单
+domain: testing
+category: 03-checklists
+difficulty: intermediate
+tags: [agent, checklist, management, strategy, test, testing, 概述, 测试策略评估矩阵]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 测试策略检查清单
+
+## 概述
+
+本清单为项目测试策略的完整审查框架，涵盖单元测试、集成测试、端到端测试、性能测试、安全测试和覆盖率管理六大维度。适用于团队建立或评估测试体系时逐项确认，确保测试投入与质量产出的最优平衡。
+
+测试金字塔原则：单元测试（70%）> 集成测试（20%）> E2E 测试（10%）。
+
+---
+
+## 1. 单元测试（Unit Testing）
+
+### 基础设施
+
+- [ ] 测试框架已选定并统一（Jest / pytest / Go testing / JUnit）
+- [ ] 测试运行器集成到 CI pipeline，每次提交自动触发
+- [ ] Mock/Stub 工具已集成（jest.mock / unittest.mock / gomock）
+- [ ] 测试数据工厂已建立（Factory Boy / Faker / Fishery）
+- [ ] 测试执行时间 < 5 分钟（超过需拆分或并行化）
+
+### 质量标准
+
+- [ ] 每个公共函数/方法至少 1 个正向测试 + 1 个异常测试
+- [ ] 纯函数测试覆盖所有边界条件（空值、零值、极大值、特殊字符）
+- [ ] 测试命名清晰：`test_<被测行为>_when_<条件>_should_<期望结果>`
+- [ ] 测试之间无顺序依赖，可独立运行
+- [ ] 不测试私有方法（通过公共接口间接覆盖）
+- [ ] 不测试框架本身的功能（如 ORM 的 CRUD）
+- [ ] 每个测试只验证一个行为（Single Assertion Principle）
+- [ ] 测试代码同样遵循代码规范（无重复、有清晰结构）
+
+### 反模式检查
+
+- [ ] 无 sleep/delay 等时间依赖（使用 fake timer）
+- [ ] 无真实网络调用（全部 mock）
+- [ ] 无真实数据库操作（使用内存数据库或 mock）
+- [ ] 无硬编码的文件路径（使用临时目录）
+- [ ] 无测试间共享的可变状态
+
+## 2. 集成测试（Integration Testing）
+
+### 基础设施
+
+- [ ] 测试数据库使用独立实例（Docker Compose / Testcontainers）
+- [ ] 测试环境配置与生产环境一致（同类型数据库、同版本中间件）
+- [ ] 每个测试套件前后有清理机制（事务回滚 / truncate）
+- [ ] 外部服务使用 Contract Testing 或 WireMock 模拟
+
+### 质量标准
+
+- [ ] API 端点测试覆盖：正常请求 + 认证失败 + 参数错误 + 权限不足
+- [ ] 数据库操作测试覆盖：CRUD + 事务 + 并发 + 约束违反
+- [ ] 消息队列测试覆盖：发送 + 消费 + 重试 + 死信
+- [ ] 缓存测试覆盖：命中 + 未命中 + 过期 + 失效
+- [ ] 服务间调用测试覆盖：正常 + 超时 + 降级 + 重试
+- [ ] 数据一致性验证：写入后立即读取确认数据正确
+- [ ] 测试数据不依赖生产数据（使用 seed 数据或 factory）
+
+### 反模式检查
+
+- [ ] 无测试调用真实第三方服务（支付、短信、邮件等）
+- [ ] 无测试修改共享状态导致其他测试失败
+- [ ] 无测试因环境差异（时区、编码、OS）而不稳定
+
+## 3. 端到端测试（E2E Testing）
+
+### 基础设施
+
+- [ ] E2E 测试框架已选定（Playwright / Cypress / Selenium）
+- [ ] 测试环境独立部署，不与开发/staging 共用
+- [ ] 测试数据有独立的 seed 脚本，可重复执行
+- [ ] 截图/录屏功能已启用，失败时自动保存证据
+- [ ] 并行执行能力已配置，减少总运行时间
+
+### 质量标准
+
+- [ ] 覆盖核心业务流程（关键路径 / Happy Path）
+- [ ] 用户注册 → 登录 → 核心操作 → 退出的完整流程
+- [ ] 支付/订单等关键转化路径 100% 覆盖
+- [ ] 跨浏览器测试：Chrome + Firefox + Safari（至少 2 种）
+- [ ] 移动端视口测试（375px / 768px / 1024px）
+- [ ] 测试步骤使用 Page Object Model 封装，减少维护成本
+- [ ] 等待策略使用显式等待（wait for element），不使用 sleep
+
+### 反模式检查
+
+- [ ] E2E 测试数量不超过总测试的 10%（避免过度依赖 E2E）
+- [ ] 不将 E2E 测试用于验证业务逻辑细节（那是单元测试的职责）
+- [ ] 不因 E2E 测试不稳定而频繁跳过（修复而非忽略）
+- [ ] 不在 E2E 测试中直接操作数据库（通过 API 准备数据）
+
+## 4. 性能测试（Performance Testing）
+
+### 基础设施
+
+- [ ] 性能测试工具已选定（k6 / JMeter / Gatling / Locust）
+- [ ] 测试环境硬件配置与生产环境等比（至少 1:2）
+- [ ] 性能基线已建立（当前 QPS、P95 延迟、错误率）
+- [ ] 测试数据量模拟生产规模（至少 80% 数据量）
+
+### 质量标准
+
+- [ ] 负载测试：验证系统在预期并发下的表现（如 500 QPS）
+- [ ] 压力测试：找到系统的瓶颈点（逐步加压直到错误率 > 1%）
+- [ ] 浸泡测试：长时间（≥ 4 小时）稳定负载，检测内存泄漏
+- [ ] 峰值测试：模拟突发流量（如秒杀场景，瞬时 10x 正常流量）
+- [ ] 关键 API 的 P95 响应时间 < SLA 要求
+- [ ] 数据库慢查询 < 全部查询的 0.1%
+- [ ] 内存使用在长时间运行后无持续增长趋势
+- [ ] 连接池、线程池使用率在高负载时 < 80%
+
+### 反模式检查
+
+- [ ] 不在开发环境跑性能测试然后推断生产表现
+- [ ] 不忽略测试中的错误率（即使 QPS 达标）
+- [ ] 不仅测试单接口（需测试混合场景模拟真实流量模型）
+
+## 5. 安全测试（Security Testing）
+
+### 基础设施
+
+- [ ] SAST（静态扫描）工具集成到 CI（SonarQube / Semgrep / CodeQL）
+- [ ] DAST（动态扫描）工具定期运行（OWASP ZAP / Burp Suite）
+- [ ] 依赖漏洞扫描自动化（npm audit / pip-audit / Trivy）
+- [ ] Secret 扫描集成到 pre-commit hook（git-secrets / trufflehog）
+
+### 质量标准
+
+- [ ] OWASP Top 10 全部覆盖测试
+- [ ] SQL 注入测试：所有用户输入参数
+- [ ] XSS 测试：所有输出到页面的用户数据
+- [ ] CSRF 测试：所有状态变更操作
+- [ ] 认证绕过测试：修改 Token / 过期 Token / 无 Token
+- [ ] 越权测试：用户 A 访问用户 B 的数据
+- [ ] 文件上传测试：恶意文件类型、超大文件、路径穿越
+- [ ] 敏感数据暴露测试：API 响应不包含密码哈希、内部 ID 等
+- [ ] HTTPS 强制：HTTP 请求 301 到 HTTPS
+- [ ] 安全响应头：HSTS、X-Content-Type-Options、X-Frame-Options
+
+### 反模式检查
+
+- [ ] 不将安全测试仅放在上线前执行（应持续集成）
+- [ ] 不忽略中低危漏洞（定期清理漏洞列表）
+- [ ] 不使用过时的加密算法（MD5、SHA1 用于密码哈希）
+
+## 6. 覆盖率管理（Coverage Management）
+
+### 目标设定
+
+- [ ] 项目整体行覆盖率目标 ≥ 80%
+- [ ] 核心业务模块行覆盖率目标 ≥ 90%
+- [ ] 分支覆盖率目标 ≥ 70%
+- [ ] 新增代码覆盖率 ≥ 85%（增量覆盖率）
+- [ ] CI 中覆盖率低于阈值阻止合并
+
+### 执行标准
+
+- [ ] 覆盖率报告自动生成并发布（Codecov / Coveralls）
+- [ ] 覆盖率趋势可视化，可追溯历史变化
+- [ ] 排除生成代码、配置文件、类型定义文件的覆盖率计算
+- [ ] 定期审查低覆盖率模块，制定补充计划
+- [ ] 不为提升覆盖率而写无意义的测试（如仅调用不断言）
+
+### 反模式检查
+
+- [ ] 覆盖率 100% 不等于零 bug（关注测试质量而非数字）
+- [ ] 不使用 `istanbul ignore` / `pragma: no cover` 绕过覆盖率
+- [ ] 不因为是 "简单代码" 就跳过测试
+
+---
+
+## 测试策略评估矩阵
+
+| 维度 | 权重 | 达标标准 | 当前状态 |
+|------|------|---------|---------|
+| 单元测试 | 30% | 覆盖率 ≥ 80%，CI 集成 | [ ] |
+| 集成测试 | 25% | API 100% 覆盖，数据层验证 | [ ] |
+| E2E 测试 | 15% | 核心路径覆盖，跨浏览器 | [ ] |
+| 性能测试 | 15% | 基线建立，满足 SLA | [ ] |
+| 安全测试 | 10% | OWASP Top 10 覆盖 | [ ] |
+| 覆盖率管理 | 5% | CI 卡点，趋势监控 | [ ] |
+
+---
+
+## Agent Checklist
+
+以下为 AI Agent 在评估或建立测试策略时必须验证的硬约束：
+
+- [ ] 确认测试框架已安装且 `npm test` / `pytest` 可正常运行
+- [ ] 确认 CI 配置中包含测试执行步骤
+- [ ] 确认覆盖率工具已集成并有阈值卡点
+- [ ] 确认核心业务模块有对应的测试文件
+- [ ] 确认测试数据使用 factory/fixture 而非硬编码
+- [ ] 确认无测试直接调用外部真实服务
+- [ ] 确认 E2E 测试使用 Page Object Model 或等效封装
+- [ ] 确认安全扫描工具已集成到 CI
+- [ ] 确认性能基线数据已记录
+- [ ] 生成测试策略评估报告，标注各维度达标情况