SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场ln-512-manual-tester

ln-512-manual-tester

测试与质量

查看项目

更新于 10-16 09:21

技能介绍

用途

ln-512-manual-tester 用于在运行中的代码上手动验证 Story 的验收标准（AC），并向质量门禁报告结构化结果。它由 ln-510-test-planner 在 ln-511-test-researcher 完成后调用，前提是 Story 上存在来自 ln-511 的“## Test Research:”研究评论，且 Story 中所有实现任务状态为 Done。

主要能力

  • 在目标项目的 tests/manual/ 文件夹中创建可执行测试脚本，并永久保存用于回归测试（非临时文件）。
  • 通过 bash/curl（API）或 puppeteer（UI）运行 AC 驱动的检查。
  • 在 Linear 中记录结果，包含每个 AC 的通过/失败状态和脚本路径。
  • 不更改状态，不创建任务，仅提供证据和结论。

测试设计原则

  1. 快速失败（Fail-Fast）：当任何标准未满足时，测试必须立即返回 1（失败）。禁止使用 print_status "WARN" + return 0 处理验证失败、无显式标志的优雅降级、隐藏错误的静默回退。例外（WARN 可接受）：不影响正确性的信息性警告、可选功能（需在注释中明确说明理由）、基础设施问题（如开发环境缺少 Nginx）。
  2. 基于期望的测试（Expected-Based Testing）：测试必须将实际结果与期望参考文件比较，而非应用启发式或算法检查。目录结构示例：tests/manual/NN-feature/ 下包含 samples/（输入文件）、expected/（期望输出文件，必需）、test-*.sh。启发式仅适用于动态/非确定性数据（时间戳、UUID、令牌——比较前需规范化；无序键的 JSON——使用 jq --sort-keys）。
  3. 结果存储：测试结果保存到 tests/manual/results/（持久化，加入 .gitignore），命名为 result_{ac_name}.{ext} 或 response_{ac_name}.json，测试完成后可检查用于调试。
  4. 期望文件生成：运行测试并查看 results/ 中的输出；若正确，复制到 expected/ 并正确命名；若错误，先修复实现再复制。切勿盲目复制结果到 expected，必须先验证正确性。

使用方式

工作流程

阶段 1：设置 tests/manual 结构

  • 阅读 docs/project/runbook.md 获取 Docker 命令、API 基础 URL、测试前提条件和环境设置。
  • 检查项目根目录是否存在 tests/manual/ 文件夹。若缺失，创建结构：config.sh（共享配置）、README.md（文件夹文档）、test-all.sh（运行所有测试套件的主脚本）、results/（测试输出文件夹，加入 .gitignore）。
  • 若存在，读取现有 config.sh 复用设置（BASE_URL、令牌）。

阶段 2：创建 Story 测试脚本

  • 获取 Story，将 AC 解析为 Given/When/Then 列表（3-5 个期望）。
  • 检查研究评论（来自 ln-511-test-researcher），将发现纳入测试用例。
  • 检测 API 还是 UI（API → curl，UI → puppeteer）。
  • 创建测试文件夹结构：tests/manual/{NN}-{story-slug}/samples/（输入文件，如需要）、expected/（期望输出文件，确定性测试必需）。
  • 生成测试脚本：tests/manual/{NN}-{story-slug}/test-{story-slug}.sh，使用适当模板（TEMPLATE-api-endpoint.sh 用于直接调用，TEMPLATE-document-format.sh 用于异步任务）。脚本包含：头部（Story ID、AC 列表、前提条件）、每个 AC 的测试函数及边界/错误用例、基于 diff 的验证（主要方式）、结果保存到 tests/manual/results/、带计时的摘要表。使脚本可执行（chmod +x）。

阶段 2.5：更新文档

  • 更新 tests/manual/README.md：在“Available Test Suites”表中添加新测试，包含 Story ID、覆盖的 AC、运行命令。
  • 更新 tests/manual/test-all.sh：在 SUITES 数组中添加对新脚本的调用，保持执行顺序（00-setup 优先，然后编号套件）。

阶段 3：执行并报告

  • 重新构建 Docker 容器（无缓存），确保健康。
  • 运行生成的脚本，捕获输出。
  • 解析结果（通过/失败计数）。
  • 发布 Linear 评论，包含：AC 矩阵（每个 AC 的通过/失败）、脚本路径、重跑命令。

关键规则

  • 脚本保存到项目 tests/manual/，而非临时文件。
  • 测试前重新构建 Docker；若重建/运行不健康则失败。
  • 在脚本注释和 Linear 评论中保持 Story 的语言（EN/RU）。
  • 不修复，不更改状态；仅提供证据和结论。
  • 脚本必须幂等（可随时重跑）。

完成定义（Definition of Done）

  • tests/manual/ 结构存在（config.sh、README.md、test-all.sh、results/ 如缺失则创建）。
  • tests/manual/results/ 已加入项目 .gitignore。
  • 测试脚本创建于 tests/manual/{NN}-{story-slug}/test-{story-slug}.sh。
  • expected/ 文件夹已创建，每个确定性 AC 至少有一个期望文件。
  • 脚本使用基于 diff 的验证（非启发式）。
  • 脚本将结果保存到 tests/manual/results/ 供调试。
  • 脚本可执行且幂等。
  • README.md 已在“Available Test Suites”表中更新新测试套件。
  • test-all.sh 已在 SUITES 数组中更新对新脚本的调用。
  • 应用已重建并运行；测试已执行。
  • 已发布结论和 Linear 评论，包含脚本路径和重跑命令。

适用场景

  • 由 ln-510-test-planner 在 ln-511-test-researcher 完成后调用。
  • Story 上存在“## Test Research:”研究评论。
  • Story 中所有实现任务状态为 Done。

限制

  • 不更改状态，不创建任务。
  • 仅提供证据和结论，不进行修复。
  • 需要 Docker 容器运行、jq 已安装。
  • 测试前必须重新构建 Docker，若重建/运行不健康则失败。

脚本模板与参考文件

  • README.md（每个项目创建一次）：包含快速开始、前提条件、文件夹结构、可用测试套件表、添加新测试说明。
  • test-all.sh（每个项目创建一次）：运行所有手动测试套件的主脚本。
  • config.sh（每个项目创建一次）：共享配置（BASE_URL、辅助函数、颜色）。
  • 测试脚本模板：template-api-endpoint.sh（API 端点测试，无异步任务）、template-document-format.sh（文档/文件处理，有异步任务）。
  • 参考文件：脚本格式参考 prompsit-api tests/manual/（生产示例）、AC 格式 shared/templates/test_task_template.md、基于风险的上下文 ln-513-auto-test-planner/references/risk_based_testing_guide.md、研究发现 ln-511-test-researcher 创建的“## Test Research”评论。

版本：1.0.0（从 ln-503 重命名，阶段 0 研究移至 ln-511-test-researcher）。最后更新：2026-01-15。