# PR #22308 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[CI] Add pre-commit hook to validate test/registered/ files have CI registry
- 合并时间：2026-04-09 06:59
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/22308

---

# 执行摘要

本 PR 新增了一个 pre-commit 钩子，用于自动验证 `test/registered/` 目录下的 Python 测试文件是否包含必要的 CI 注册调用（如 `register_cuda_ci`）。此举旨在预防因测试文件缺失注册而导致的 CI 中断问题，通过将检查提前到提交阶段，提升开发效率和 CI 稳定性。变更涉及两个文件：新增验证脚本和更新 pre-commit 配置，风险较低，主要影响开发团队的工作流程。

# 功能与动机

根据 PR 描述，`test/registered/` 目录下的文件由 `run_suite.py` 的 `collect_tests()` 收集，要求每个文件必须包含 CI 注册调用。缺失注册会导致 CI 失败并抛出 `ValueError: No CI registry found`。此前 #22298 已修复了一个因文件放置在 `test/registered/` 但未注册而中断所有 CI 套件的案例。本 PR 的动机是通过 pre-commit 钩子在提交时捕获此类错误，避免等待 CI 运行时失败，从而提高开发效率和 CI 可靠性。

# 实现拆解

实现分为两个关键部分：

1. **pre-commit 配置更新**：在 `.pre-commit-config.yaml` 中添加新的钩子 `check-registered-tests`，配置如下：
   ```yaml
   - id: check-registered-tests
     name: check registered tests have CI registry
     entry: python3 scripts/ci/check_registered_tests.py
     language: system
     files: ^test/registered/.*\.py$
     pass_filenames: false
   ```
 该钩子针对 `test/registered/` 目录下的所有 `.py` 文件运行验证脚本。

2. **验证脚本实现**：新增 `scripts/ci/check_registered_tests.py`，核心逻辑包括：
 - 导入 `ci_register.py` 中的 `ut_parse_one_file()` 函数，复用其 AST 解析逻辑以匹配 `run_suite.py` 的行为。
 - 遍历 `test/registered/` 目录下的 Python 文件，跳过 `conftest.py` 和 `__init__.py`。
 - 检查每个文件是否包含 CI 注册调用，若无则报错并提示将手动测试移至 `test/manual/`。
 - 脚本返回非零状态码以阻止提交，确保问题在早期被发现。

# 评论区精华

由于 review 评论为空，没有公开的讨论或争议点。但从提交历史可见，作者通过临时添加错误文件验证了钩子的有效性，并在确认后恢复，体现了测试的严谨性。

# 风险与影响

**风险分析**：
- 脚本依赖 `ci_register.py` 的 `ut_parse_one_file()` 函数，若该函数逻辑变更或存在 bug，可能导致误报或漏报。
- 脚本仅检查文件是否包含注册调用，未验证注册调用的正确性（如参数有效性），潜在 CI 问题可能仍存在。
- 新增 pre-commit 钩子可能轻微增加提交开销，但检查范围有限，影响可忽略。

**影响分析**：
- 对用户无直接影响。
- 对开发团队：显著提高 CI 稳定性，减少因注册缺失导致的调试时间；增强开发流程，通过早期验证预防问题。
- 对系统性能无显著影响。

# 关联脉络

本 PR 与近期历史 PR 关联如下：
- **#22298**：PR body 中提及该 Issue 修复了 test/registered/ 目录下文件缺失注册导致 CI 中断的案例，是本 PR 的直接动机来源。
 - **#22270**（Refactor auto benchmark unit tests and fix CI bug）：涉及 test/registered/ 目录的重构和 CI 修复，与本 PR 在测试基础设施和 CI 稳定性方面有共同关注点。

整体来看，本 PR 是 sglang 仓库持续优化 CI 和测试基础设施的一部分，通过自动化检查提升代码质量和开发效率，符合近期多个 PR（如 #22395、#22391）对 CI 流程的改进趋势。