Files

T

check / check (push) Waiting to run

Details

docs: TESTING.md constraints match the resolver and the test-time policy (closes #289 )

The Constraints list named a query timeout calibrated to round-trip time and a
limited root-server fan-out; the resolver has neither. It now gives the
2-second timeout and the second try over UDP, says a zone's servers are asked
one at a time in a random order, and gives the 60-second cap and 20-second
target for make test from REPO_POLICIES.md. The line on flaky failures now
says, as the README does, that a flaky live test is fixed with robustness,
never with mocks or skip flags.

Model: opus-5-5

2026-10-15 15:34:30 +00:00

2.2 KiB

Raw Blame History

Testing Policy

DNS Resolution Tests

DNS is never mocked in this project, not in tests and not anywhere else; see the README section "No DNS mocking. Ever." Every test that looks something up in DNS MUST query live DNS servers, never a stand-in. Logic that works on record data, such as comparing or formatting records, may be tested on that data directly with no lookup.

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. make test must finish in under 60 seconds, the hard cap in REPO_POLICIES.md; under 20 seconds is the target
Each query to a nameserver has a 2-second timeout, and a query over UDP that gets no reply is sent once more (queryTimeoutDuration and maxRetries in internal/resolver/iterative.go)
In the walk to a name's nameservers, the servers of each zone are asked one at a time in a random order, as the README's DNS Resolution Strategy describes
Live lookups that expect an answer go through internal/livednstest, which limits how many run at once in a test binary and retries a lookup that got none
A flaky live test is a robustness problem, fixed with retries with backoff, several independent nameservers or longer timeouts, never with mocks or skip flags

What NOT to do

Do not mock, fake or stub DNS anywhere: no stand-in DNSClient, no stand-in for the watcher's DNSResolver, no fake DNS server, no canned responses
Do not add -short flags to skip slow tests
Do not increase -timeout to hide hanging queries
Do not remove -count=1 from the test phase of the Dockerfile — Go's test cache replays a previous run's output without querying anything, so a cached pass is not evidence that live resolution works
Do not modify linter configuration to suppress findings