ln-140-test-docs-creator

用途

ln-140-test-docs-creator 是一个 L2 Worker 技能，用于创建和校验测试文档，为项目建立通用测试理念与测试组织结构。它生成两份文档：

• docs/reference/guides/testing-strategy.md：通用测试理念（基于风险的测试、测试金字塔、隔离模式等）
• tests/README.md：测试组织结构（目录布局、Story-Level Test Task Pattern）

该技能通常由 ln-100-documents-pipeline 编排器调用，也可在以下情况直接使用：仅创建测试文档、校验既有测试文档的结构与内容、为已有项目搭建测试理念与结构文档。若需要创建完整文档结构，应使用 ln-100-documents-pipeline。

主要能力

技能遵循三阶段工作流：CREATE → VALIDATE STRUCTURE → VALIDATE CONTENT，不跳阶段。

阶段 1：创建测试文档

• 检查并创建目录：docs/reference/guides/、tests/、tests/manual/、tests/manual/results/，并将 tests/manual/results/ 加入 .gitignore
• 若 testing-strategy.md 不存在，则从模板 references/templates/testing_strategy_template.md 复制并替换 [CURRENT_DATE] 占位符
• 若 tests/README.md 不存在，则从模板 references/templates/tests_readme_template.md 复制并替换 {{DATE}} 占位符
• 已存在的文件跳过创建并进入校验

阶段 2：校验结构

• 检查并补齐 SCOPE 标签（testing-strategy.md 与 tests/README.md 各有预期 SCOPE 内容）
• 检查必需章节：testing-strategy.md 需含 "Testing Philosophy"、"Test Levels"；tests/README.md 需含 "Test Organization"、"Running Tests"
• 检查并补齐 Maintenance 章节（含 Last Updated、Update Triggers、Verification）
• 检查 POSIX 文件结尾（单个 LF 空行）
• 自动修复结构违规并输出汇总

阶段 3：校验内容

• 加载 references/questions.md 校验规范，对 2 个文件共 4 个章节进行启发式校验（任一启发式通过即视为有效）
• 对 testing-strategy.md 使用标准模板内容，无需自动发现
• 对 tests/README.md 执行自动发现：
  • 测试框架：检查 package.json（jest、vitest、mocha、ava、tap、jasmine）、requirements.txt（pytest、nose2、unittest2）、go.mod（内置 testing）
  • 测试目录结构：扫描 tests/automated/e2e、tests/automated/integration、tests/automated/unit，缺失时创建占位结构
  • 命名约定：从现有测试文件提取最常见模式（如 *.test.js、*.spec.ts、test_*.py、*_test.go），无文件时使用框架默认
  • 测试运行命令：读取 package.json 的 scripts.test，缺失时按框架使用默认命令
  • 覆盖率命令：查找 test:coverage、coverage、test:cov，缺失时使用框架默认
• 输出内容校验汇总

使用方式

该技能为文档生成技能，通过编排器或直接调用执行。执行时需加载以下参考文件：

• 必读：references/docs_quality_contract.md、references/markdown_read_protocol.md
• 可选：references/docs_quality_rules.json（仅在需要精确规则 ID、路径矩阵或占位符例外时加载）
• 必读：references/docs_generation_summary_contract.md

技能接受可选的 summaryArtifactPath 参数，返回规范化摘要（含 created_files、skipped_files、quality_inputs、validation_status），供 ln-100 运行集中式文档质量门禁。

适用场景

• 为项目搭建测试策略与测试文档结构
• 仅创建测试文档（testing-strategy.md + tests/README.md）
• 校验既有测试文档的结构与内容
• 为已有项目补充测试理念与组织结构文档

限制

• 仅生成测试文档，不生成实际测试代码
• 不创建完整文档结构（完整搭建应使用 ln-100-documents-pipeline）
• 三阶段流程不可跳过
• 实际测试目录（e2e/、integration/、unit/）在 Story 测试任务执行时或阶段 3 缺失时创建
• 文档遵循 NO_CODE 规则：描述策略而非测试实现
• 框架命令需匹配项目技术栈

输出结构

docs/reference/guides/
└── testing-strategy.md           # 通用测试理念（465 行）

tests/
└── README.md                     # 测试组织 + Story-Level Pattern（112 行）

关键规则

• 仅文档：创建测试文档，不创建实际测试代码
• 三阶段流水线：CREATE → VALIDATE STRUCTURE → VALIDATE CONTENT
• 自动发现优先：先扫描测试框架与目录结构，再回退到默认值
• 幂等执行：创建前检查存在性，每次运行重新校验且不重复
• 共享开头契约：两份文件均需包含 SCOPE、元数据标记、Quick Navigation、Agent Entry 和 Maintenance
• Story-Level Test Task Pattern：测试集中在最终 Story 任务中（测试规划者创建任务，测试执行者实现）
• 基于价值的测试：优先级 ≥15 必须测试，每个测试需由 Usefulness Criteria 证明

参考文件

• 基于风险的测试方法论：references/risk_based_testing_guide.md
• 测试策略模板：references/templates/testing_strategy_template.md
• 测试 README 模板：references/templates/tests_readme_template.md
• 校验规范：references/questions.md（v1.0.0）

前置条件

• 由 ln-100-documents-pipeline 编排器调用
• 需要 docs/reference/guides/ 目录（由 ln-120-reference-docs-creator 创建，或阶段 1 缺失时创建）
• 创建 docs/reference/guides/testing-strategy.md 与 tests/README.md，并校验结构与内容