test: expect(fn).toThrow(Class) passes when fn RETURNS an error — zero instances today, and nothing stops the next one #150

The hazard

In Bun 1.3.14, a function that returns an error satisfies .toThrow(). Verified directly:

expect(() => new TypeError('x')).toThrow(TypeError);  // PASSES — nothing threw
expect(() => ({ a: 1 })).toThrow();                   // correctly fails

So the matcher does not distinguish "threw an Error" from "returned an Error". Any test of the shape expect(() => f()).toThrow(SomeError) where f returns rather than throws is vacuously green.

Why this repo is unusually exposed to it

packages/*/src/errors.ts is full of error factories that return — loginFailed(), poolMaxInvalid(), rollbackStepsInvalid(), driverUnknown(), mfaRequiredUnenforceable(), and so on. The house pattern is throw someError(...). Writing expect(() => someError(x)).toThrow(...) — dropping the throw — is a natural slip, reads correctly, and passes.

That is exactly the "a test that cannot fail is not a test" rule the conventions already state, in a form no reviewer will spot: the test is green and the assertion looks right.

Current exposure: none

Swept all 731 .toThrow call sites across packages/ and scripts/. Exactly one matches the risky shape, and it is expect(() => reportError(hostile, …)).not.toThrow() (packages/core/src/error-reporter.test.ts:171) — a negated assertion on a void function, unaffected.

So this is a latent trap, not a live defect. Filing it because the sweep that found it was looking at something else, and the next person to write an error-factory test will not know.

How it was found

An agent on PR #148 wrote a test in this shape, noticed it passed against code that could not have satisfied it, and rewrote it with an explicit try/catch plus an identity assertion (packages/action/src/json-schema.test.ts). It self-reported the near-miss rather than banking the green.

Fix direction

Enforcement beats documentation (axiom 3). Options, cheapest first:

1. A Biome lint rule, or a scripts/ check in the errors verify step, refusing expect(() => <ident>(…)).toThrow where the callee resolves to a known error factory (the errors.ts export sets are already enumerable — collectDeclaredCodes() walks them).
2. A repo convention that error-throw tests use try/catch + isUltimateError(caught) + a code assertion, which is what the strongest existing tests already do, plus a check that .toThrow( never appears with a bare factory call.

Option 1 is a real gate step; option 2 alone is a convention, and a convention that is not a build error does not exist.

Found by the multi-agent bug sweep, 2026-08-18.