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

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.

Is the off-state run worth its cost?

Browser e2e time is not free, so weigh what the gated-off run buys. For a behavior flag it usually replaces a run that was already being paid for — a fixture that pins its flags runs identically with and without the axis set, so keying the flag on an axis converts a redundant duplicate into coverage — and it is what proves a pass isn't vacuous: a test that passes with the feature off wasn't testing the feature. Absorbed failures also fail fast, so the off-state run is cheaper than it sounds. For a new API the calculus flips: the off state can only throw, which proves nothing, so use a lazy // @force-gate <flag> on the describe — the fixture build is skipped too, so the off state costs almost nothing.

Conditions

Every name in a pragma must be declared in test/lib/gate/conditions.ts (typos fail the suite at collection). Two tiers:

• static — the run's shape: dev, start, deploy, mode, turbopack, rspack, webpack, bundler, react18, wasm, linux, macos, windows, ci; specialized CI variants adapter, nodeMiddleware, standaloneOutput, turbopackDev, and turbopackBuild; plus the always-false FIXME/TODO. prod and prefetching are semantic aliases for !dev — prefer the name that states why the suite cannot run.
• lazy — a predicate over the fixture's resolved next.config (cacheComponents, ppr, useOffline, output, …).

Adding one is a two-line change; follow the guidance at the top of conditions.ts. The rule that matters: lazy conditions read the resolved config, never process.env — env vars don't survive config resolution (__NEXT_CACHE_COMPONENTS only applies when the fixture doesn't set cacheComponents itself, and resolution implies flags the fixture never mentions).