diff --git a/REVIEW.md b/REVIEW.md index a8347f002a6..5673fe1078d 100644 --- a/REVIEW.md +++ b/REVIEW.md @@ -27,6 +27,14 @@ Assume a better approach exists until you have tried to find one: An approach finding names the alternative and why it holds up better long-term. "Rework or abandon this PR" is a valid finding when the case is strong. +# Tests + +Unit tests mock time instead of depending on the real clock: a test that sleeps to let work settle, waits out a timeout to prove nothing happened, or asserts that an operation finished within a real-time budget passes on a quiet machine and flakes under load. +Flag one in any language, even when the timer goes through `kio::clock` or `@moq/clock`, whose timers still wait in real time until the test installs a paused, simulated, or `Manual` clock. +The fix is a mocked clock or an awaited event, never a shorter or longer real wait or a looser budget, and the same fix lands in every language's sibling test. +The exception is a test that drives real sockets, devices, or processes, which may wait on the real clock and opts out with `host_time()` or `hostTime()`; that opt-out belongs nowhere else. +The runtime guards fail Rust and bun tests only when a timer fires on the host clock, so they miss Go and Python tests, elapsed-time assertions, and any wait that bypasses those clocks; and Rust's `host_time()` lasts for the whole process, so it hides other tests' waits outside nextest's one-test-per-process runs. + # Not findings Each of these has been raised and refuted repeatedly here; the rules in `AGENTS.md` already decide them: diff --git a/quest/m0/README.md b/quest/m0/README.md index 929667880e5..ac0a83b835c 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -36,5 +36,4 @@ edge, which embeds moq-relay; it moved there on 2026-09-28. - [Bun-spawning test recipes install the JS workspace](/quest/m0/recipe-js-install.md) - `bare-fin`, `max-age`, `stream-limits`, `relay-fill`, and `receive-credit` pass in a fresh checkout - [CI cost and latency](/quest/m0/ci/README.md) - cloud CI runs only in GitHub's merge queue, one tested entry at a time, expensive checks run nightly and gate `release`, caches move to R2, and runners are chosen last - [More tests under load](/quest/m0/test-flakes-2/README.md) - load-only and queue failures, one quest per flake, fixed at the cause, since each one drops a queued PR -- [Tests can't wait on the real clock](/quest/m0/clock-guard/README.md) - a test whose real-clock timer fires fails every run, in JS and, if the spike holds, Rust - [Agent build output can't fill the desktop's disk](/quest/m0/agent-disk-budget.md) - finished agent checkouts reclaim their mbx targets automatically, so parallel agent builds stop filling the root disk diff --git a/quest/m0/clock-guard/README.md b/quest/m0/clock-guard/README.md deleted file mode 100644 index 8c3121f0381..00000000000 --- a/quest/m0/clock-guard/README.md +++ /dev/null @@ -1,40 +0,0 @@ -# [M] Tests can't wait on the real clock - -## Goal - -A new test that waits on the real clock fails every run instead of flaking -1 in 20 under load. Today's lints ban how a timer is spelled, not the clock -it runs on: `clippy.toml` and biome send every timer to `kio::clock` or -`@moq/clock`, whose `sleep`/`timeout` still wait in real time unless the -test installs a paused, simulated, or `Manual` clock. So a test passes every -lint and still proves "nothing happened" by waiting 200 ms of wall time, -which is how the `copy_fill` `idle()` flake landed -([moq-dev/moq#7845](https://github.com/moq-dev/moq/pull/7845)) three days -after the lint. - -The tests already waiting in real time are burned down in m1's -[Tests run on a mocked clock](/quest/m1/mock-clock-tests/README.md). - -## Plan - -Decided 2026-11-06 (maintainer, /quest-complete, from an audit of every -test's clock): - -- ✅ **JS fails a test when a real-clock timer fires**, with a scoped - opt-out, plus a `REVIEW.md` rule and a biome deny on the `Bun` global. Not - chosen: a grep check over changed lines (misses shared helpers); a review - rule alone (reviewers flagged #4039, #3641, #1717, and #7845, and the - waits landed anyway). -- ✅ **Rust spikes the same guard**, falling back to a grep check if the - spike fails. Not chosen: a grep check only; JS only for now. -- ✅ m0 for the guards, since each real-time wait is a future merge-queue - flake; the burn-down is m1. - -This README's own work: restore the rule to `REVIEW.md`, for every language. -"Unit tests mock time instead of depending on wall-clock timing or sleeps" -sat in root `AGENTS.md` from #4286 until -[moq-dev/moq#7761](https://github.com/moq-dev/moq/pull/7761) moved it into -`quest context`, where online reviewers no longer see it; today only -`rs/AGENTS.md` and `rs/moq-net/AGENTS.md` say anything. The rule should say -what a fix looks like: a mocked clock or an awaited event, never a shorter -or longer real wait, and the same fix in every language's sibling test. diff --git a/quest/m1/mock-clock-tests/README.md b/quest/m1/mock-clock-tests/README.md index fec17ff85cf..4bcee02b9c3 100644 --- a/quest/m1/mock-clock-tests/README.md +++ b/quest/m1/mock-clock-tests/README.md @@ -18,8 +18,8 @@ test's clock): assertions.** Not chosen: only the first two; also the ~530 tests that only wait for progress under a timeout, which flake little and would cost a much larger migration. -- ✅ m1, while the [guards](/quest/m0/clock-guard/README.md) that stop new - ones are m0. +- ✅ m1, while the guards that stop new ones (the runtime guards and the + `REVIEW.md` rule) landed in m0. Rules every child keeps: