mirror of
https://github.com/vercel/next.js.git
synced 2026-09-20 02:25:18 +08:00
Andrew Clark
94327e8ade
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.
92 lines
2.8 KiB
Bash
Executable File
92 lines
2.8 KiB
Bash
Executable File
#!/usr/bin/env bash
|
|
#
|
|
# Set up environment variables for a Next.js jest test run and exec jest
|
|
# in a single hop, replacing this shell process.
|
|
#
|
|
# Usage:
|
|
# scripts/run-jest.sh \
|
|
# [--mode=<dev|start|deploy>] \
|
|
# [--bundler=<webpack|turbo|rspack>] \
|
|
# [--experimental] \
|
|
# [--headless] \
|
|
# -- [jest args...]
|
|
#
|
|
# All arguments after `--` are forwarded verbatim to jest.
|
|
|
|
set -eo pipefail
|
|
|
|
while [ $# -gt 0 ]; do
|
|
case "$1" in
|
|
--mode=dev|--mode=start|--mode=deploy)
|
|
export NEXT_TEST_MODE="${1#--mode=}"
|
|
;;
|
|
--mode=*)
|
|
echo "run-jest.sh: unknown mode: ${1#--mode=}" >&2
|
|
exit 1
|
|
;;
|
|
--bundler=webpack)
|
|
export IS_WEBPACK_TEST=1
|
|
;;
|
|
--bundler=turbo)
|
|
export IS_TURBOPACK_TEST=1
|
|
;;
|
|
--bundler=rspack)
|
|
export NEXT_RSPACK=1
|
|
export NEXT_TEST_USE_RSPACK=1
|
|
;;
|
|
--bundler=*)
|
|
echo "run-jest.sh: unknown bundler: ${1#--bundler=}" >&2
|
|
exit 1
|
|
;;
|
|
--experimental)
|
|
export __NEXT_CACHE_COMPONENTS=true
|
|
;;
|
|
--headless)
|
|
export HEADLESS=true
|
|
;;
|
|
--)
|
|
shift
|
|
break
|
|
;;
|
|
*)
|
|
echo "run-jest.sh: unknown argument: $1" >&2
|
|
exit 1
|
|
;;
|
|
esac
|
|
shift
|
|
done
|
|
|
|
# `__NEXT_TEST_AXIS` names the alternate flag configurations of the test
|
|
# matrix. Axes are lettered (`A`, `B`, …) — a fixed enumeration a fixture opts
|
|
# into, not a boolean, and not one of the buckets test *sharding* splits a run
|
|
# into. CI runs the suites once plainly and once per axis, and a fixture keys
|
|
# an experimental flag on an axis to cover both states of the flag — enabled
|
|
# by default, disabled on that axis:
|
|
#
|
|
# experimental: {
|
|
# concurrentRouterQueue: process.env.__NEXT_TEST_AXIS !== 'A',
|
|
# }
|
|
#
|
|
# paired with a `// @gate concurrentRouterQueue` on the affected tests: a
|
|
# plain run — including a local run with no special env — exercises the
|
|
# feature, and the axis run covers the off state (see
|
|
# test/lib/gate/README.md).
|
|
#
|
|
# For now there is a single axis, `A`, and it is an alias for
|
|
# `__NEXT_CACHE_COMPONENTS` (the `--experimental` run) rather than a CI
|
|
# dimension of its own. That works because most experiments hard-code
|
|
# `cacheComponents: true` in their fixture anyway — the cache-components env
|
|
# default only applies to fixtures that don't set it themselves, so for these
|
|
# fixtures that run is free to double as the axis run. Setting either name
|
|
# implies the other.
|
|
if [ -n "${__NEXT_TEST_AXIS:-}" ]; then
|
|
export __NEXT_CACHE_COMPONENTS=true
|
|
elif [ "${__NEXT_CACHE_COMPONENTS:-}" = "true" ]; then
|
|
export __NEXT_TEST_AXIS=A
|
|
fi
|
|
|
|
# Resolves to `node_modules/.bin/jest` via `$PATH`. This relies on being
|
|
# invoked through pnpm (or another package runner), which prepends the
|
|
# workspace's `node_modules/.bin/` to `$PATH` before running the script.
|
|
exec jest --runInBand "$@"
|