# PR #22189 完整报告

- 仓库：`sgl-project/sglang`
- 标题：Update test skills and guide
- 合并时间：2026-04-06 20:30
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/22189

---

# 执行摘要

本次 PR 更新了 SGLang 项目的测试编写指南，明确禁止在模块级别直接修改 `sys.modules` 来模拟依赖，因为这种操作在 pytest 导入所有测试文件时会导致跨测试污染。文档建议使用 `patch.dict` 作为类装饰器或配合 `start`/`stop` 方法进行清理，确保测试隔离性。这是对测试开发规范的重要澄清，影响所有编写单元测试的开发者，但无代码变更，风险较低。

# 功能与动机

**为什么做**：根据 review 评论，现有文档中关于使用 `setUpModule` 配合 `patch.dict` 的建议存在缺陷：1) `setUpModule` 在模块导入后执行，如果依赖在顶层导入时触发，补丁会太晚；2) 需要显式清理以避免污染。本次修改旨在提供更安全、更可靠的测试依赖模拟方法，防止跨测试污染问题。

# 实现拆解

修改了两个关键文档文件：

| 文件路径 | 变更内容 | 影响 |
|----------|----------|------|
| `.claude/skills/write-sglang-test/SKILL.md` | 在测试编写指南中，将原来的建议扩展为明确禁止模块级 `sys.modules` 修改，推荐使用 `patch.dict` 作为类装饰器或配合 `start`/`stop` 方法。 | 定义了测试开发的最佳实践 |
| `test/registered/unit/README.md` | 补充说明不要直接在模块级别修改 `sys.modules`，因为 pytest 会在运行前导入所有测试文件，这种修改会污染整个进程。建议使用 `patch.dict("sys.modules", ...)` 并确保正确清理。 | 提供了单元测试实施的具体指南 |

关键代码逻辑更新：
- 在 SKILL.md 中，将“See `test/registered/unit/README.md` for details and examples.”扩展为“Do not modify `sys.modules` at module level — use `patch.dict` (as a class decorator or with `start`/`stop`) to ensure cleanup and avoid cross-test pollution.”
- 在 README.md 中，新增段落强调避免模块级 `sys.modules` 修改，并推荐 `patch.dict` 配合清理。

# 评论区精华

review 中只有一个评论者 `gemini-code-assist[bot]` 提供了技术反馈：

> “The recommendation to use `setUpModule` with `patch.dict` has two significant drawbacks:
1. **Import Timing**: `setUpModule` runs *after* the module is imported. If the test file has top-level imports that trigger the dependency, the patch will be applied too late. 2. **Cleanup**: `patch.dict` inside `setUpModule` requires explicit `start()` and `stop()` (or `addModuleCleanup`) to prevent the very pollution this rule aims to avoid.”

评论者建议使用 `patch.dict` 作为 **类装饰器 **是更好的替代方案。PR 作者接受了建议，更新了文档以明确禁止模块级 `sys.modules` 修改。

未解决的疑虑：评论者询问现有 `maybe_stub_sgl_kernel()` 模块级调用是否仍是推荐做法，但未得到明确回答。

# 风险与影响

**风险分析**：
1. 文档变更风险：新指南可能过于严格，影响现有测试编写模式，但这是最佳实践的澄清。
2. 理解风险：开发者可能误解新指南，错误应用 `patch.dict` 导致测试失败。
3. 兼容性风险：现有测试中可能仍有模块级 `sys.modules` 修改，但本次 PR 只更新文档，不修改代码，因此不会直接影响现有测试运行。

**影响分析**：
- 对用户：无直接影响，这是内部开发文档更新。
- 对系统：无代码变更，不影响运行时行为。
- 对团队：所有编写 SGLang 测试的开发者需要遵循新指南，避免使用模块级 `sys.modules` 修改，这能提高测试的隔离性和可靠性。影响程度中等，涉及测试编写规范的变更。

# 关联脉络

与近期历史 PR 的关联：
1. **PR #22176**（Fix ut module importing）：同样涉及测试导入问题，重构了测试文件的导入机制以避免 CPU-only 环境依赖问题。本次文档更新可视为对该 PR 实践的规范化。
2. **PR #21400**和 **#21399**（添加 CPU-only 单元测试）：这些添加单元测试的 PR 可能受到本次文档更新的影响，未来编写类似测试需要遵循新指南。

**演进趋势**：SGLang 项目近期持续加强测试基础设施，包括添加单元测试（如 #21400、#21399）、修复测试导入问题（#22176）以及本次规范化测试编写指南。这表明团队在提升测试覆盖率和质量方面投入资源，确保代码可靠性。本次 PR 是这一趋势的延续，通过文档更新统一测试开发实践。