Add a server-router regression gate: pnpm test-routing (#100812)
## Summary
`pnpm test-routing` runs the e2e tests that check the server's routing
and HTTP behavior, first with `next start` and then with `next dev`,
through the existing `run-tests.js`. The suite passes on today's server,
so a failure after a change to the server is a regression. It's the gate
for consolidating the server and routing implementation.
- `test/routing-tests-manifest.json` is a v2 test manifest of whole
files: every test under `test/e2e/routing-server/`, plus 69 existing
suites that mostly test server routing. That's 87 files; start mode runs
86 and dev runs 80. Nothing is selected by test name, and a manifest
entry that matches no file fails the run.
- `scripts/test-routing.mjs` expands the manifest into explicit paths
for each mode and sets the same bundler environment as the CI jobs.
Turbopack is the default; `--bundler=webpack` and `--bundler=rspack`
also work, and the Rspack manifests narrow the list. It turns
`run-tests.js` retries off when a selected test directory has unstaged
changes, because a retry resets that directory with `git clean -fdx`.
- `test/e2e/routing-server/` adds 18 test files for payloads and body
limits, headers and cookies, streaming, compression, connection
lifecycle, route selection, routing phase order, Proxy, i18n, RSC
requests, caching, Draft Mode and image endpoints. Its README covers how
to run the suite.
- Tests assert what the server does today. Five check behavior today's
server doesn't have, so they run behind `@gate`, each with a TODO that
explains the failure and links the docs:
- In `next start`, hashed `_next/static` assets get the `Cache-Control`
from `headers()`, not the immutable policy that [the headers
docs](https://nextjs.org/docs/app/api-reference/config/next-config-js/headers#cache-control)
say can't be overridden.
- In `next start`, a `force-static` GET isn't cached when the same file
exports other methods, unlike what [the Route Handler caching
docs](https://nextjs.org/docs/app/getting-started/route-handlers#caching)
describe.
- `next/image` advertises `images.path`, but the server only serves
`/_next/image` ([Image
docs](https://nextjs.org/docs/app/api-reference/components/image#path)).
- With a matching Proxy, Pages client navigation to a config redirect
keeps the source URL, unlike what `redirects.mdx` describes.
- webpack dev prints no conflict message for a page and a Route Handler
at the same URL. That's a bundler inconsistency, not a docs
contradiction: the build and Turbopack dev print one.
- Seven of the existing suites cover areas where `@next/routing` is thin
or where adapters already fail, so the gate also catches differences if
`next start` switches to `@next/routing`: dynamic-route matching
(`dynamic-routing`), the rewritten-path headers on RSC requests
(`rewrite-headers`), RSC query handling (`adapter-rsc-query-leak`),
WebSocket upgrades (`socket-io`), forwarded host and protocol
(`x-forwarded-headers`), and two suites left out of deploy runs
(`i18n-hybrid`, `app-custom-route-base-path`).
- Three more new tests are gated only on Vercel deployments, where CI
runs new tests: the adapter build answers `/_error` with 200, Proxy
without a matcher doesn't run for `/_next/image`, and
`skipProxyUrlNormalize` doesn't show Proxy the data URL as sent.
- `test/e2e/api-support` now reads large responses to the end and writes
the chunked response with backpressure. On Node.js 24, the 4 MB
response-limit case failed with `SocketError: other side closed` without
this.
This replaces the earlier version of this PR. That version added a
separate scheduler with test-name selection (`--suite-list` in
`run-tests.js`), contract IDs in test names, and expectations in
existing suites for behavior that isn't built yet: custom server
lifecycle, bundler selection, tsconfig reloading and dev route repair.
All of that is dropped. Its small fixes to existing tests (next-head,
OpenTelemetry, metadata-dynamic-routes) can come as separate PRs.
## Verification
- `pnpm test-routing` (Turbopack) on Node.js 24.22.2, after merging
canary: start passed 86 files in 11.3 min and dev passed 80 files in
10.7 min. In dev, `dynamic-routing` › "should resolve dynamic route href
for page added later" passed on retry; it passed 3 of 3 runs on its own.
- `pnpm test-routing --bundler=webpack`: start passed in 14.1 min and
dev in 15.4 min. In dev, `cancel-request/stream-cancel` passed on retry.
- After the test names were reworded: `pnpm test-routing
test/e2e/routing-server --retries 0` passed with both bundlers in both
modes.
- Not run locally: deploy mode, Rspack, the Cache Components jobs and
Node.js 20.9.0.
- Run the suite locally on Node.js 24.21 or later. Earlier versions lack
the [realpath fix](https://github.com/nodejs/node/pull/65113), and
without it a dev fixture can load React twice and time out.
<!-- NEXT_JS_LLM -->