coorl-lost-cities/docs/archive/test-coverage-notes.md

Test Coverage Notes

Current quick coverage command, excluding Cython line coverage:

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:

compiler_directives={
    "linetrace": True,
    # existing directives...
}
define_macros=[("CYTHON_TRACE", "1")]

[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.