Files

Check / check (pull_request) Failing after 5m24s

Details

doc: add testing policy — real DNS only, no mocks

Documents the project testing philosophy: all resolver tests must
use live DNS queries. Mocking the DNS client layer is not permitted.
Includes rationale and anti-patterns to avoid.

2026-02-22 04:28:47 -08:00

1.3 KiB

Raw Blame History

Testing Policy

DNS Resolution Tests

All resolver tests MUST use live queries against real DNS servers. No mocking of the DNS client layer is permitted.

Rationale

The resolver performs iterative resolution from root nameservers through the full delegation chain. Mocked responses cannot faithfully represent the variety of real-world DNS behavior (truncation, referrals, glue records, DNSSEC, varied response times, EDNS, etc.). Testing against real servers ensures the resolver works correctly in production.

Constraints

Tests hit real DNS infrastructure and require network access
Test duration depends on network conditions; timeout tuning keeps the suite within the 30-second target
Query timeout is calibrated to 3× maximum antipodal RTT (~300ms) plus processing margin
Root server fan-out is limited to reduce parallel query load
Flaky failures from transient network issues are acceptable and should be investigated as potential resolver bugs, not papered over with mocks or skip flags

What NOT to do

Do not mock DNSClient for resolver tests (the mock constructor exists for unit-testing other packages that consume the resolver)
Do not add -short flags to skip slow tests
Do not increase -timeout to hide hanging queries
Do not modify linter configuration to suppress findings