Agent skill · vercel
gate-tests
How to use the `@gate` / `@force-gate` test directives instead of `it.skip` or fake-green skip patterns. Use when a test is known-failing under some test-matrix dimension (dev mode, a bundler, an experimental flag like cacheComponents), when converting `if (isNextDev) return` guards or env-var `describe.skip` branches, when adding a condition to test/lib/gate/conditions.ts, or when keying a fixture's experimental flag on a __NEXT_TEST_AXIS letter. Covers directive choice, condition tiers, the test-axis fixture pattern, pitfalls, and verification commands.
What it needs
About 6k tokens when loaded.
What this skill does
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 NEXTTESTAXIS + a @gate/@force-gate Branching expectations on process.env.NEXTCACHECOMPONENTS 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. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills vercel/gate-tests