ln-140-test-docs-creator

路径： 文件路径（references/、../ln-*）均相对于此技能目录。

测试文档创建器

类型： L2 Worker

此技能用于创建和验证测试文档：testing-strategy.md（通用测试理念）+ tests/README.md（测试组织结构，包含 tests/automated/ + Story-Level Test Task Pattern）。

目的

创建和验证测试文档（testing-strategy.md + tests/README.md），为任何项目确立通用测试理念、基于风险的测试策略、作为默认自动化测试根目录的 tests/automated/，以及 Story-Level Test Task Pattern。

何时使用此技能

此技能是由 ln-100-documents-pipeline 编排器调用的 L2 WORKER。

以下情况应直接使用此技能：

• 仅创建测试文档（testing-strategy.md + tests/README.md）
• 验证现有测试文档的结构和内容
• 为现有项目设置测试理念和结构文档
• 不创建完整文档结构（完整设置请使用 ln-100-documents-pipeline）

工作流

此技能遵循 3 阶段工作流：创建 → 验证结构 → 验证内容。每个阶段都在前一阶段的基础上推进，确保结构完整并完成语义验证。

必须阅读： 加载 references/docs_quality_contract.md 和 references/markdown_read_protocol.md。 可选规则目录：仅在需要精确规则 ID、路径矩阵或允许的占位符例外时，加载 references/docs_quality_rules.json。

---

阶段 1：创建测试文档

目标：确立测试理念和文档结构。

流程：

1.1 检查并创建目录：

• 检查 docs/reference/guides/ 是否存在 → 如不存在则创建
• 检查 tests/ 是否存在 → 如不存在则创建
• 检查 tests/manual/ 是否存在 → 如不存在则创建
• 检查 tests/manual/results/ 是否存在 → 如不存在则创建
• 如果项目 .gitignore 中尚未包含 tests/manual/results/，则将其添加到 .gitignore
• 对每项记录日志："✓ 已创建 [directory]/" 或 "✓ [directory]/ 已存在"

1.2 检查并创建文档文件：

• 检查 docs/reference/guides/testing-strategy.md 是否存在

• 如果存在：

  • 跳过创建
  • 记录日志："✓ testing-strategy.md 已存在，继续验证"

• 如果不存在：

  • 复制模板：ln-140-test-docs-creator/references/templates/testing_strategy_template.md → docs/reference/guides/testing-strategy.md
  • 替换占位符：
    • [CURRENT_DATE] — 当前日期（YYYY-MM-DD）
  • 保留模板中的共享元数据标记和标准顶部章节
  • 记录日志："✓ 已根据模板创建 testing-strategy.md"

• 检查 tests/README.md 是否存在

• 如果存在：

  • 跳过创建
  • 记录日志："✓ tests/README.md 已存在，继续验证"

• 如果不存在：

  • 复制模板：ln-140-test-docs-creator/references/templates/tests_readme_template.md → tests/README.md
  • 替换占位符：
    • {{DATE}} — 当前日期（YYYY-MM-DD）
  • 保留模板中的共享元数据标记和标准顶部章节
  • 记录日志："✓ 已根据模板创建 tests/README.md"

1.3 输出：

docs/reference/guides/
└── testing-strategy.md           # Created or existing

tests/
├── README.md                     # Created or existing
└── manual/
    └── results/                  # Created, added to .gitignore

---

阶段 2：验证结构

目标：确保测试文档文件符合结构要求，并自动修复违规项。

流程：

2.1 检查 SCOPE 标签：

• 读取两个文件（testing-strategy.md、tests/README.md）——先检查开头部分
• 检查每个文件是否包含 `` 标签和元数据标记
• 预期的 SCOPE 标签：
  • testing-strategy.md：``
  • tests/README.md：``
• 如果任一文件缺少标签：
  • 使用 Edit 工具在第 1 行（第一个标题之前）添加 SCOPE 标签
  • 记录违规项：scope_tags_added += 1

2.2 检查必需章节：

• 从 references/questions.md 加载预期章节
• 对于 testing-strategy.md，必需章节：
  • “测试理念”
  • “测试级别”
• 对于 tests/README.md，必需章节：
  • “测试组织”
  • “运行测试”
• 对于每个文件：
  • 读取文件内容
  • 检查是否存在 ## [Section Name] 标题
  • 如果缺少：
    • 使用 Edit 工具，根据模板添加包含最少具体指导的章节，而非原始占位内容
    • 记录违规项：missing_sections += 1

2.3 检查 Maintenance 章节：

• 对于每个文件（testing-strategy.md、tests/README.md）：
  • 搜索 ## Maintenance 标题
  • 如果缺少：
    • 使用 Edit 工具在文件末尾添加：

      ## Maintenance
      
      **Last Updated:** [current date]
      
      **Update Triggers:**
      - Test framework changes
      - Test organization changes
      - New test patterns introduced
      
      **Verification:**
      - [ ] All test examples follow current framework syntax
      - [ ] Directory structure matches actual tests/
      - [ ] Test runner commands are current
      

    • 记录违规项：maintenance_added += 1

2.4 检查 POSIX 文件结尾：

• 对于每个文件：
  • 检查文件是否以一个空行（LF）结尾
  • 如果缺少：
    • 使用 Edit 工具添加末尾换行符
    • 记录修复项：posix_fixed += 1

2.5 报告验证结果：

• 记录摘要：

  ✅ Structure validation complete:
    - SCOPE tags: [added N / already present]
    - Missing sections: [added N sections]
    - Maintenance sections: [added N / already present]
    - POSIX endings: [fixed N / compliant]
  

• 如果发现违规项：“⚠️ 已自动修复 [total] 项结构违规”

---

阶段 3：验证内容

目标：确保每个章节都以有意义的内容回答相关问题，并通过自动发现填充测试专属章节。

流程：

3.1 加载验证规范：

• 读取 references/questions.md
• 解析 4 个章节（每个文件 2 个章节）的问题和验证启发式规则

3.2 验证 testing-strategy.md 章节：

对于此文件，使用标准模板内容（无需自动发现）：

1. 测试理念章节：

   • 读取章节内容
   • 根据 questions.md 中的验证启发式规则进行检查：
     • ✅ 提及“基于风险的测试”
     • ✅ 包含测试金字塔说明
     • ✅ 提及优先级阈值（≥15）
     • ✅ 引用 Story-Level Test Task Pattern
     • ✅ 长度超过 100 个单词
   • 如果任一启发式检查通过 → 内容有效
   • 如果全部未通过 → 记录警告：“⚠️ testing-strategy.md → 测试理念章节可能需要检查”

2. 测试级别章节：

   • 读取章节内容
   • 根据 questions.md 中的验证启发式规则进行检查：
     • ✅ 列出 3 个级别（E2E、Integration、Unit）
     • ✅ 包含数值范围（2-5、3-8、5-15）
     • ✅ 说明理由
     • ✅ 长度超过 150 个单词
   • 如果任一启发式检查通过 → 内容有效
   • 如果全部未通过 → 记录警告：“⚠️ testing-strategy.md → 测试级别章节可能需要检查”

注意：testing-strategy.md 是通用理念——无需针对项目进行自动发现。

3.3 使用自动发现验证 tests/README.md 章节：

章节：测试组织

1. 自动发现测试框架：

   • 检查 package.json → "devDependencies" 和 "dependencies"：
     • Node.js 框架：jest、vitest、mocha、ava、tap、jasmine
     • 如果找到：提取名称和版本
   • 检查 requirements.txt（如果是 Python 项目）：
     • Python 框架：pytest、nose2、unittest2
     • 如果找到：提取名称和版本
   • 检查 go.mod（如果是 Go 项目）：
     • Go 使用内置的 testing 包
   • 如果检测到框架：
     • 记录日志："✓ 已检测到测试框架：[framework]@[version]"
     • 记录：framework_detected = "[framework]"
   • 如果未检测到：
     • 记录日志："⚠️ 未检测到测试框架。将使用通用测试组织方式。"
     • 记录：framework_detected = None

2. 自动发现测试目录结构：

   • 使用 Glob 工具扫描 tests/ 目录：
     • 模式："tests/automated/e2e/**/*.{js,ts,py,go}"
     • 模式："tests/automated/integration/**/*.{js,ts,py,go}"
     • 模式："tests/automated/unit/**/*.{js,ts,py,go}"
   • 统计各目录中的文件数：
     • e2e_count = len(e2e_files)
     • integration_count = len(integration_files)
     • unit_count = len(unit_files)
   • 如果目录存在：
     • 记录日志："✓ 测试结构：[e2e_count] 个 E2E、[integration_count] 个集成测试、[unit_count] 个单元测试"
   • 如果目录不存在：
     • 创建占位结构：

       tests/
         automated/
           e2e/         (empty, ready for E2E tests)
           integration/ (empty, ready for Integration tests)
           unit/        (empty, ready for Unit tests)
       

     • 记录日志："✓ 已创建测试目录结构（将在 Story 测试任务执行期间填充）"

3. 自动发现命名约定：

   • 对于找到的每个测试文件（来自步骤 2）：
     • 提取文件名模式：
       • *.test.js → "*.test.js" 约定
       • *.spec.ts → "*.spec.ts" 约定
       • test_*.py → "test_*.py" 约定
       • *_test.go → "*_test.go" 约定
   • 统计每种模式的出现次数
   • 使用最常见的模式（多数规则）
   • 如果检测到模式：
     • 记录日志："✓ 命名约定：[pattern]（根据 [count] 个文件检测得出）"
   • 如果不存在文件：
     • 使用框架默认值：
       • Jest/Vitest → *.test.js
       • Mocha → *.spec.js
       • Pytest → test_*.py
       • Go → *_test.go
     • 记录日志："✓ 命名约定：[default_pattern]（框架默认值）"

4. 检查 Test Organization 部分内容：

   • 从 tests/README.md 读取该部分
   • 检查验证条件：
     • ✅ 描述目录结构（tests/automated/e2e、tests/automated/integration、tests/automated/unit）
     • ✅ 提及命名约定
     • ✅ 引用 Story-Level Test Task Pattern
     • ✅ 提及框架
   • 如果任一条件通过 → 内容有效
   • 如果全部未通过 → 记录警告："⚠️ tests/README.md → Test Organization 部分需要更新"

部分：运行测试

1. 自动发现测试运行命令：

   • 读取 package.json → "scripts" → "test"
   • 如果找到：
     • 提取命令值
     • 示例：
       • "jest" → 测试运行器："npm test"（运行 jest）
       • "vitest" → 测试运行器："npm test"（运行 vitest）
       • "mocha" → 测试运行器："npm test"（运行 mocha）
       • 自定义脚本 → 测试运行器："npm test"（运行 [custom]）
     • 记录日志："✓ 测试运行器：npm test（运行 [command]）"
   • 如果未找到（没有 package.json 或没有 test 脚本）：
     • 根据检测到的框架（来自步骤 3.3.1）使用默认值：
       • Jest → "npm test"
       • Vitest → "npm test"
       • Pytest → "pytest"
       • Go → "go test ./..."
     • 记录日志："⚠️ 在 package.json 中未找到 test 脚本。使用默认值 '[command]'。"

2. 自动发现覆盖率命令（可选）：

   • 检查 package.json → "scripts" 中是否有：
     • "test:coverage"
     • "coverage"
     • "test:cov"
   • 如果找到：
     • 提取命令
     • 记录日志："✓ Coverage command: npm run [script_name]"
   • 如果未找到：
     • 使用框架默认命令：
       • Jest → "npm test -- --coverage"
       • Vitest → "npm test -- --coverage"
       • Pytest → "pytest --cov=src"
       • Go → "go test -cover ./..."
     • 记录日志："✓ Coverage command: [default] (framework default)"

3. 检查 Running Tests 部分内容：

   • 从 tests/README.md 读取该部分
   • 检查验证启发式：
     • ✅ 包含测试运行器命令
     • ✅ 提及覆盖率
     • ✅ 说明如何运行特定测试
     • ✅ 包含命令示例
   • 如果任一启发式通过 → 内容有效
   • 如果全部未通过 → 记录警告："⚠️ tests/README.md → Running Tests 部分需要更新"

3.4 验证报告内容：

• 记录摘要：

  ✅ Content validation complete:
    - testing-strategy.md: [2 sections checked]
    - tests/README.md: [2 sections checked]
    - Test framework: [detected framework or "Not detected"]
    - Test structure: [automated/e2e, automated/integration, automated/unit counts or "Created placeholder"]
    - Naming convention: [pattern or "Framework default"]
    - Test runner: [command]
    - Coverage command: [command]
  

---

完整输出结构

docs/reference/guides/
└── testing-strategy.md           # Universal testing philosophy (465 lines)

tests/
└── README.md                     # Test organization + Story-Level Pattern (112 lines)

注意：实际测试目录（e2e/、integration/、unit/）会在 Story 测试任务执行期间或第 3 阶段创建；若目录缺失，也会在第 3 阶段创建。

---

关键规则

• **仅限文档：**此技能创建测试文档，而非实际测试代码
• **3 阶段流水线：**创建 → 验证结构 → 验证内容（不得跳过阶段）
• **优先自动发现：**在回退到默认值之前，先扫描测试框架和目录结构
• **幂等执行：**创建前检查是否存在；每次运行时重新验证，不重复创建
• **必须包含共享开篇约定：**两个文件都必须包含 SCOPE、元数据标记、Quick Navigation、Agent Entry 和 Maintenance

---

参考文件

• 基于风险的测试方法：references/risk_based_testing_guide.md

模板

测试策略模板：

• references/templates/testing_strategy_template.md - 通用测试理念，包含：
  • SCOPE 标签（测试理念，而非特定框架）
  • 核心理念（“测试你的代码，而非框架”）
  • 基于风险的测试策略（优先级矩阵、测试上限）
  • Story 级测试模式
  • 测试组织（tests/automated/e2e、tests/automated/integration、tests/automated/unit 的定义）
  • 隔离模式（删除数据／事务回滚／重新创建数据库）
  • 测试与不测试的内容（通用示例）
  • 测试模式（Arrange-Act-Assert、在接缝处模拟、测试数据构建器）
  • 常见问题（不稳定测试、慢速测试、测试耦合）
  • 覆盖率指南
  • 验证清单

测试 README 模板：

• references/templates/tests_readme_template.md - 测试组织，包含：
  • SCOPE 标签（仅限测试文档）
  • 概述（E2E／集成／单元测试组织）
  • 测试理念（简要说明，链接到 testing-strategy.md）
  • 测试结构（目录树）
  • Story 级测试任务模式（测试放在 Story 的最后一个任务中，而非分散各处）
  • 测试执行（项目专用命令）
  • Quick Navigation（指向 testing-strategy.md、kanban_board、指南的链接）
  • Maintenance 部分（更新触发条件、验证、最后更新日期）

验证规范：

• references/questions.md（v1.0.0）- 基于问题的验证：
  • 每个部分必须回答的问题（共 4 个部分）
  • 验证启发式（任一通过 → 有效）
  • 自动发现提示（测试框架、目录结构、命名约定）
  • MCP Ref 提示（必要时进行外部调研）

---

最佳实践

• 不要过早验证：阶段 1 创建结构，阶段 2 验证结构（不重复检查）
• 参数化验证：阶段 3 验证 2 个文件中的 4 个部分（不重复代码）
• 优先自动发现：使用默认值之前，先扫描测试框架和目录结构
• 幂等：✅ 可安全地多次运行（创建前检查是否存在，每次运行都会重新验证）
• 职责分离：创建 → 验证结构 → 验证内容
• 故事级测试任务模式：测试集中在最后一个故事任务中（测试规划器创建任务，测试执行器负责实现）
• 基于价值的测试：优先级 ≥15 的项目必须测试，每项测试都必须依据实用性标准说明理由
• 不编写测试代码：此技能仅创建文档，不创建实际测试

文档标准

• NO_CODE 规则： 测试文档描述测试策略，而非测试实现
• 技术栈适配： 框架命令必须与项目技术栈相符
• 格式优先级： 表格（测试级别、数量）> 列表 > 文本
• 共享的文档质量约定： SCOPE 标签、维护部分、占位符策略和特定技术栈的链接验证均遵循共享的文档质量约定/规则

---

先决条件

调用方：ln-100-documents-pipeline 编排器

需要：

• docs/reference/guides/ 目录（由 ln-120-reference-docs-creator 创建，若缺失则由阶段 1 创建）

创建：

• docs/reference/guides/testing-strategy.md（通用测试理念）
• tests/README.md（测试组织结构）
• 已验证的结构和内容（自动发现测试框架和目录结构）

---

返回约定

返回规范化摘要，以便 ln-100 运行一个集中的文档质量检查：

{
  "created_files": [
    "docs/reference/guides/testing-strategy.md",
    "tests/README.md"
  ],
  "skipped_files": [],
  "quality_inputs": {
    "doc_paths": [
      "docs/reference/guides/testing-strategy.md",
      "tests/README.md"
    ],
    "owners": {
      "docs/reference/guides/testing-strategy.md": "ln-140-test-docs-creator",
      "tests/README.md": "ln-140-test-docs-creator"
    }
  },
  "validation_status": "passed|passed_with_fixes|skipped"
}

---

运行时摘要产物

必须阅读： 加载 references/docs_generation_summary_contract.md

接受可选的 summaryArtifactPath。

摘要类型：

• docs-generation

必需的载荷语义：

• worker = "ln-140"
• status
• created_files
• skipped_files
• quality_inputs
• validation_status
• warnings

将摘要写入提供的产物路径，或在结构化输出中返回相同的封装。

完成定义

完成工作前，验证所有检查项：

✅ 已创建结构（阶段 1）：

• docs/reference/guides/ 目录存在
• tests/ 目录存在
• tests/manual/ 目录存在
• tests/manual/results/ 目录存在
• 已将 tests/manual/results/ 添加到 .gitignore
• testing-strategy.md 存在（已创建或原已存在）
• tests/README.md 存在（已创建或原已存在）

✅ 已验证结构（阶段 2）：

• 两个文件的前 5 行中均包含 SCOPE 标签
• testing-strategy.md 包含 “Testing Philosophy” 和 “Test Levels” 部分
• tests/README.md 包含 “Test Organization” 和 “Running Tests” 部分
• 两个文件末尾均包含维护部分
• 符合 POSIX 文件结尾要求（LF，文件末尾只有一个空行）

✅ 已验证内容（阶段 3）：

• 已检查 testing-strategy.md → Testing Philosophy 部分（提及 Risk-Based Testing）
• 已检查 testing-strategy.md → Test Usefulness Criteria 部分
• 已检查或自动发现 tests/README.md → Test Organization 部分
• 已检查或自动发现 tests/README.md → Running Tests 部分
• 已检测（如适用）并记录测试框架
• 已扫描或创建测试目录结构
• 已检测命名约定或使用默认值
• 已识别测试运行器命令或使用默认值

✅ 报告：

• 已记录阶段 1：创建摘要
• 已记录阶段 2：结构修复（如有）
• 已记录阶段 3：包含自动发现结果的内容验证摘要
• 已输出返回约定，其中包含 created_files、skipped_files、quality_inputs 和 validation_status

---

技术详情

标准：

• 故事级测试任务模式
• 基于风险的测试（优先级 ≥15，实用性标准）

语言：仅支持英语

自动发现支持：

• Node.js：jest、vitest、mocha、ava、tap、jasmine
• Python：pytest、nose2、unittest2
• Go：内置 testing 包

---

版本： 7.2.0 最后更新： 2026-01-15