Merge commit 'ac794a6a7051497ff60b947642d44f0f8c04d6c6' into lsp-server

2026-01-08 15:56:37 +08:00
parent f056b0cad1 ac794a6a70
commit 488785f08f
113 changed files with 254751 additions and 176 deletions
@@ -0,0 +1,435 @@
+# 🧪 Playbook 测试套件
+
+本目录包含 Playbook 项目的完整测试框架，用于验证脚本、模板和文档的正确性。
+
+## 📋 目录结构
+
+```txt
+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          # 文档链接有效性检查
+```
+
+## 🚀 快速开始
+
+### 本地运行所有测试
+
+```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_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](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_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**：
+
+```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_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`：
+
+```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