diff --git a/TESTING.md b/TESTING.md new file mode 100644 index 0000000..3dd34c4 --- /dev/null +++ b/TESTING.md @@ -0,0 +1,34 @@ +# 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