playbook/tests

🧪 Playbook 测试套件

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

📋 目录结构

tests/
├── README.md                       # 本文件：测试文档
├── scripts/                        # Shell 脚本测试（bats）
│   ├── test_sync_standards.bats   # sync_standards.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 模板验证
└── integration/                    # 集成测试
    └── check_doc_links.sh          # 文档链接有效性检查

🚀 快速开始

本地运行所有测试

# 进入 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_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

# 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 框架测试 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_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 说明文档
  • 包含使用说明

3. 集成测试 (integration/)

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

check_doc_links.sh

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

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

🔧 本地开发

安装测试依赖

Ubuntu/Debian：

# 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：

# bats-core
brew install bats-core

# Python 工具
pip3 install toml tomli jsonschema yamllint

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

# YAML 验证
pip3 install yamllint

运行单个测试

# Shell 脚本测试
cd tests/scripts
bats test_sync_standards.bats --tap  # TAP 格式输出
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

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

添加新测试

添加新的 bats 测试

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

#!/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 测试失败

# 使用 --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

文档链接检查失败

查看详细报告：

cat /tmp/doc_links_report.txt

🤝 贡献指南

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

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

📖 相关文档

• 开发规范索引
• 提交信息规范
• Gitea Actions 文档
• bats-core 文档

❓ 常见问题

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

A: 可能原因：

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

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

Q: 如何跳过某些测试？

A: bats 支持 skip 命令：

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

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

A: 建议：

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

---

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