From ed239b248b93b659885649ea1a0eeb0da69ad688 Mon Sep 17 00:00:00 2001 From: sneak Date: Thu, 15 Oct 2026 11:27:11 +0000 Subject: [PATCH] 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 --- TESTING.md | 16 +++++++++------- TODO.md | 4 ++++ 2 files changed, 13 insertions(+), 7 deletions(-) diff --git a/TESTING.md b/TESTING.md index d216a73..c256ba3 100644 --- a/TESTING.md +++ b/TESTING.md @@ -19,16 +19,18 @@ 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 60-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 +- 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 -- Flaky failures from transient network issues are acceptable and should be - investigated as potential resolver bugs, not papered over with mocks or skip +- 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 diff --git a/TODO.md b/TODO.md index c6e8b06..ba34bd0 100644 --- a/TODO.md +++ b/TODO.md @@ -19,6 +19,10 @@ milestone: https://git.eeqj.de/sneak/dnswatcher/milestone/7 # Completed Steps +- 2026-10-15: `TESTING.md` Constraints give the resolver's 2-second query + timeout and second try, say a zone's servers are asked one at a time in a + random order, give the 60-second cap and 20-second target for `make test`, and + say a flaky live test is fixed with robustness, not with mocks (closes #289). - 2026-10-15: a request under `/s/` that names a directory, such as `/s/` or `/s/css`, answers 404 instead of a listing of its files (closes #286). - 2026-10-15: a notification endpoint that answers with a redirect, or any