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.
101 lines
4.0 KiB
JavaScript
101 lines
4.0 KiB
JavaScript
const nextJest = require('next/jest')
|
|
const { withGateTransformer } = require('./test/lib/gate/jest-transformer')
|
|
|
|
const createJestConfig = nextJest()
|
|
|
|
// Any custom config you want to pass to Jest
|
|
/** @type {import('jest').Config} */
|
|
const customJestConfig = {
|
|
displayName: process.env.IS_WEBPACK_TEST ? 'webpack' : 'Turbopack',
|
|
testMatch: ['**/*.test.js', '**/*.test.ts', '**/*.test.jsx', '**/*.test.tsx'],
|
|
setupFilesAfterEnv: ['<rootDir>/jest-setup-after-env.ts'],
|
|
verbose: true,
|
|
rootDir: 'test',
|
|
roots: [
|
|
'<rootDir>',
|
|
'<rootDir>/../packages/next/src/',
|
|
'<rootDir>/../packages/next-codemod/',
|
|
'<rootDir>/../packages/eslint-plugin-internal/',
|
|
'<rootDir>/../packages/font/src/',
|
|
'<rootDir>/../packages/next-routing/',
|
|
],
|
|
haste: {
|
|
// Throwing to avoid warnings creeping up over time polluting log output.
|
|
throwOnModuleCollision: true,
|
|
},
|
|
modulePathIgnorePatterns: [
|
|
'/\\.next/',
|
|
// Prevents jest-haste-map warnings due to multiple versions of the same
|
|
// package being vendored. Also means tests in `compiled` will be ignored.
|
|
// Jest does not normalize/resolve paths in modulePathIgnorePatterns so we can't
|
|
// prefix with <rootDir>/../ like we do in roots.
|
|
'packages/next/src/compiled/',
|
|
'<rootDir>/development/app-dir/non-context-aware-addon/bindings',
|
|
'<rootDir>/development/app-dir/non-context-aware-addon/single-context-addon',
|
|
'<rootDir>/development/app-dir/ssr-in-rsc/internal-pkg/',
|
|
'<rootDir>/e2e/app-dir/self-importing-package/internal-pkg',
|
|
'<rootDir>/e2e/app-dir/self-importing-package-monorepo/internal-pkg',
|
|
'<rootDir>/e2e/app-dir/server-source-maps/fixtures/default/internal-pkg',
|
|
'<rootDir>/e2e/app-dir/turbopack-reports/bindings',
|
|
'<rootDir>/e2e/app-dir/turbopack-reports/native-addon',
|
|
'<rootDir>/e2e/prerender-native-module/bindings',
|
|
'<rootDir>/e2e/prerender-native-module/native-addon',
|
|
'<rootDir>/e2e/prerender-native-module/native-addon-wrapper',
|
|
'<rootDir>/e2e/transpile-packages-typescript-foreign/pkg',
|
|
'<rootDir>/production/prerender-worker-threads/bindings',
|
|
'<rootDir>/production/prerender-worker-threads/single-context-addon',
|
|
'<rootDir>/production/standalone-mode/tracing-side-effects-false/foo',
|
|
'<rootDir>/production/standalone-mode/tracing-static-files/foo',
|
|
'<rootDir>/production/standalone-mode/tracing-unparsable/foo',
|
|
'<rootDir>/production/supports-module-resolution-nodenext/pkg',
|
|
],
|
|
modulePaths: ['<rootDir>/lib'],
|
|
transformIgnorePatterns: ['/next[/\\\\]dist/', '/\\.next/'],
|
|
moduleNameMapper: {
|
|
'@next/font/(.*)': '@next/font/$1',
|
|
},
|
|
}
|
|
|
|
// Check if the environment variable is set to enable test report,
|
|
// Insert a reporter to generate a junit report to upload.
|
|
//
|
|
// This won't count retries to avoid tests being reported twice.
|
|
// Our test report will report test results for flaky tests as failed without retry.
|
|
const enableTestReport = !!process.env.NEXT_JUNIT_TEST_REPORT
|
|
|
|
if (enableTestReport) {
|
|
if (!customJestConfig.reporters) {
|
|
customJestConfig.reporters = ['default']
|
|
}
|
|
|
|
let outputDirectory
|
|
if (process.env.IS_TURBOPACK_TEST) {
|
|
outputDirectory = '<rootDir>/turbopack-test-junit-report'
|
|
} else if (process.env.NEXT_RSPACK) {
|
|
outputDirectory = '<rootDir>/rspack-test-junit-report'
|
|
} else {
|
|
outputDirectory = '<rootDir>/test-junit-report'
|
|
}
|
|
|
|
customJestConfig.reporters.push([
|
|
'jest-junit',
|
|
{
|
|
outputDirectory,
|
|
reportTestSuiteErrors: 'true',
|
|
uniqueOutputName: 'true',
|
|
outputName: 'nextjs-test-junit',
|
|
addFileAttribute: 'true',
|
|
},
|
|
])
|
|
}
|
|
|
|
// createJestConfig is exported in this way to ensure that next/jest can load the Next.js config which is async
|
|
const createConfig = createJestConfig(customJestConfig)
|
|
|
|
module.exports = async function createConfigWithGates() {
|
|
// `withGateTransformer` chains the `@gate` pragma rewrite in front of the
|
|
// SWC transformer that `next/jest` configured, keeping next/jest's SWC
|
|
// options as the single source of truth. See test/lib/gate/.
|
|
return withGateTransformer(await createConfig())
|
|
}
|