测试和质量门禁
目的
定义软件团队的测试层级和 CI 门禁。
测试层级
| 层级 | 目的 | 示例 |
|---|---|---|
| Unit | 快速验证核心逻辑 | pure function、reducer |
| Integration | 验证 DB/API/service 边界 | API + Postgres |
| Contract | 验证协议兼容性 | runtime claim payload、webhook schema |
| E2E smoke | 验证关键用户路径 | task -> run -> artifact |
| Release smoke | 发布后信心检查 | health check、关键 route |
| Manual exploratory | 高风险 UX/产品变化 | payment、onboarding、permissions |
门禁语义
不要把 pnpm check 这类命令名当成标准本身。真正的标准是它背后的验证语义：代码是否格式正确、类型/编译是否通过、测试是否通过、能否构建、migration 是否可执行、关键路径是否仍然可用。
三角色质量责任
| 角色 | 负责判断 | 最低证据 |
|---|---|---|
| 技术负责人 | 测试覆盖是否匹配风险，失败是否阻止合并 | test / build / migration / smoke 结果 |
| 产品负责人 | 用户可见路径是否符合验收 | 截图、录屏、staging 链接、产品验收 |
| 平台 / 资深工程师 | 命令是否稳定、CI 是否可复现 | CI 配置、命令说明、失败排障方式 |
| 门禁 | 必须验证什么 | 失败时含义 | | --- | --- | | Format | 代码格式符合仓库规范 | 代码风格不可合并 | | Lint / static analysis | 常见 bug、未使用代码、危险模式被拦截 | 可能存在静态风险 | | Typecheck / compile | 类型系统或编译器能通过 | 代码无法可靠运行或构建 | | Unit test | 核心逻辑仍符合预期 | 行为回归 | | Integration test | DB/API/service 边界仍兼容 | 模块间契约破坏 | | Build | 生产 artifact、镜像或包能生成 | 无法部署或发布 | | Migration check | schema 变化可执行、可审查 | 数据库升级风险 | | Smoke | 关键用户路径或交付闭环仍可用 | 系统主路径不可用 | | Witness / provider smoke | 外部集成最小真实路径仍可用 | 第三方或 provider 集成失效 |
不同技术栈的命令映射
| 技术栈 | Format / lint | Typecheck / compile | Test | Build | Migration / smoke |
|---|---|---|---|---|---|
| JS/TS | pnpm lint |
pnpm typecheck |
pnpm test |
pnpm build |
pnpm db:migrate、pnpm smoke:* |
| Go | gofmt -l . && go vet ./... |
go test ./... 覆盖编译 |
go test ./... |
go build ./... |
项目 migration CLI、项目 smoke 脚本 |
| Python | ruff check .、black --check . |
mypy . 或 pyright |
pytest |
python -m build 或 Docker build |
Alembic/Django migration、项目 smoke 脚本 |
| Rust | cargo fmt --check、cargo clippy -- -D warnings |
cargo check |
cargo test |
cargo build --release |
SQLx/Diesel migration、项目 smoke 脚本 |
| Java/Kotlin | ./gradlew checkstyleMain 或同类任务 |
./gradlew compileJava / compileKotlin |
./gradlew test |
./gradlew build |
Flyway/Liquibase、项目 smoke 脚本 |
| Swift/iOS | SwiftLint 或 formatter check | xcodebuild build |
xcodebuild test |
archive/build action | migration/smoke 按 app 后端或本地 fixture 定义 |
JS/TS 参考命令
如果仓库使用 pnpm workspace，可以把上面的门禁聚合成这些脚本：
| 参考命令 | 具体应该做什么 |
|---|---|
pnpm lint |
运行 ESLint、formatter check，必要时包含 import/order、accessibility lint |
pnpm typecheck |
运行 tsc --noEmit 或框架等价 typecheck |
pnpm test |
运行 unit/integration tests，例如 Vitest/Jest/Playwright component tests |
pnpm build |
生成生产 Web/API artifact，验证 bundler、server build、类型生成 |
pnpm check |
聚合 lint、typecheck、test、build 中适合合并前必跑的门禁 |
pnpm runtime:test |
测 runtime daemon 的 claim、heartbeat、状态转换、错误回传 |
pnpm runtime:build |
编译 runtime daemon，确保可发布或可打包 |
pnpm db:migrate |
在本地或 CI 数据库执行 migration，验证 schema 可升级 |
pnpm smoke:m1 |
跑最小交付闭环，例如 task -> run -> artifact -> approval |
pnpm witness:test |
跑外部集成 witness fixture，验证 webhook、签名、payload、权限映射 |
pnpm smoke:codex |
使用真实 provider/app-server 跑一次受控 smoke，验证 provider 集成没有漂移 |
CI 必须门禁
- 使用 frozen lockfile 安装。
- Lint/typecheck。
- Unit/integration tests。
- Build。
- Runtime daemon tests。
- Migration check。
- 关键交付闭环 smoke。
- 安全和依赖扫描。
参考实现可以在 CI 中启动 Postgres，并执行 pnpm check、pnpm db:migrate、pnpm smoke:m1。实际项目应替换为自己的等价质量门禁，并在 README 或 CI 文档中说明每个命令覆盖哪些验证语义。
质量标准
变更完成必须有证据：
| 变更 | 证据 |
|---|---|
| UI | 截图或 E2E/smoke 证明 |
| API | request/response test |
| DB migration | migration test 或 rollback note |
| Runtime | daemon test 和 protocol fixture |
| Provider integration | witness 或 smoke |
| Security | permission test 或 review note |
后续 Agent 就绪要求
这一节在人类测试和质量门禁稳定后再看。
Agent run 必须产出测试证据作为 artifact。没有证据的 run 应视为未完成。
下一步阅读
读完或填完这份文档后，通常继续看：
- 32-PR评审-pr-review.md：质量门禁明确后，继续看 PR 如何提交和评审。