mirrors / skillhub-159-test-suite-architect

项目文件夹

文件

T

wehub-skill-sync 430874e39e chore: import zh skill test-suite-architect

2026-07-13 21:36:54 +08:00

9.9 KiB

原始文件 永久链接 Blame 文件历史

基准真相原则 —— 防止文档同步问题

目的：防止因文档/跟踪文件不匹配导致的测试套件完整性问题。

经验教训：CCPM 项目发现 CSV 与文档之间的一致性率仅为 3.2%（93 个测试 ID 中只有 3 个正确匹配）。

问题

常见的反模式

项目往往拥有多个真相来源：

测试用例文档（例如 02-CLI-TEST-CASES.md）
执行跟踪 CSV（例如 TEST-EXECUTION-TRACKING.csv）
Bug 跟踪电子表格
测试自动化代码

出问题的环节：

文档更新了 → CSV 未更新
CSV 从旧测试列表中自动生成 → 文档独立定稿
基于 CSV 执行测试 → 执行了错误的测试步骤
Bug 报告引用 CSV ID → 无法追溯到正确的测试

CCPM 的真实案例

CSV TC-CLI-012："安装不存在的技能"

步骤：运行 ccpm install this-skill-does-not-exist-12345
预期结果：明确的错误信息

文档 TC-CLI-012："安装已安装的技能"

步骤：运行 ccpm install cloudflare-troubleshooting（已安装）
预期结果：带有 --force 提示的警告信息

结果：完全不同的测试！QA 工程师可能执行了错误的测试并报告了不正确的结果。

基准真相原则

规则一：单一真相来源

将某一个文件声明为测试规范的权威来源：

✅ 正确：
基准真相：02-CLI-TEST-CASES.md（详细的测试规范）
辅助文件：TEST-EXECUTION-TRACKING.csv（仅限执行状态）

❌ 错误：
CSV 和文档都包含测试步骤（分歧不可避免）

规则二：清晰的角色分离

文件类型	用途	包含内容	更新时机
测试用例文档	规范	前置条件、步骤、预期结果、通过/失败标准	测试设计变更时
跟踪 CSV	执行跟踪	状态、结果、Bug ID、执行日期、备注	每次测试执行后
Bug 报告	失败记录	复现步骤、环境、严重等级、解决方案	测试失败时

规则三：明确引用

在指令中始终指明使用哪个文件：

好：

执行测试用例 TC-CLI-042：
1. 从 02-CLI-TEST-CASES.md（第 15-16 页）读取完整的测试规范
2. 严格按文档步骤执行
3. 在 TEST-EXECUTION-TRACKING.csv 的 TC-CLI-042 行中更新结果

差：

执行测试用例 TC-CLI-042（未引用源文档）

预防策略

策略一：自动化 ID 校验

脚本：validate_test_ids.py（在项目中生成）

#!/usr/bin/env python3
"""校验文档与 CSV 之间的测试 ID"""

import csv
import re
from pathlib import Path

def extract_doc_ids(doc_path):
    """从 Markdown 文档中提取所有 TC-XXX-YYY 格式的 ID"""
    with open(doc_path, 'r') as f:
        content = f.read()
    pattern = r'TC-[A-Z]+-\d{3}'
    return set(re.findall(pattern, content))

def extract_csv_ids(csv_path):
    """从 CSV 中提取所有测试用例 ID"""
    with open(csv_path, 'r') as f:
        reader = csv.DictReader(f)
        return set(row['Test Case ID'] for row in reader if row['Test Case ID'])

def validate_sync(doc_path, csv_path):
    """检查文档与 CSV 之间的一致性"""
    doc_ids = extract_doc_ids(doc_path)
    csv_ids = extract_csv_ids(csv_path)

    matching = doc_ids & csv_ids
    csv_only = csv_ids - doc_ids
    doc_only = doc_ids - csv_ids

    consistency_rate = len(matching) / len(csv_ids) * 100 if csv_ids else 0

    print(f"\n{'='*60}")
    print(f"测试 ID 校验报告")
    print(f"{'='*60}\n")
    print(f"✅ 匹配的 ID：     {len(matching)}")
    print(f"⚠️  仅 CSV 存在的 ID：     {len(csv_only)}")
    print(f"⚠️  仅文档存在的 ID：     {len(doc_only)}")
    print(f"\n📊 一致性率：{consistency_rate:.1f}%\n")

    if consistency_rate < 100:
        print(f"❌ 检测到同步问题！\n")
        if csv_only:
            print(f"CSV 中存在但文档中不存在的 ID：{sorted(csv_only)[:5]}")
        if doc_only:
            print(f"文档中存在但 CSV 中不存在的 ID：{sorted(doc_only)[:5]}")
    else:
        print(f"✅ 完美同步！\n")

    return consistency_rate >= 95

if __name__ == "__main__":
    import sys
    if len(sys.argv) < 3:
        print("用法：python validate_test_ids.py <文档路径> <CSV 路径>")
        sys.exit(1)

    doc_path = sys.argv[1]
    csv_path = sys.argv[2]

    valid = validate_sync(doc_path, csv_path)
    sys.exit(0 if valid else 1)

用法：

python scripts/validate_test_ids.py \
  tests/docs/02-CLI-TEST-CASES.md \
  tests/docs/templates/TEST-EXECUTION-TRACKING.csv

# 输出：
# ============================================================
# 测试 ID 校验报告
# ============================================================
#
# ✅ 匹配的 ID：     3
# ⚠️  仅 CSV 存在的 ID：     90
# ⚠️  仅文档存在的 ID：     0
#
# 📊 一致性率：3.2%
#
# ❌ 检测到同步问题！

策略二：ID 映射文档

检测到不匹配时，创建桥接文档：

文件：tests/docs/TEST-ID-MAPPING.md

内容：

# 测试 ID 映射 —— CSV 与文档

## 基准真相
**官方来源**：02-CLI-TEST-CASES.md
**跟踪文件**：TEST-EXECUTION-TRACKING.csv（仅限执行跟踪）

## ID 映射表
| CSV ID | 文档 ID | 测试名称 | 匹配状态 |
|--------|--------|-----------|--------------|
| TC-CLI-001 | TC-CLI-001 | 按名称安装技能 | ✅ 匹配 |
| TC-CLI-012 | TC-CLI-008 | 安装不存在的技能 | ❌ 不匹配 |

策略三：CSV 使用指南

为 QA 工程师创建明确的说明文档：

文件：tests/docs/templates/CSV-USAGE-GUIDE.md

内容：

# TEST-EXECUTION-TRACKING.csv 使用指南

## ✅ 正确用法

1. **始终使用测试用例文档**作为以下内容的权威来源：
   - 测试步骤
   - 预期结果
   - 前置条件

2. **此 CSV 仅用于**：
   - 跟踪执行状态
   - 记录结果（通过/失败）
   - 链接到 Bug 报告

## ❌ 不要依赖 CSV 获取测试规范

恢复工作流

当发现同步问题时：

第一步：评估严重程度

# 运行 ID 校验脚本
python scripts/validate_test_ids.py <文档> <CSV>

# 一致性率：
#   100%：   ✅ 无需操作
#   90-99%： ⚠️  需要小幅修复
#   50-89%： 🔴 需要重大同步
#   <50%：   🚨 严重 —— 重新生成 CSV

第二步：创建桥接文档

# 如果一致性率 < 100%，创建：
1. TEST-ID-MAPPING.md（映射 CSV → 文档 ID）
2. CSV-USAGE-GUIDE.md（指导 QA 工程师）

第三步：通知团队

主题：[紧急] 测试套件同步问题 —— 测试前请先阅读

团队，

我们发现 CSV 与文档之间存在测试 ID 不匹配：
- 一致性率：3.2%（93 个测试中仅 3 个匹配）
- 影响：基于 CSV 执行的测试可能使用错误的步骤
- 需执行的操作：继续测试前请先阅读 CSV-USAGE-GUIDE.md

基准真相：02-CLI-TEST-CASES.md（始终信任此文件）
仅限跟踪：TEST-EXECUTION-TRACKING.csv

桥接文档：TEST-ID-MAPPING.md（映射 ID）

第四步：重新验证已执行的测试

修复前已执行的测试可能需要重新验证：
- TC-CLI-001~003：✅ 正确（ID 匹配）
- TC-CLI-029：⚠️  对照文档 TC-CLI-029 进行验证
- TC-CLI-037：⚠️  对照文档 TC-CLI-037 进行验证

第五步：长期修复

选项 A：保持分离（在活跃测试期间推荐）

CSV = 仅限执行跟踪
文档 = 测试规范
映射文档桥接差距

选项 B：从文档重新生成 CSV（测试后）

风险：执行历史丢失
好处：完美同步
时间节点：当前测试周期结束后

最佳实践

✅ 应做事项

在项目 README 中提前声明基准真相
分离关注点：规范 vs. 跟踪 vs. Bug
定期校验 ID（每周或在重要里程碑前）
在映射文件中记录偏差
对 QA 团队进行基准真相原则培训

❌ 不应做事项

❌ 在多个文件中重复测试步骤
❌ 未经校验自动生成跟踪文件
❌ 仅凭 CSV 执行测试
❌ 认为"只是跟踪文件"——ID 很重要！
❌ 忽视微小的不匹配（3% 很快会变成 50%）

QA 项目设置清单

使用 init_qa_project.py 时，请确保：

在 README 中声明了基准真相
CSV 仅包含 ID 和跟踪字段（无详细步骤）
测试用例文档在 CSV 生成前已完备
ID 校验脚本已添加到项目
CSV 使用指南已包含在 templates/ 目录下
QA 工程师已接受关于应信任哪个文件的培训

与 qa-expert 技能的集成

使用 qa-expert 初始化项目时：

python scripts/init_qa_project.py my-app ./

# 这将创建：
tests/docs/
  ├── README.md                        （声明基准真相）
  ├── 02-CLI-TEST-CASES.md            （权威规范）
  ├── TEST-ID-MAPPING.md              （如果需要）
  └── templates/
      ├── TEST-EXECUTION-TRACKING.csv （仅限跟踪）
      ├── CSV-USAGE-GUIDE.md          （使用说明）
      └── validate_test_ids.py        （校验脚本）

成功标准

当满足以下条件时，你的测试套件具有良好的完整性：

✅ ID 一致性率 ≥ 95%
✅ QA 工程师知道应信任哪个文件
✅ 跟踪 CSV 仅包含状态（不含步骤）
✅ 校验脚本每周运行
✅ 团队已接受基准真相原则培训

警示信号：

🚩 多个文件包含测试步骤
🚩 CSV 中的测试名称与文档不同
🚩 QA 工程师"偏爱"CSV 而非文档
🚩 无人知道哪个文件是权威来源
🚩 测试 ID 随时间推移产生分歧

文档版本：1.0 创建日期：2025-11-10 基于：CCPM 测试套件完整性事件（3.2% 一致性率） 优先级：🔴 P0（对测试套件质量至关重要）

9.9 KiB 原始文件 永久链接 Blame 文件历史 Unescape Escape