From cd3f7cea3bd577e349d0d2d92db7426d3442f2de Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=A0=95=EC=8B=9C=EC=9B=90?= <sebastianrcnt@gmail.com>
Date: Thu, 7 May 2026 02:11:16 +0900
Subject: [PATCH] Add test coverage notes

---
 docs/test-coverage-notes.md | 53 +++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 docs/test-coverage-notes.md

diff --git a/docs/test-coverage-notes.md b/docs/test-coverage-notes.md
new file mode 100644
index 0000000..af75841
--- /dev/null
+++ b/docs/test-coverage-notes.md
@@ -0,0 +1,53 @@
+# Test Coverage Notes
+
+Current quick coverage command, excluding Cython line coverage:
+
+```bash
+uv run --with coverage coverage run --source=src/coolrl_lost_cities -m pytest tests/games/classic
+uv run --with coverage coverage report -m
+uv run --with coverage coverage html -d htmlcov
+```
+
+Latest snapshot:
+
+- `98 passed`
+- `69%` total coverage
+- The report is effectively Python-only because the existing `.pyx` extensions
+  were not built with Cython tracing.
+
+Deferred ideas:
+
+1. Add a tiny coverage helper script if this command becomes common.
+2. Keep normal coverage Python-only by default, so the existing Cython build
+   artifacts stay untouched.
+3. If `.pyx` line coverage becomes useful, run it in a separate `git worktree`
+   or fresh clone. Avoid `build_ext --inplace --force` in the main working tree,
+   because it can overwrite the normal `.so` files with tracing builds.
+4. Gate Cython tracing behind an environment variable such as
+   `CYTHON_COVERAGE=1`.
+5. For tracing builds, enable both Cython line tracing and coverage's Cython
+   plugin:
+
+```python
+compiler_directives={
+    "linetrace": True,
+    # existing directives...
+}
+define_macros=[("CYTHON_TRACE", "1")]
+```
+
+```ini
+[run]
+plugins = Cython.Coverage
+source = src/coolrl_lost_cities
+```
+
+Rough performance expectation:
+
+- Python-only coverage: usually modest overhead.
+- Cython tracing build without coverage: likely noticeable but manageable.
+- Cython tracing plus coverage: can be several times slower, and tight
+  traversal or encoding loops may be much worse.
+
+Practical default: keep the main tree fast and boring. Measure `.pyx` coverage
+only when there is a specific question about the Cython paths.