The test suite has accumulated a bunch of patterns for disabling tests
that are known to fail under some configuration: `it.skip`, `if
(isNextDev) { test('skipped in dev mode', () => {}); return }`, whole
describes toggled off by checking `process.env.__NEXT_CACHE_COMPONENTS`.
These all have the same flaw: nothing tells you when the thing you
skipped starts working. The test stays disabled forever, and the
workaround it was guarding rots along with it.
React solves this with the `@gate` pragma, and this PR ports it to the
Next.js e2e harness:
```ts
// Blocked on the optimization that marks a route as fully static when
// no dynamic params are referenced in Server Components.
// @gate !cacheComponents
it('navigates to a page with a lazily-generated static param', async () => {
// body unchanged
})
```
The test still runs. If the condition is false and the test fails, the
failure is absorbed and the suite stays green. If it _passes_, the suite
fails: the gate is stale, delete it. So instead of a skip that hides a
fixed bug indefinitely, you get a CI failure the day the fix lands.
When the condition is static, the inversion is Jest's own `test.failing`
under the hood. A lazy condition isn't known until the fixture's
resolved config is read inside the body, so those tests invert at
runtime instead.
`// @force-gate <condition>` skips for real — for tests that can't even
be attempted (prefetching is disabled in dev, deploy has no local build
output, the fixture won't build under the condition), and for tests of a
new API, where the disabled state can only throw and running it proves
nothing:
```ts
// Prefetching is disabled in dev, so this suite has nothing to test.
// @force-gate prefetching
describe('segment cache prefetch scheduling', () => {
// ...
})
```
There's no staleness check in that case, so this is a judgment call:
prefer `@gate` when the off state fails for a meaningful reason — the
flag changes behavior that already exists — and `@force-gate` when the
body can only throw because the API doesn't exist. A static condition
(mode, bundler) resolves at collection time into a normal Jest skip. A
lazy condition resolves at runtime, and when a lazy force-gate on a
describe is false, we skip the fixture build entirely — that's what
makes it usable for suites whose fixtures are build-incompatible with
the condition. (One caveat: Jest has no way to skip a test that's
already running, so these report as passing with a warning in the log,
not as skipped.)
Conditions live in a hand-written registry. I considered deriving the
lazy ones from the config schema automatically, but a gate is a claim
about which dimension of the test matrix explains a failure, and I'd
rather each of those claims be spelled out with a description.
Referencing an undeclared name fails the suite at collection time, so a
typo can't silently disable a gate.
The important design decision for lazy conditions is that they read the
fixture's _resolved_ config, never `process.env`. The env var isn't the
truth: `__NEXT_CACHE_COMPONENTS=true` only applies when the fixture
doesn't set `cacheComponents` itself, and config resolution implies
flags the fixture never mentions (`cacheComponents: true` alone turns on
`experimental.ppr`). Resolution happens in a child process, because
in-process `loadConfig` would leak the fixture's `.env` files into the
Jest worker. Suites with no lazy gate never pay for any of this.
The condition expression is parsed using a small grammar (also ported
from the React repo). An expression that doesn't parse fails the suite:
```ts
// @gate mode === 'start' && !cacheComponents
// @gate !(turbopack || rspack)
```
There's also a runtime version, mirroring React's `gate(flags =>
flags.enableFoo)`, for tests that run under both states but assert
differently (and for `it.each`, where the pragma can't attach):
```ts
import { gate } from 'next-test-utils'
it('renders the fallback', async () => {
if (await gate((conditions) => conditions.cacheComponents)) {
// PPR: the fallback is part of the static shell
} else {
// fully dynamic: the fallback streams in
}
})
```
It also accepts the pragma expression language as a string: `await
gate('cacheComponents && !dev')`.
Docs are in `test/lib/gate/README.md`; `test/unit/gate/` covers the
transform, the expression language, and the runtime.
### What?
Every `pnpm test-*` / `pnpm testonly-*` script in the root `package.json` is now a single direct invocation of a new `scripts/run-jest.sh` helper instead of chaining through several `pnpm run` + `cross-env` layers.
### Why?
Each hop through `pnpm run` / `cross-env` spins up its own Node process and takes a few hundred milliseconds before anything useful happens. For example, `pnpm test-dev-turbo` used to walk through five layers:
```
test-dev-turbo
-> pnpm run with-turbo pnpm test-dev-inner (cross-env IS_TURBOPACK_TEST=1)
-> pnpm test-dev-inner (cross-env NEXT_TEST_MODE=dev)
-> pnpm testheadless (cross-env HEADLESS=true)
-> pnpm testonly
-> jest --runInBand
```
#### Measured overhead (same machine, same stubbed jest invocation — `jest --version`)
| Chain | Layers | Median (ms) | Range (ms) |
|---|---|---|---|
| `jest --version` (baseline, direct) | 1 | 80 | 75–89 |
| `pnpm test-dev-turbo --version` (**new**) | `pnpm → bash → jest` | 448 | 435–493 |
| `pnpm test-dev-turbo --version` (**old**) | `pnpm → cross-env → pnpm → cross-env → pnpm → cross-env → pnpm → jest` | 2494 | 2462–2512 |
That's **~2 seconds per test invocation** shaved off, and ~85% reduction in wrapper overhead (from ~2414 ms to ~368 ms). The remaining ~368 ms is essentially just one `pnpm run` startup, which is unavoidable while we keep the `pnpm test-*` entry points.
Real-world impact: for a ~72 s e2e test run this is ~3%, but for fast unit-test files (often <5 s) this is closer to 30-40%, and it adds up quickly in CI jobs that shell out to these scripts in a loop.
### How?
- New `scripts/run-jest.sh` parses named flags and `exec`s jest directly:
- `--mode=<dev|start|deploy>` → sets `NEXT_TEST_MODE`
- `--bundler=<webpack|turbo|rspack>` → sets `IS_WEBPACK_TEST=1` / `IS_TURBOPACK_TEST=1` / `NEXT_RSPACK=1 NEXT_TEST_USE_RSPACK=1`
- `--experimental` → sets `__NEXT_CACHE_COMPONENTS=true __NEXT_EXPERIMENTAL_APP_NEW_SCROLL_HANDLER=true`
- `--headless` → sets `HEADLESS=true`
- `--` terminates flag parsing; everything after is forwarded verbatim to jest so existing workflows like `pnpm test-dev-turbo path/to/foo.test.ts -t "pattern"` keep working.
- Every `test-*` / `testonly-*` entry in `package.json` (including `testheadless`) now reads like `scripts/run-jest.sh --mode=dev --bundler=turbo --headless --`. No more `pnpm run` / `cross-env` indirection at the top level.
- Removed nine unused internal intermediates (`test-dev-inner`, `test-dev-experimental-inner`, `test-start-inner`, `test-start-experimental-inner`, `test-deploy-inner`, `testonly-dev-inner`, `testonly-start-inner`, `testonly-deploy-inner`, `test-inner`). These were only called by other package.json scripts and not referenced anywhere else in the repo.
- Kept `testonly`, `testheadless`, and all public `test-*` / `testonly-*` names so `AGENTS.md`, `contributing/core/testing.md`, `.conductor/`, and `.agents/skills/` work unchanged.
- The `with-webpack`, `with-turbo`, `with-rspack`, and `with-experimental` prefix scripts remain for ad-hoc use; they are just no longer in the hot path of the test scripts.
- `scripts/run-jest.sh` invokes a bare `jest`, which resolves via `$PATH` (pnpm prepends `node_modules/.bin/` when running a package script). The helper is documented as only supported when invoked through a package runner.
### Verification
Ran a small e2e test through the new chain in both dev+turbopack and start+webpack modes. Output confirms env vars propagate correctly (`PASS Turbopack ...` / `PASS webpack ...`, plus `pnpm next --turbopack` vs `pnpm next start` in the logs):
```
pnpm test-dev-turbo test/e2e/app-dir/_allow-underscored-root-directory/...
-> PASS Turbopack ... 3 passed
pnpm test-start-webpack test/e2e/app-dir/_allow-underscored-root-directory/...
-> PASS webpack ... 3 passed
```
CI is unaffected: every workflow invokes `node run-tests.js ...` directly, never through these pnpm scripts.
<!-- NEXT_JS_LLM_PR -->
Andrew Clark