Writing SGLang CI / UT Tests

Apply kernel-organization for the public operator namespace, logical grouping, lazy registry metadata, and test placement. The implementation tutorial below does not replace that API contract.

This skill covers how to write and register tests. For CI pipeline internals (stage ordering, fail-fast, gating, partitioning, debugging CI failures), see the CI workflow guide. Whether a case is worth adding at all is decided by unit-test-admission — read it before writing the case, not after.

Core Rules

1. Always use CustomTestCase — never raw unittest.TestCase. It ensures tearDownClass runs even when setUpClass fails, preventing resource leaks in CI.
2. tearDownClass must shut the server down gracefully — call terminate_and_kill_process_tree(cls.process), never a bare kill_process_tree. SIGKILL alone skips the server's userspace cleanup and leaves its GPU memory charged to the dead process; the next class then OOMs while loading weights. Keep it defensive too: hasattr/null checks before accessing resources (e.g. cls.process) that setUpClass may not have finished allocating.
3. Place non-kernel tests in test/registered/<kind>/<subsystem>/ — <kind> is unit, e2e, accuracy, perf, or stress; kernel tests use test/registered/kernels/{ops,benchmark}/<group>/; hardware belongs in registrations, not directory names
4. Reuse server fixtures — inherit from DefaultServerBase or write setUpClass/tearDownClass with popen_launch_server
5. Mock boundaries, not SGLang behavior — mock slow or external dependencies only when the assertion still checks an observable result, state transition, or error. A test whose evidence is only assert_called* mirrors its mock and is not admissible. Launch a real server only when inference results or lifecycle behavior are the contract under test.