gate-tests

Gating tests with @gate / @force-gate

Full reference: test/lib/gate/README.md. This skill is the decision guide: which directive to reach for, the standard conversion patterns, and how to verify.

Never write these — gate instead

Anti-pattern	Replacement
it.skip('...') for a known failure	// @gate <cond> (or @gate FIXME if no condition explains it)
if (isNextDev) { test('skipped in dev mode', () => {}); return }	// @force-gate prefetching (or !dev) on the describe
(flagEnabled ? describe.skip : describe)(...) keyed on process.env	// @force-gate <cond> (lazy) on the describe
Duplicating a fixture directory per flag state	one fixture keyed on __NEXT_TEST_AXIS + a @gate/@force-gate
Branching expectations on process.env.__NEXT_CACHE_COMPONENTS	if (await gate((c) => c.cacheComponents)) (gate from next-test-utils)

The skip patterns are fake-greens: nothing tells you when the bug they hide is fixed. @gate still runs the body and fails the suite the day the "known failure" starts passing, so stale workarounds get deleted instead of rotting.

Choosing the directive

Ask what kind of difference you're encoding:

1. A behavior change — both states assert something meaningful. Don't gate the test at all: fork inside the body with the runtime gate() — same condition registry, no inversion — which pinpoints exactly what differs, and also covers it.each, where a pragma cannot attach: if (await gate((c) => c.cacheComponents)) { ... } else { ... }. It mirrors React's gate(flags => ...); a pragma expression string works too (await gate('cacheComponents && !dev')). A suite-level pragma is too coarse here — it hides what is different between the states.
2. A flag that changes the behavior of existing surface (cacheComponents, optimisticRouting) and the suite is written for one state. // @gate <cond> on the test or describe. The body runs; a false condition inverts the expectation (failure absorbed, a pass fails as "stale gate"). The off state fails for a meaningful reason — the behavior differs — so a pass is real information: the gate is stale, delete it.
3. A new API — the off state proves nothing. Typically // @force-gate <cond> (lazy) on the describe. An API that throws when its flag is off — or is inert, like useOffline(), which compiles to a hook that always reports online — can only fail vacuously (often slowly, by timing out), and browser e2e time is considerable, so skip the run (and the fixture build) instead of paying for it. Working example: test/e2e/app-dir/use-offline/. This is discretion, not a rule: when the flag changes behavior the suite can observe, the off state is meaningful and @gate buys the staleness check.
4. @force-gate <cond> also when running the body is impossible, not merely failing: prefetching is off in dev, deploy has no local build output, the fixture cannot even build under the condition.
   • Static condition (!dev, bundler…) → real Jest ○ skipped at collection.
   • Lazy condition on a describe → the fixture build is skipped when false; tests report passed-with-⚠ skipped by @force-gate (Jest cannot skip at runtime). Build-skipping covers start/dev suites where nextTestSetup owns the build — not skipStart suites, not deploy.
5. Pragmas stack: a common pair is a static // @force-gate prefetching plus a lazy // @gate <flag> on the same describe.