testing.md

Testing

• pytest-asyncio auto mode. Async test functions do not require @pytest.mark.asyncio. The setting lives in pyproject.toml under [tool.pytest.ini_options].
• httpx2.MockTransport for transport mocking, not respx. Tests construct httpx2.AsyncClient(transport=httpx2.MockTransport(handler)) and pass it as httpx2_client= to AsyncClient (or the sync equivalent httpx2.Client(transport=httpx2.MockTransport(handler)) to Client). MockTransport is a first-party httpx2 API; respx targets httpx (not httpx2) and patches its internals directly — see docs/testing.md for why.
• Hypothesis property-based tests for concurrency-sensitive code: RetryBudget, Bulkhead, retry interleaving. Files are named test_*_props.py so they are easy to grep and treat separately in CI.
• Benchmarks are standalone scripts, not pytest tests. Performance characterization (e.g. benchmarks/contention.py) lives under benchmarks/ (coverage-omitted via run.omit), run explicitly and never gated in CI — shared-runner perf is too noisy to gate on.
• stress marker for free-threading proof. Registered in pyproject.toml, stress-marked tests drive real thread parallelism (ThreadPoolExecutor, shared instances, high iteration counts, invariant-not-timing assertions) against httpware's Lock/Semaphore-based components and the shared httpx2 connection pool. They run in the default suite too, so they count toward coverage under the GIL — but the GIL serializes bytecode execution, so a GIL run only exercises the code path, it does not prove thread-safety. That proof comes from the pytest-freethreaded CI job, which runs the full suite on free-threaded CPython 3.14t with the GIL disabled (the job asserts sys._is_gil_enabled() is False in a shell step before running the suite). 3.13t is deferred — see planning/deferred.md — pending an msgspec cp313t wheel.
• Coverage is 100% line coverage. New code is expected to maintain this.