# PR #31817 完整报告

- 仓库：`sgl-project/sglang`
- 标题：test: publish resolved config in unit fixtures for the namespace API
- 合并时间：2026-07-22 16:19
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/31817

---

# 执行摘要

- 一句话：测试夹具改为发布真实解析配置
- 推荐动作：值得阅读以理解结构化配置 API 的测试策略和命名空间概念。关注 `test_runtime_context.py` 中如何通过 `NS` 装饰器和 `get_memory()` 访问器验证配置写入的正确性。

# 功能与动机

PR body 明确指出这是结构化 RuntimeContext 配置 API 的一部分，目标是通过域名空间（如 `get_model()`/`get_serving()`/`get_exec()` 等）读取解析后的配置。为支持这一新 API，单元测试需要发布真实的已解析 ServerArgs 而非 mock，以确保命名空间袋的正确性。

# 实现拆解

1. **更新 `test_runtime_context.py` 中的导入语句**：添加 `NS`（命名空间指示器）的导入，并导入新的 `get_memory` 访问器。
2. **修改 `_FakeResolvedArgs` 类的字段注解**：为 `page_size` 和 `sampling_backend` 添加 `NS(...)` 装饰器，指明它们所属的命名空间（如 `memory`、`exec.kernel`），以匹配新的配置袋发布机制。
3. **重写并重命名测试方法**：将 `test_tokenizer_alias_is_same_function` 改为 `test_tokenizer_and_scheduler_setters_are_distinct_role_shims`，断言两个 setter 不再是同一函数，以验证 per-role 的发布逻辑。将 `test_declare_load_time_override_writes_through` 改为 `test_declare_load_time_override_writes_the_bag`，验证声明写入命名空间袋（如 `get_memory().page_size`）而非直接修改 `server_args` 对象。同时更新 `test_declare_load_time_override_records_provenance` 测试以使用命名空间访问。
4. **更新 `test_legacy_global_ratchet.py` 中的棘轮基线**：将 `set_global_server_args_for_*` 计数从 5 降至 4，反映 shim 调用点的减少。

关键文件：
- `test/registered/unit/test_runtime_context.py`（模块 运行时上下文；类别 test；类型 test-coverage；符号 test_tokenizer_alias_is_same_function, test_tokenizer_and_scheduler_setters_are_distinct_role_shims, test_declare_load_time_override_writes_through, test_declare_load_time_override_writes_the_bag）: 核心测试文件，验证新的命名空间配置 API 是否正确工作。包含对 tokenizer/scheduler setter 独立性的断言、命名空间袋写入验证以及负载时覆盖的记录验证。
- `test/registered/unit/test_legacy_global_ratchet.py`（模块 遗留门控；类别 test；类型 test-coverage）: 棘轮测试，确保遗留 setter 的调用点不会增加。本 PR 将其基线从 5 降至 4，反映迁移进展。

关键符号：test_tokenizer_and_scheduler_setters_are_distinct_role_shims, test_declare_load_time_override_writes_the_bag, test_declare_load_time_override_records_provenance

## 关键源码片段

### `test/registered/unit/test_runtime_context.py`

核心测试文件，验证新的命名空间配置 API 是否正确工作。包含对 tokenizer/scheduler setter 独立性的断言、命名空间袋写入验证以及负载时覆盖的记录验证。

```python
# _FakeResolvedArgs 是用于测试的可发布 fixture，
# 其字段通过 NS("...") 指定所属命名空间，
# 使 declare_load_time_override 写入正确的袋。
class _FakeResolvedArgs:
    page_size: A[int | None, Arg(help="p", resolvable=True), NS("memory")] = None
    sampling_backend: A[
        str | None, Arg(help="s", resolvable=True), NS("exec.kernel")
    ] = None
    _resolved_overrides: list = dataclasses.field(default_factory=list)

# 验证负载时覆盖写入命名空间袋而非 server_args 对象。
def test_declare_load_time_override_writes_the_bag(self):
    from sglang.srt.arg_groups.overrides import declare_load_time_override
    args = self._publish(page_size=1)
    declare_load_time_override("model.load_time", {"page_size": 64})
    # 声明写入 memory 袋，server_args 中保持原始值不变。
    self.assertEqual(get_memory().page_size, 64)
    self.assertEqual(args.page_size, 1)

```

# 评论区精华

机器人 Codex 审查提出了多个建议，包括：避免在只读 grammar fixture 中直接赋值（`test/registered/unit/constrained/test_grammar_manager.py`）、发布负载均衡方法配置（`test/registered/unit/disaggregation/test_register_to_bootstrap.py`）、保留类级运行时配置（`test/registered/unit/conftest.py`）、保留 draft 加载格式（`python/sglang/srt/managers/scheduler.py`）、保持适应性步骤计数对 graph runner 可见（`python/sglang/srt/speculative/eagle_worker_v2.py`）等。这些建议虽未直接关联本 PR 的测试变更，但反映了整体配置迁移对下游的影响。

- 将测试断言从 server_args 写入改为命名空间袋写入 (design): 测试已更新以反映新的设计：负载时覆盖写入命名空间袋，server_args 保持为只读记录。
- tokenizer 和 scheduler setter 不再互为别名 (design): 测试已更新以反映 per-role 发布，但未验证具体 role 值。
- 全局 conftest 中的自动重置 fixture 可能与其他测试冲突 (testing): 未直接在本 PR 中解决，提示全局 reset 可能需调整作用域。

# 风险与影响

- 风险：本 PR 本身风险较低，因为它只涉及测试夹具和单元测试的调整，未修改生产代码。但作为配置迁移系列的一部分，若后续 PR 中生产代码对命名空间袋的依赖引入错误，可能导致运行时行为不一致。此外，棘轮基线降低意味着必须确保没有新代码绕过新的配置 API。
- 影响：影响范围限于两个测试文件：`test_runtime_context.py` 和 `test_legacy_global_ratchet.py`。这些变更确保单元测试与新的命名空间配置 API 兼容，并为后续生产代码迁移提供验证基础。对用户和系统无直接影响。
- 风险标记：测试全局 fixture 可能干扰其他测试

# 关联脉络

- PR #31816 : 此 PR 堆叠在 PR#31816 之上，后者引入了结构化 RuntimeContext 配置 API 的基础设施。