pipework 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.30.0
+
+- **Test setup narrates its steps, and its own bound is on progress rather than on a wall clock.** `setupTestDatabases()` was a single awaited call: a consumer's `beforeAll` had nothing to log while it ran, and nothing to say when it did not finish. Under a width-40 start burst, a setup that was merely queued behind its peer forks — advancing the whole time — was killed by vitest's 60 s hook timeout and reported as `Hook timed out in 60000ms` with no test assertion attached, a reading about the host rather than about the suite. `setupTestDatabases(instance, { onProgress })` now reports every step it reaches: `rls-probe`, `run-prepare`, `template-pin`, `template-wait` (once per poll while a peer builds), `template-build`, `template-migrate` (once per migration file), `template-ready`, `queue-check`, `clone-start`, `clone-done`, `ready`. Each report names the phase, the database it is about, the total elapsed time, and the phase it displaced with how long that held — so a caller can log the steps, or time them, without parsing prose. Setup also bounds itself now, and the bound is on PHASE ADVANCE, not on total elapsed time: a setup that keeps reaching steps finishes late and green however long the whole thing takes, while one that stops advancing for `test.setupStallMs` (default 120 s) fails as `SetupStalled`, naming the last phase reached, the database, how long it has been stuck, and the total elapsed. The default setup file installs a listener that stays silent while setup is quick and writes one `pipework:test-setup slow phase=… db=… held_ms=… next=… elapsed_ms=…` line per phase that held 10 s or longer — so a healthy run gains no output and a late one explains itself. `applyMigrations()` takes a matching `onMigration` callback, which is what keeps a long migration replay from looking like a stall. Existing callers are unaffected: the options argument is optional and setup's behavior without it is unchanged.
+
 ## 0.29.0
 
 - **New: `closeSetupConnections()` lets a consumer close the harness's setup connections before their own `afterAll` looks at the database.** The connections `useSetupDb()` opens are closed by `setupPipeworkTests`' own `afterAll`, and under vitest's `sequence.hooks: 'stack'` that hook runs *after* every setupFile `afterAll` — so a teardown-time observer sampling `pg_stat_activity` to name leaked backends saw every setup connection still open and could not tell them from a real leak. The internal `_closeSetupConnections` was not reachable through the `pipework/test` entry, leaving copying `useSetupDb` app-side purely to win the hook order as the only way out. `closeSetupConnections()` is now exported from `pipework/test`: close first, then sample, and what remains is a true survivor set. It is idempotent, a connection that throws on close is still tolerated, and calling it early does not disturb the harness's own teardown — the pool still closes and the databases still drop afterwards. A later `useSetupDb()` opens a fresh connection. Hook order is unchanged for everyone else.