From 0cff0708289dd5dc6ee2794b57914702c0ec6ae3 Mon Sep 17 00:00:00 2001
From: Ke Bao <ispobaoke@gmail.com>
Date: Sun, 15 Mar 2026 20:27:05 +0800
Subject: [PATCH] [CI] Add READMEs for unit test directory structure (#20626)

---
 test/registered/README.md      | 23 ++++++++++++++
 test/registered/unit/README.md | 55 ++++++++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 test/registered/README.md
 create mode 100644 test/registered/unit/README.md

diff --git a/test/registered/README.md b/test/registered/README.md
new file mode 100644
index 000000000..433c9ffb3
--- /dev/null
+++ b/test/registered/README.md
@@ -0,0 +1,23 @@
+# Registered Tests
+
+Tests under this directory are auto-discovered by `run_suite.py` via CI registration decorators.
+
+## Where Should I Put My New Test?
+
+### No server / engine launch required
+
+| What you're testing | Directory | Requires |
+|---|---|---|
+| Component logic in isolation (cache, scheduler, config, parser, etc.) | [`unit/<module>/`](unit/README.md) | CPU or GPU |
+| CUDA kernel correctness | `kernels/` | GPU |
+
+### Server / engine launch required (E2E)
+
+| What you're testing | Directory | Requires |
+|---|---|---|
+| Model inference correctness | `models/`, `4-gpu-models/`, `8-gpu-models/` | GPU |
+| Feature-specific (OpenAI API, LoRA, speculative, distributed, VLM, etc.) | `openai_server/`, `lora/`, `spec/`, `distributed/`, ... | GPU |
+| Benchmarks (performance, accuracy, stress) | `benchmark/` | GPU |
+| Platform-specific | `amd/`, `ascend/` | Vendor GPU |
+
+See [`unit/README.md`](unit/README.md) for unit test conventions.
diff --git a/test/registered/unit/README.md b/test/registered/unit/README.md
new file mode 100644
index 000000000..e2d6aa5dd
--- /dev/null
+++ b/test/registered/unit/README.md
@@ -0,0 +1,55 @@
+# Unit Tests
+
+Component-level tests that do **not** launch a server or load model weights.
+Tests can use CPU or GPU — the key criterion is **no server process**.
+
+## Quick Start
+
+1. Find the source file under `python/sglang/srt/`.
+2. Create the corresponding test here, mirroring the source tree:
+   ```
+   srt/mem_cache/radix_cache.py       →  unit/mem_cache/test_radix_cache.py
+   srt/sampling/sampling_params.py    →  unit/sampling/test_sampling_params.py
+   ```
+3. Register for CI at the **top of the file** (after imports, before test classes):
+   ```python
+   from sglang.test.ci.ci_register import register_cpu_ci
+   register_cpu_ci(est_time=5, suite="stage-a-cpu-only")
+   # or: register_cuda_ci(est_time=10, suite="stage-b-test-small-1-gpu")
+   ```
+4. Run locally:
+   ```bash
+   pytest test/registered/unit/ -v            # all unit tests
+   pytest test/registered/unit/mem_cache/ -v  # one module
+   ```
+
+## Example
+
+```python
+"""Unit tests for <module> — no server, no model loading."""
+
+from sglang.test.ci.ci_register import register_cpu_ci
+
+register_cpu_ci(est_time=5, suite="stage-a-cpu-only")
+
+import unittest
+
+from sglang.srt.<module> import TargetClass
+
+
+class TestTargetClass(unittest.TestCase):
+    def test_basic_behavior(self):
+        obj = TargetClass(...)
+        self.assertEqual(obj.method(), expected)
+
+
+if __name__ == "__main__":
+    unittest.main()
+```
+
+## Rules
+
+- **No** `popen_launch_server()` or `Engine(...)`.
+- **No** model weight loading.
+- Use `unittest.TestCase` or `CustomTestCase` (from `sglang.test.test_utils`, adds CI retry).
+- Use `unittest.mock` for dependencies that are expensive to construct.