testing-best-practices

测试最佳实践

实用的 QA 指南，帮助将产品行为、需求和代码路径转化为有用的检查项。适用于手动测试用例、测试计划、覆盖率审查、自动化场景、单元测试、Playwright 浏览器和组件集成测试、定位器、/unit-test-grill、/integration-test-grill 和 /testcase-grill。

核心不在于某个特定框架，而在于测试规范：

• 从用户可见或公开的契约出发：哪些必须正常工作，哪些可能失败，以及哪些绝不能发生。
• 根据风险选择合适的测试形式：探索性记录、手动测试用例、回归检查清单、单元测试覆盖、集成场景或自动化任务。
• 确保每项检查都能验证有意义的行为、需求、分支、状态转换、错误路径或清理保证。
• 让覆盖范围保持聚焦。分别测试相互独立的维度，避免产生嘈杂的笛卡尔积，并跳过那些只是在重复测试平台本身的随意边界值。
• 忠于项目现状：新增结构之前，先阅读相邻测试、现有 QA 工件、产品流程、架构和自动化约定。
• 将集成测试定位器和测试数据视为需要维护的测试 API；变更架构或实现时，应一并更新受影响的检查项。

选择测试对象后，请参阅对应的规则文件。目前的详细规则涵盖自动化单元测试、语义化集成定位器，以及存储在代码库中的产品测试用例；对于其他 QA 形式，请遵循本文件的核心默认原则，并确保输出具体到测试人员或自动化工程师可以执行。

适用场景

以下情况请参考这些指南：

• 创建手动测试用例、冒烟检查、回归套件、验收场景或探索性测试章程。
• 生成、修订、审查或重组存储在代码库测试用例目录中的结构化测试用例。
• 规划或审查针对应用行为的自动化覆盖。
• 为代码添加自动化测试或审查自动化测试。
• 查找行为覆盖、分支覆盖、状态转换、清理检查或错误路径方面的缺漏。
• 确定测试文件或 QA 检查清单中检查项的命名、排序和范围。
• 创建或审查集成测试定位器，包括其语义名称、架构路径、JSX 属性和受影响的检查项。
• 调用 /unit-test-grill，将代码行为转化为检查清单，而不编写测试代码。
• 调用 /integration-test-grill，将已确认的产品用例映射到浏览器或组件自动化，而不编写测试代码。
• 调用 /testcase-grill，将页面或区块转化为归属明确的测试用例列表，而不将其写入目录。

QA 默认原则

• 每项检查围绕一个行为或需求编写；在格式需要时，明确前置条件、操作和预期结果。
• 当区分会影响执行优先级时，将冒烟、关键路径、回归、负向、边界、权限、数据状态和恢复检查分别列出。
• 优先使用描述预期行为而非实现细节的场景名称。
• 仅在影响可复现性时注明准备数据、环境假设和清理步骤。
• 根据稳定性和价值标记自动化候选项：优先覆盖重复的关键路径、高风险回归、确定性状态和可靠断言。
• 在预期结果、数据要求和定位器策略足够稳定且易于维护之前，不要将场景自动化。
• 审查时，指出具体缺失的检查项或不稳定的假设；不要将覆盖率百分比或技术名称作为主要发现。

规则索引

应用任何特定主题的单元测试规则前，请先阅读 unit-test-conventions。

• unit-test-function - 公共输入、自有转换、分支、错误和异步协作者边界。
• unit-test-react-hook - Hook 的公共契约、变化的参数、异步工作、清理以及浏览器／监听器行为。
• unit-test-react-component-standalone - 独立组件的 DOM、属性、状态、交互和无障碍性。
• unit-test-react-component-compound - 公共组成部分，以及它们之间的状态、上下文、行为和无障碍性关系。
• unit-test-grill - /unit-test-grill 的场景规划模式，分为需要改进的现有测试和需要创建的新测试。

应用任何应用集成测试规则前，请先阅读 integration-test-conventions。

• integration-test-browser - 当测试用例需要导航、浏览器管理的状态、应用启动，或其他完整浏览器边界时使用。
• integration-test-component - 逼真的已挂载功能边界、包装器、提供者，以及可观察的组件集成行为。
• integration-test-server — 公共服务端入口和服务编排。
• integration-test-mocks - 场景所属的模拟状态、用例 ID、处理器和就近存放的文件结构。
• integration-test-locator-testids - 语义化测试 ID 方案、复用、生成的常量，以及有条件地使用 @siberiacancode/testids。
• integration-test-setup — 测试用例的前置条件、组件包装器、路由器和查询状态、挂载及就绪状态。
• integration-test-grill - 由测试用例驱动的自动化规划，分为需要改进的现有自动化测试和需要创建的新浏览器或组件测试。

应用任何特定主题的测试用例规则前，请先阅读 testcase-conventions。

• testcase-file-structure - 文件夹和文件的归属、覆盖重复，以及子屏幕和可复用区块的存放位置。
• testcase-naming - 点分层级、精确的界面标签，以及加载、空列表和数据用例的固定形式。
• testcase-content - 原子化用例、面向用户的操作、具体的预期结果，以及设计、功能和数据检查之间的划分。
• testcase-preconditions - 用例文件、文件夹和全局前置条件的范围。
• testcase-grill - /testcase-grill 的用例规划模式，分为需要改进的现有用例和需要创建的新用例。

使用方法

1. 明确测试目标：手动 QA、测试用例设计、覆盖率审查、自动化规划、自动化测试实现或集成测试设计。
2. 明确测试对象：产品流程、需求、API、数据状态、函数、UI 行为、hook、组件或跨组件集成。
3. 选择符合请求的输出格式。对于手动 QA，编写可执行的测试用例或按优先级排序的检查清单。对于自动化，编写稳定的场景或代码级测试。
4. 对于单元测试，先阅读通用约定，然后仅阅读与被测代码相匹配的具体规则。
5. 对于浏览器 API 或监听器 hook，仅当存在相应行为时，才阅读 hook 规则中链接的参考资料。
6. 对于集成测试，先阅读通用约定，然后仅阅读所选浏览器或组件边界、mock、定位器或 grill 模式所需的规则。
7. 对于存储在仓库中的测试用例，先阅读测试用例约定，然后仅阅读与任务相匹配的规则：选择或重组文件时阅读结构规则，编写 name 时阅读命名规则，编写步骤和预期结果时阅读内容规则，添加或移动设置时阅读前置条件规则，列出用例后再编写时阅读 grill 规则。

自动化测试默认原则

• 现有仓库约定优先于通用测试偏好。
• 先检查同一模块的测试，然后检查最接近的可比测试、相邻层测试、现有 helper，最后才检查实现。
• 模仿最接近的可行模式，并尽可能减少结构改动；除非可比测试已采用新的抽象，或正确性确有需要，否则不要重新设计测试套件或添加新的抽象。
• 仅根据明确的行为、项目通常覆盖的实现分支、类似测试、用户需求、回归问题或既定覆盖模式添加场景。
• 如果没有相关的项目约定，请使用 Should <observable behavior>、就近放置测试、直接设置，仅对真正重复的用例使用 forEach，仅在多个维度相互影响时合并用例。

完整编译文档

编译后的概览请参阅 AGENTS.md。