playbook/tests/README.md

# 🧪 Playbook 测试套件

本目录包含 Playbook 项目的完整测试框架，用于验证脚本、模板和文档的正确性。

## 📋 目录结构

```txt
tests/
├── README.md                       # 本文件：测试文档
├── scripts/                        # Shell 脚本测试（bats）
│   ├── test_sync_standards.bats   # sync_standards.sh 测试
│   ├── test_sync_templates.bats   # sync_templates.sh 测试
│   ├── test_vendor_playbook.bats  # vendor_playbook.sh 测试
│   └── test_install_codex_skills.bats  # install_codex_skills.sh 测试
├── templates/                      # 模板验证测试
│   ├── validate_python_templates.sh    # Python 模板验证
│   ├── validate_cpp_templates.sh       # C++ 模板验证
│   ├── validate_ci_templates.sh        # CI 模板验证
│   └── validate_project_templates.sh   # 项目模板验证
└── integration/                    # 集成测试
    └── check_doc_links.sh          # 文档链接有效性检查
```

## 🚀 快速开始

### 本地运行所有测试

```bash
# 进入 playbook 根目录
cd /path/to/playbook

# 1. 运行 Shell 脚本测试（需要 bats）
sudo apt-get install bats  # Ubuntu/Debian
cd tests/scripts
bats test_sync_standards.bats
bats test_sync_templates.bats
bats test_vendor_playbook.bats
bats test_install_codex_skills.bats

# 2. 运行模板验证测试
cd tests/templates
sh validate_python_templates.sh
sh validate_cpp_templates.sh
sh validate_ci_templates.sh
sh validate_project_templates.sh

# 3. 运行集成测试
cd tests/integration
sh check_doc_links.sh
```

### CI 自动化测试

测试套件通过 Gitea Actions 自动运行（见 `.gitea/workflows/test.yml`）：

- **触发时机**：
  - 推送到 `main` 分支
  - Pull Request 到 `main` 分支
  - 手动触发（workflow_dispatch）
- **运行平台**：ubuntu-22.04
- **并行策略**：使用 matrix 策略并行运行多个测试组

## 📚 测试详解

### 1. Shell 脚本测试 (scripts/)

使用 [bats-core](https://github.com/bats-core/bats-core) 框架测试 shell 脚本。

#### test_sync_standards.bats

测试 `scripts/sync_standards.sh` 脚本的功能：

- **基础功能**：
  - 脚本存在且可执行
  - 无参数时默认同步 tsl（已有 `.agents/<lang>/` 则自动识别）
  - 单语言同步（tsl/cpp）
  - 多语言同步（tsl cpp）
- **.gitattributes 同步**：
  - 默认模式追加缺失规则
  - 保留现有内容
  - 更新已存在的 managed block
- **AGENTS.md 处理**：
  - 不存在时自动创建
  - 已存在时不覆盖
- **备份功能**：
  - 更新前创建备份
- **错误处理**：
  - 未找到 playbook 快照时报错
  - 无效语言参数时报错
- **环境变量**：
  - `SYNC_GITATTR_MODE` 配置
- **幂等性**：
  - 多次执行结果一致

#### test_sync_templates.bats

测试 `scripts/sync_templates.sh` 脚本的功能：

- **基础同步**：
  - 同步 memory-bank/ 与 docs/prompts/
  - 创建 AGENTS.md / AGENT_RULES.md / TODO.md / CONFIRM.md
- **占位符替换**：
  - `{{PROJECT_NAME}}` 与 `{{DATE}}`
- **目录覆盖策略**：
  - 无 `-force` 时不覆盖已有目录
  - `-force` 时覆盖并备份
- **AGENTS.md 更新**：
  - `-full` 更新 framework 区块

#### test_vendor_playbook.bats

测试 `scripts/vendor_playbook.sh` 脚本的功能：

- **基础功能**：
  - 单语言 vendoring
  - 多语言 vendoring
- **自动同步**：
  - 自动执行 sync_standards
- **SOURCE.md 生成**：
  - 包含来源信息
  - 包含 commit hash
  - 包含时间戳
- **裁剪功能**：
  - 仅包含指定语言
  - 始终包含 common 目录
  - 包含对应模板文件
- **目标目录处理**：
  - 已存在时覆盖更新
  - 创建必要的父目录
- **错误处理**：
  - 目标目录不存在时报错
  - 无效语言参数时报错
- **完整性验证**：
  - 所有必要文件已复制
  - 脚本可执行
- **幂等性**：
  - 多次 vendor 结果一致

#### test_install_codex_skills.bats

测试 `scripts/install_codex_skills.sh` 脚本的功能：

- **基础功能**：
  - 脚本存在且可执行
- **安装功能**：
  - 创建 skills 目录
  - 复制 skill 目录（包含 `SKILL.md`）
  - 支持指定单个 skill 安装
  - 同名目录安装前创建备份
- **错误处理**：
  - 指定不存在的 skill 报错
- **幂等性**：
  - 多次安装结果一致

### 2. 模板验证测试 (templates/)

验证项目模板文件的正确性和完整性。

#### validate_python_templates.sh

验证 `templates/python/` 目录下的 Python 模板：

- **pyproject.toml**：
  - 文件存在
  - TOML 语法正确
  - 包含必要配置节（tool.black, tool.isort, tool.pytest.ini_options）
  - black line-length 配置正确
  - isort profile 配置正确
- **.flake8**：
  - 文件存在
  - 包含 [flake8] 配置
  - 配置了 max-line-length
  - 配置了错误忽略规则
- **.pylintrc**：
  - 文件存在
  - 包含必要配置节（MASTER, MESSAGES CONTROL, FORMAT）
  - 配置了 max-line-length
- **.pre-commit-config.yaml**：
  - 文件存在
  - YAML 语法正确
  - 包含 repos 配置
  - 配置了常用 hooks（black, isort, flake8）
- **.editorconfig**：
  - 文件存在
  - 包含 root = true
  - 包含 Python 文件配置
- **.vscode/settings.json**：
  - 文件存在
  - JSON 语法正确
  - 包含 Python 配置

#### validate_cpp_templates.sh

验证 `templates/cpp/` 目录下的 C++ 模板：

- **CMakeLists.txt**：
  - 文件存在
  - CMake 基础语法正确
  - 配置了 C++23 标准
  - 启用了 C++ Modules 扫描（可选）
  - 启用了 import std; 支持（可选）
  - 启用了编译命令导出（用于 clangd）
- **.clang-format**：
  - 文件存在
  - YAML 语法正确
  - 配置了 Language: Cpp
  - 基于某个风格（BasedOnStyle）
  - 配置了 C++ 标准
  - 配置了缩进宽度
- **.clangd**：
  - 文件存在
  - YAML 语法正确
  - 包含 CompileFlags 配置
  - 配置了 -std=c++23
  - 配置了 CompilationDatabase 路径
  - 配置了 Index 选项
- **conanfile.txt**：
  - 文件存在
  - 包含 [requires] 配置（可选）
  - 包含 [generators] 配置
  - 配置了 CMakeDeps 生成器
  - 配置了 CMakeToolchain 生成器
  - 包含 [options] 配置
- **CMakeUserPresets.json**：
  - 文件存在
  - JSON 语法正确
  - 包含 version 字段
  - 包含 configurePresets
  - 包含 buildPresets

#### validate_ci_templates.sh

验证 `templates/ci/` 目录下的 CI 模板：

- **Gitea/GitHub workflow 文件**：
  - 文件存在
  - YAML 语法正确
  - 包含必要字段（name, on, jobs, runs-on, steps）
  - 包含中文注释（符合项目风格）
  - 包含配置区域标记
  - 包含环境变量配置
- **特定 workflow 模板**：
  - standards-check.yml：包含格式化检查和 lint 检查
  - test.yml：包含测试步骤和测试矩阵
- **文档**：
  - 包含 README 说明文档
  - 包含使用说明

#### validate_project_templates.sh

验证项目通用模板：

- **核心模板**：
  - `templates/AGENTS.template.md`
  - `templates/AGENT_RULES.template.md`
  - `templates/README.md`
- **memory-bank 模板**：
  - 项目定位/技术栈/架构/进度/决策/实施计划
- **prompts 模板**：
  - `prompts/README.md`
  - `prompts/system/agent-behavior.template.md`
  - `prompts/coding/clarify.template.md`
  - `prompts/coding/verify.template.md`

### 3. 集成测试 (integration/)

端到端测试，验证整体功能。

#### check_doc_links.sh

检查所有 Markdown 文档中的链接有效性：

- **扫描范围**：
  - 所有 `*.md` 文件（排除 `*.template.md`）
  - 排除 node_modules, .git, build, dist 等目录
- **链接类型**：
  - Markdown 链接：`[text](link)`
  - 引用链接：`[text]: link`
- **验证逻辑**：
  - 检查相对路径链接是否指向存在的文件
  - 跳过外部链接（http/https）
  - 跳过 mailto 链接
  - 跳过代码块与行内代码中的链接样式文本
  - 支持锚点（但只验证文件存在性）
- **报告内容**：
  - 总链接数
  - 有效链接数
  - 跳过链接数（外部/mailto）
  - 断开链接详情（文件、行号、链接、目标路径）

## 🔧 本地开发

### 安装测试依赖

**Ubuntu/Debian**：

```bash
# bats-core (Shell 脚本测试)
sudo apt-get update
sudo apt-get install bats

# Python 工具（模板验证）
pip install toml tomli jsonschema yamllint

# C++ 工具（模板验证，可选）
sudo apt-get install cmake clang-format

# YAML 验证
pip install yamllint
```

**macOS**：

```bash
# bats-core
brew install bats-core

# Python 工具
pip3 install toml tomli jsonschema yamllint

# C++ 工具（可选）
brew install cmake clang-format

# YAML 验证
pip3 install yamllint
```

### 运行单个测试

```bash
# Shell 脚本测试
cd tests/scripts
bats test_sync_standards.bats --tap  # TAP 格式输出
bats test_sync_templates.bats
bats test_vendor_playbook.bats --formatter junit  # JUnit 格式

# 模板验证测试
cd tests/templates
sh validate_python_templates.sh
sh validate_cpp_templates.sh
sh validate_ci_templates.sh
sh validate_project_templates.sh

# 集成测试
cd tests/integration
sh check_doc_links.sh
```

### 添加新测试

#### 添加新的 bats 测试

在 `tests/scripts/` 创建新文件 `test_<script_name>.bats`：

```bash
#!/usr/bin/env bats

setup() {
    # 测试前准备
    export TEST_DIR="$(mktemp -d)"
}

teardown() {
    # 测试后清理
    rm -rf "$TEST_DIR"
}

@test "描述测试内容" {
    # 测试代码
    [ -f "some_file" ]
}
```

#### 添加新的模板验证

在 `tests/templates/` 创建新文件 `validate_<template_type>_templates.sh`，参考现有脚本结构。

#### 添加新的集成测试

在 `tests/integration/` 创建新脚本，确保：

1. 使用 `set -eu` 启用错误检测
2. 输出清晰的测试进度
3. 生成详细的报告文件
4. 返回正确的退出码（0 = 成功，非 0 = 失败）

## 📊 测试覆盖率目标

- **Shell 脚本测试**：目标覆盖率 ≥ 80%
- **模板验证测试**：目标通过率 = 100%
- **集成测试**：目标通过率 = 100%
- **文档链接有效性**：目标有效率 = 100%

## 🐛 故障排查

### bats 测试失败

```bash
# 使用 --verbose 查看详细输出
bats --verbose test_sync_standards.bats

# 使用 --trace 查看执行跟踪
bats --trace test_sync_standards.bats
```

### 模板验证失败

验证脚本会生成详细报告文件：

- `tests/templates/python_validation_report.txt`
- `tests/templates/cpp_validation_report.txt`
- `tests/templates/ci_validation_report.txt`

### 文档链接检查失败

查看详细报告：

```bash
cat /tmp/doc_links_report.txt
```

## 🤝 贡献指南

添加新功能时，请同步更新相应的测试：

1. **修改脚本**（`scripts/`）→ 更新对应的 `.bats` 测试
2. **修改模板**（`templates/`）→ 更新对应的验证脚本
3. **修改文档**（`docs/`, `.agents/`）→ 运行文档链接检查
4. **修改 CI workflow**（`.gitea/workflows/`）→ 验证 YAML 语法

## 📖 相关文档

- [开发规范索引](../docs/index.md)
- [提交信息规范](../docs/common/commit_message.md)
- [Gitea Actions 文档](https://docs.gitea.com/usage/actions/overview)
- [bats-core 文档](https://bats-core.readthedocs.io/)

## ❓ 常见问题

### Q: 为什么测试在 CI 通过，但本地失败？

A: 可能原因：

- 环境差异（工具版本、路径）
- 权限问题
- Git 配置差异

建议使用 Docker 容器复现 CI 环境。

### Q: 如何跳过某些测试？

A: bats 支持 `skip` 命令：

```bash
@test "某个测试" {
    skip "原因说明"
    # 测试代码
}
```

### Q: 测试运行很慢，如何加速？

A: 建议：

1. 使用 bats 的 `--jobs` 参数并行运行
2. 只运行变更相关的测试
3. 使用 CI 的缓存机制

---

**测试套件维护者**: Playbook 团队
**最后更新**: 2026-01-07