Quality Assurance

质量保障

概述

质量保障是一项整合型技能，结合了三个关键的质量维度：全面的测试策略、代码质量执行和阶段门验证。它确保代码在每个阶段都经过测试、易于维护，并已准备好投入生产。

整合自：

• testing-strategist - 测试金字塔与全面测试
• code-quality-enforcer - 代码标准与最佳实践
• validation-gate-checker - 阶段转换验证

何时使用此技能

在以下情况下使用质量保障：

• 为项目搭建测试基础设施
• 开展代码审查
• 验证是否已准备好进入下一项目阶段
• 为团队制定质量标准
• 调试生产环境中的质量问题
• 提高代码可维护性
• 确保已具备生产就绪条件

关键能力

测试策略（来自 testing-strategist）

• 设计覆盖率合理的测试金字塔
• 制定单元测试、集成测试和端到端（E2E）测试策略
• 设定覆盖率目标和质量指标
• 选择测试框架和工具
• 规划测试自动化和 CI/CD 集成

代码质量（来自 code-quality-enforcer）

• 执行编码标准和最佳实践
• 审查代码的可读性和可维护性
• 识别安全漏洞和反模式
• 确保类型安全和错误处理
• 重构代码以提高质量分数

验证关卡（来自 validation-gate-checker）

• 定义阶段转换标准
• 验证是否已准备好进入下一阶段
• 确保交付物完整
• 检查是否符合标准
• 防止过早进行阶段转换

工作流

第 1 部分：测试策略

测试金字塔

结构：

        /\
       /E2E\      10% - End-to-End (Critical user flows)
      /------\
     /Integr-\   20% - Integration (Components, APIs, DB)
    /----------\
   /   Unit     \ 70% - Unit (Functions, classes, logic)
  /--------------\

理由：

• 单元测试运行快速、相互隔离且易于维护
• 集成测试能够发现组件交互问题
• E2E 测试验证关键用户工作流，但运行缓慢且容易失效

---

单元测试（占测试总数的 70%）

覆盖率目标：

• 关键代码（身份验证、支付、安全）：100%
• 业务逻辑：>90%
• 整体代码库：>85%

测试内容：

• 纯函数和业务逻辑
• 边界情况和错误条件
• 输入验证
• 状态管理
• 实用函数

最佳实践：

• 每个源文件对应一个测试文件
• 快速执行（每项测试 <1ms）
• 不依赖外部依赖项（使用 mock/stub）
• 使用描述性测试名称
• AAA 模式（Arrange、Act、Assert）

示例：

// Good: Fast, isolated, clear
describe('calculateDiscount', () => {
  it('applies 10% discount for orders over $100', () => {
    const result = calculateDiscount(150)
    expect(result).toBe(15)
  })

  it('returns 0 for orders under $100', () => {
    const result = calculateDiscount(50)
    expect(result).toBe(0)
  })

  it('throws error for negative amounts', () => {
    expect(() => calculateDiscount(-10)).toThrow()
  })
})

---

集成测试（占测试总数的 20%）

测试内容：

• 使用真实数据库的 API 端点
• 协同工作的多个组件
• 第三方服务集成（使用 mock）
• 数据库查询和事务
• 文件系统操作

最佳实践：

• 设置和清理测试数据库
• 使用测试数据库或事务
• 对外部服务进行 mock
• 测试正常流程和关键错误场景
• 每项测试 <5 秒

示例：

// Good: Real database, tests integration
describe('POST /api/users', () => {
  beforeEach(async () => {
    await db.users.deleteMany({})
  })

  it('creates user and returns 201', async () => {
    const response = await request(app)
      .post('/api/users')
      .send({ email: '[email protected]', name: 'Test' })

    expect(response.status).toBe(201)
    expect(response.body.email).toBe('[email protected]')

    const user = await db.users.findOne({ email: '[email protected]' })
    expect(user).toBeDefined()
  })

  it('returns 400 for duplicate email', async () => {
    await db.users.create({ email: '[email protected]' })

    const response = await request(app)
      .post('/api/users')
      .send({ email: '[email protected]', name: 'Test' })

    expect(response.status).toBe(400)
  })
})

---

E2E 测试（占测试总数的 10%）

测试内容：

• 关键用户工作流（注册、结账等）
• 跨多页的用户旅程
• 与后端交互的 UI 操作
• 跨浏览器兼容性（如有需要）

最佳实践：

• 仅测试关键路径
• 使用页面对象模式
• 在部署前于 CI/CD 中运行
• 可接受较慢的执行速度（每项测试 30 秒至 2 分钟）
• 在 CI 中使用无头浏览器

示例：

// Good: Tests complete user flow
describe('User Signup Flow', () => {
  it('allows new user to signup and access dashboard', async () => {
    await page.goto('/signup')

    await page.fill('input[name="email"]', '[email protected]')
    await page.fill('input[name="password"]', 'SecurePass123!')
    await page.click('button[type="submit"]')

    await page.waitForURL('/dashboard')
    expect(await page.textContent('h1')).toContain('Welcome')
  })
})

---

测试工具建议

JavaScript/TypeScript：

• 单元测试：Jest 或 Vitest
• 集成测试：Supertest（API）+ Jest
• E2E 测试：Playwright 或 Cypress

Python：

• 单元测试：pytest
• 集成测试：使用 fixtures 的 pytest
• E2E 测试：Selenium 或 Playwright

通用：

• 覆盖率：Istanbul（JS）、Coverage.py（Python）
• CI/CD：GitHub Actions、CircleCI、GitLab CI
• Mock：Jest（JS）、unittest.mock（Python）

---

第 2 部分：代码质量执行

代码质量原则

1. 可读性

• 使用描述性变量名和函数名
• 遵循单一职责原则
• 格式清晰且一致
• 注释解释“为什么”，而非“是什么”

2. 可维护性

• DRY（不要重复自己）
• SOLID 原则
• 类型安全（TypeScript、类型提示）
• 处处进行错误处理

3. 测试

• 为所有函数编写单元测试
• 覆盖边界情况
• 测试名称描述行为

4. 安全性

• 不硬编码机密信息
• 验证输入
• 防止 SQL 注入
• 防范 XSS

---

代码质量检查清单

代码审查前：

• 不硬编码机密信息或 API 密钥
• 函数长度 <50 行（更长时拆分）
• 包含错误处理（try/catch、空值检查）
• 所有测试均通过
• 类型安全（TypeScript 严格模式、Python 类型提示）
• 没有 console.log 或调试代码
• 变量名具有描述性（避免使用 x、tmp、data）
• 注释解释“为什么”，而非“是什么”
• 遵循 DRY——没有复制粘贴代码
• 遵循安全最佳实践（输入验证、清理）

---

代码审查指南

检查内容：

严重问题（必须修复）：

• 安全漏洞（SQL 注入、XSS、机密信息）
• 未经迁移处理的破坏性更改
• 缺少错误处理
• 逻辑或算法错误
• 性能瓶颈

重要问题（应该修复）：

• 代码重复（违反 DRY）
• 命名或结构不佳
• 新代码缺少测试
• 违反类型安全要求
• 格式不一致

次要问题（最好修复）：

• 风格不一致
• 注释过多
• 优化机会
• 改进文档

---

代码质量评分

评分体系（0-100）：

安全性（30 分）：

• 代码中没有机密信息（10 分）
• 输入验证（10 分）
• 错误处理（10 分）

可读性（25 分）：

• 描述性名称（10 分）
• 结构清晰（10 分）
• 注释恰当（5 分）

测试（25 分）：

• 单元测试覆盖率 >85%（15 分）
• 边界情况测试（10 分）

可维护性（20 分）：

• 遵循 DRY（10 分）
• 函数长度 <50 行（5 分）
• 类型安全（5 分）

评分等级：

• 90-100：优秀
• 80-89：良好
• 70-79：可接受
• <70：需要改进

---

第 3 部分：验证关卡

验证关卡确保每个阶段完成后再进入下一阶段。

阶段 1 → 阶段 2（探索 → 设计）

关卡标准：

• PRP 文档已完成并经过审查
• 已与用户验证问题陈述
• 已定义可衡量的成功标准
• 已记录用户故事（待完成工作）
• 利益相关者已就范围达成一致
• 已记录待解决问题及负责人

交付物：

• 产品需求提示（PRP）
• 用户研究摘要
• 成功指标仪表板

审查问题：

• 我们是否理解用户的问题？
• 我们能否衡量成功？
• 范围是否明确且已达成一致？

---

阶段 2 → 阶段 3（设计 → 开发）

关卡标准：

• 已记录架构（系统图）
• 已设计数据模型（ERD 或 schema）
• 已定义 API 契约（如适用）
• 已识别安全威胁（威胁模型）
• 已规划针对严重威胁的缓解措施
• 已批准技术栈
• 已记录基础设施计划

交付物：

• 架构文档
• 数据模型 / ERD
• API 规范（OpenAPI/Swagger）
• 含缓解措施的威胁模型
• 基础设施图

审查问题：

• 架构是否稳健且可扩展？
• 安全威胁是否已得到缓解？
• 我们是否具备所需的基础设施访问权限？

---

阶段 3 → 阶段 4（开发 → 测试）

关卡标准：

• 所有 P0 功能已完成
• 单元测试覆盖率 >80%
• 已完成代码审查
• 静态分析（SAST）通过
• 没有严重或高严重级别的问题
• 已实现错误处理
• 已设置日志记录和监控

交付物：

• 可运行的软件（包含所有 P0 功能）
• 测试覆盖率报告
• 代码审查批准
• SAST 扫描结果

审查问题：

• 所有 MVP 功能都已完成吗？
• 代码质量是否达标？
• 严重错误是否已解决？

---

阶段 4 → 阶段 5（测试 → 部署）

关卡标准：

• 所有测试均已通过（单元、集成、E2E）
• 测试覆盖率 >90%
• 已完成用户验收测试（UAT）
• 安全测试已通过（DAST、渗透测试）
• 性能测试已通过（负载、压力）
• 文档已完成（用户文档和开发文档）
• 已记录回滚计划
• 部署操作手册已就绪

交付物：

• 测试结果（全部通过）
• UAT 批准
• 安全测试报告
• 性能测试结果
• 部署操作手册

审查问题：

• 我们是否对质量有信心？
• 如有需要，我们能否回滚？
• 生产基础设施是否已就绪？

---

示例

示例 1：API 测试策略

项目： 用户管理 REST API

测试计划：

单元测试（70%）：

• 业务逻辑（验证、权限）
• 数据转换
• 工具函数
• 错误处理逻辑

集成测试（20%）：

• POST /users（在 DB 中创建用户）
• GET /users/:id（从 DB 中获取用户）
• PUT /users/:id（在 DB 中更新用户）
• DELETE /users/:id（从 DB 中删除用户）
• 身份验证中间件
• 错误响应（400、401、404、500）

E2E 测试（10%）：

• 完整注册流程（创建用户 → 验证电子邮件 → 登录）
• 密码重置流程
• 个人资料更新流程

工具：

• Jest（单元测试）
• Supertest（集成测试）
• Playwright（E2E）

覆盖率目标： 整体 90%

---

示例 2：代码质量审查

之前（质量差 - 得分：55/100）：

// Bad: Hardcoded secret, no error handling, poor naming
function getData(x) {
  const result = fetch('https://api.example.com/data', {
    headers: { Authorization: 'Bearer sk_live_abc123' }
  })
  return result.json()
}

问题：

• 安全性：API 密钥硬编码（-10 分）
• 错误处理：没有错误处理（-10 分）
• 命名：变量名称不佳（-10 分）
• 测试：没有测试（-15 分）

之后（质量良好 - 得分：95/100）：

// Good: Secure, robust, clear
async function fetchUserData(userId: string): Promise<UserData> {
  try {
    const apiKey = process.env.API_KEY;
    if (!apiKey) {
      throw new Error('API_KEY environment variable not set');
    }

    const response = await fetch(`https://api.example.com/users/${userId}`, {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    });

    if (!response.ok) {
      throw new Error(`API request failed: ${response.status}`);
    }

    return await response.json();
  } catch (error) {
    logger.error('Failed to fetch user data', { userId, error });
    throw new Error(`Failed to fetch user ${userId}`);
  }
}

// Tests
describe('fetchUserData', () => {
  it('fetches user successfully', async () => {
    // Test implementation
  });

  it('throws error if API_KEY not set', async () => {
    // Test implementation
  });
});

---

示例 3：阶段关卡验证

项目： 客户支持聊天机器人（阶段 3 → 阶段 4）

验证检查：

要求：

• ✅ 所有 P0 功能已完成（聊天 UI、AI 回复、升级处理）
• ✅ 单元测试覆盖率：87%
• ✅ 代码审查：已批准（2 位审查者）
• ❌ SAST 扫描：发现 3 个中等严重级别问题（失败）
• ✅ 错误处理：已实现
• ✅ 日志记录：Datadog 集成已完成

决定： 关卡未通过 - 必须先修复 SAST 问题才能继续

待办事项：

1. 修复 3 个中等严重级别问题（输入验证）
2. 重新运行 SAST 扫描
3. 重新审查关卡标准

预计通过时间： 2 天

---

最佳实践

测试

1. 先编写测试（TDD） - 明确需求
2. 保持测试相互独立 - 不共享状态
3. 测试行为，而非实现 - 确保测试在重构后仍有效
4. 使用描述性测试名称 - 测试就是文档
5. 快速失败 - 先运行速度快的测试

代码质量

1. 自动化质量检查 - ESLint、Prettier、类型检查
2. 先自行审查代码 - 发现明显问题
3. 保持 PR 小而聚焦 - 更容易全面审查
4. 修复根本原因 - 不要只修补表面问题
5. 持续重构 - 不要积累技术债务

验证关卡

1. 提前记录标准 - 避免意外
2. 严格把控关键关卡 - 安全性、生产就绪状态
3. 对非必需项保持灵活 - 不要阻碍进度
4. 跟踪关卡通过情况 - 找出瓶颈
5. 自动化检查 - 通过 CI/CD 强制执行

---

常见陷阱

1. 测试错误的内容

反模式： 测试实现细节（私有方法）
更好的做法： 测试公共 API 和行为

2. 边界情况覆盖不足

反模式： 只测试正常路径 更好的做法： 测试空值、空数组、错误和边界条件

3. 跳过阶段门禁

反模式：“发布后再修” 结果： 生产环境漏洞、安全问题

更好的做法： 强制执行门禁，必要时延迟发布

4. 质量过度工程化

反模式： 所有内容都要求 100% 覆盖率，陷入完美主义 更好的做法： 根据风险采取务实的质量标准

5. 手动进行质量检查

反模式： 记得在提交前运行代码检查工具 更好的做法： 在提交前钩子和 CI/CD 中实现自动化

---

相关技能

• testing-strategist - 原始测试技能（现已整合）
• security-architect - 安全测试和威胁验证
• deployment-advisor - 生产就绪验证
• performance-optimizer - 性能测试和优化
• framework-orchestrator - 使用验证门禁进行阶段转换

---

交付物

使用质量保证时，请产出：

1. 测试策略文档

   • 测试金字塔拆解
   • 覆盖率目标
   • 工具和框架
   • CI/CD 集成计划

2. 代码质量标准

   • 风格指南
   • 代码检查规则
   • 审查清单
   • 质量评分标准

3. 阶段门禁标准

   • 各阶段的进入／退出标准
   • 必需的交付物
   • 审查流程
   • 批准权限

4. 质量仪表板

   • 测试覆盖率指标
   • 代码质量评分
   • 门禁通过情况跟踪
   • 趋势分析

---

成功指标

在以下情况下，质量保证发挥了作用：

• 测试覆盖率持续高于 85%
• 生产环境漏洞占发布次数的比例低于 1%
• 代码审查能在合并前发现问题
• 阶段门禁能阻止过早转换
• 质量随时间提升（而非下降）
• 团队无需强制要求也能遵循标准
• CI/CD 流水线自动执行质量检查

---

请记住： 质量不是可选项。它决定了软件是可持续发展，还是陷入技术破产。