Unverified Commit f76af5ca authored by Andrew Clark's avatar Andrew Clark Committed by GitHub

Make router-act ignore App Shell prefetch requests (#94580)

When App Shells is enabled, prefetching is split into two phases: a
prefetch for the shell, and a separate phase for the per-page content.

This would cause a handful of the existing prefetch-related tests to
fail once App Shells is turned on. However, the fact that the shell is
prefetched separately from the page content is an incidental detail of
how prefetching works. The App Shell is conceptually part of the route,
not part of the "prefetch". Or in other words, App Shell prefetching has
more in common with incremental module loading than it does with
prefetching in the traditional sense used in the context of web apps.

So, this updates router-act to ignore App Shell requests for the
purposes of making assertions about prefetch responses. They're still
captured, fulfilled, and awaited — they just don't participate in the
matching logic. Tests that specifically assert on App Shell behavior can
opt back in with `createRouterAct(page, { includeAppShellRequests: true
})`.

This is groundwork for the next PR, which enables App Shells by default.
With these requests ignored, most prefetch tests pass unchanged
regardless of whether App Shells is on.

<!-- NEXT_JS_LLM_PR -->
parent 9af81ed9
...@@ -60,6 +60,22 @@ await act(async () => { ... }) ...@@ -60,6 +60,22 @@ await act(async () => { ... })
- Extra responses that don't match any `includes` assertion are silently ignored — you only need to assert on the responses you care about. This keeps tests decoupled from the exact number of requests the router makes. - Extra responses that don't match any `includes` assertion are silently ignored — you only need to assert on the responses you care about. This keeps tests decoupled from the exact number of requests the router makes.
- Each `includes` expectation claims exactly one response. If the same substring appears in N separate responses, provide N separate `{ includes: '...' }` entries. - Each `includes` expectation claims exactly one response. If the same substring appears in N separate responses, provide N separate `{ includes: '...' }` entries.
### App Shell requests are ignored by default
When App Shells are enabled (the default when Cache Components is on), a `prefetch` is split into two phases: an **App Shell** prefetch — the param/searchParam-independent chrome of the route (layouts, loading boundaries, static shell) — and a separate per-link/per-page data prefetch. The App Shell is conceptually part of the route, not prefetch data, so **`act` ignores App Shell requests for all assertion purposes** (they carry a `next-router-prefetch: '3'` header).
This means you generally do **not** need to account for the extra App Shell response in your assertions. If a `Loading...` fallback now arrives in both the App Shell prefetch and the per-link prefetch, you still write a single `{ includes: 'Loading...' }` — the App Shell copy is invisible to matching. Likewise, `'no-requests'` still passes even if an App Shell prefetch fires, and `block: 'reject'` won't match content that appears only in the App Shell.
App Shell requests are still intercepted, fulfilled, and awaited (so the shell is cached and no requests are left in flight) — they just don't participate in `includes` matching, `no-requests`, `block: 'reject'`, or the "at least one request" check. An App Shell response that returns an error status (4xx/5xx) still fails the test.
To assert on App Shell responses directly — for tests specifically about App Shell behavior — opt in at the `act` instance level:
```typescript
const act = createRouterAct(page, { includeAppShellRequests: true })
```
With this option, App Shell requests are treated like any other router request. Prefer expressing App Shell behavior through observable outcomes (e.g. an instant navigation rendering the cached shell before the data response arrives) rather than asserting on prefetch content where practical. See `test/e2e/app-dir/segment-cache/prefetch-app-shell/prefetch-app-shell.test.ts` for the canonical example.
### What `act` Does Internally ### What `act` Does Internally
`act` intercepts all router requests — prefetches, navigations, and Server Actions — made during the scope: `act` intercepts all router requests — prefetches, navigations, and Server Actions — made during the scope:
......
...@@ -2,6 +2,11 @@ import { nextTestSetup } from 'e2e-utils' ...@@ -2,6 +2,11 @@ import { nextTestSetup } from 'e2e-utils'
import type * as Playwright from 'playwright' import type * as Playwright from 'playwright'
import { createRouterAct } from 'router-act' import { createRouterAct } from 'router-act'
// This suite asserts directly on App Shell prefetch responses, so every
// `createRouterAct` call passes `{ includeAppShellRequests: true }`. By default
// router-act ignores App Shell requests (those with `next-router-prefetch: '3'`)
// for assertion purposes, since the App Shell is conceptually part of the route
// rather than prefetch data. These tests are the exception that opts back in.
describe('App Shell prefetching', () => { describe('App Shell prefetching', () => {
const { next, isNextDev } = nextTestSetup({ const { next, isNextDev } = nextTestSetup({
files: __dirname, files: __dirname,
...@@ -18,7 +23,7 @@ describe('App Shell prefetching', () => { ...@@ -18,7 +23,7 @@ describe('App Shell prefetching', () => {
page = p page = p
}, },
}) })
const act = createRouterAct(page) const act = createRouterAct(page, { includeAppShellRequests: true })
// Reveal the LinkAccordion for /posts/1. This caches the App Shell // Reveal the LinkAccordion for /posts/1. This caches the App Shell
// for the route — the param-independent content of the page that's // for the route — the param-independent content of the page that's
...@@ -68,7 +73,7 @@ describe('App Shell prefetching', () => { ...@@ -68,7 +73,7 @@ describe('App Shell prefetching', () => {
page = p page = p
}, },
}) })
const act = createRouterAct(page) const act = createRouterAct(page, { includeAppShellRequests: true })
// Reveal /posts/1 (default/auto prefetch). The route is allow-runtime, which // Reveal /posts/1 (default/auto prefetch). The route is allow-runtime, which
// is NOT eager, so under App Shells only the shared App Shell is prefetched. // is NOT eager, so under App Shells only the shared App Shell is prefetched.
...@@ -100,7 +105,7 @@ describe('App Shell prefetching', () => { ...@@ -100,7 +105,7 @@ describe('App Shell prefetching', () => {
page = p page = p
}, },
}) })
const act = createRouterAct(page) const act = createRouterAct(page, { includeAppShellRequests: true })
// Reveal /partial/1. /partial/[id] is fully static and opts into Partial // Reveal /partial/1. /partial/[id] is fully static and opts into Partial
// Prefetching, so this prefetches the shared app shell ("Partial app // Prefetching, so this prefetches the shared app shell ("Partial app
...@@ -136,7 +141,7 @@ describe('App Shell prefetching', () => { ...@@ -136,7 +141,7 @@ describe('App Shell prefetching', () => {
page = p page = p
}, },
}) })
const act = createRouterAct(page) const act = createRouterAct(page, { includeAppShellRequests: true })
// Reveal /eager/1. /eager/[id] opts into Partial Prefetching in "eager" // Reveal /eager/1. /eager/[id] opts into Partial Prefetching in "eager"
// mode, so this primes the shared app shell. (Because the route is eager it // mode, so this primes the shared app shell. (Because the route is eager it
...@@ -172,7 +177,7 @@ describe('App Shell prefetching', () => { ...@@ -172,7 +177,7 @@ describe('App Shell prefetching', () => {
page = p page = p
}, },
}) })
const act = createRouterAct(page) const act = createRouterAct(page, { includeAppShellRequests: true })
// /eager-instant/[id] sets BOTH unstable_instant (which alone behaves like // /eager-instant/[id] sets BOTH unstable_instant (which alone behaves like
// 'partial' — not eager) and prefetch = 'unstable_eager'. The eager // 'partial' — not eager) and prefetch = 'unstable_eager'. The eager
...@@ -204,7 +209,7 @@ describe('App Shell prefetching', () => { ...@@ -204,7 +209,7 @@ describe('App Shell prefetching', () => {
page = p page = p
}, },
}) })
const act = createRouterAct(page) const act = createRouterAct(page, { includeAppShellRequests: true })
// Reveal /partial/1 (default). /partial/[id] opts into Partial Prefetching, // Reveal /partial/1 (default). /partial/[id] opts into Partial Prefetching,
// so the default link primes the shared shell and skips the Speculative // so the default link primes the shared shell and skips the Speculative
...@@ -246,7 +251,7 @@ describe('App Shell prefetching', () => { ...@@ -246,7 +251,7 @@ describe('App Shell prefetching', () => {
page = p page = p
}, },
}) })
const act = createRouterAct(page) const act = createRouterAct(page, { includeAppShellRequests: true })
// Reveal the LinkAccordion for /static-posts/1. Two prefetch responses // Reveal the LinkAccordion for /static-posts/1. Two prefetch responses
// fire: one for the per-segment static prefetch of /static-posts/1 // fire: one for the per-segment static prefetch of /static-posts/1
......
...@@ -2,9 +2,27 @@ import type * as Playwright from 'playwright' ...@@ -2,9 +2,27 @@ import type * as Playwright from 'playwright'
import { diff } from 'jest-diff' import { diff } from 'jest-diff'
import { equals } from '@jest/expect-utils' import { equals } from '@jest/expect-utils'
// Mirrors NEXT_ROUTER_PREFETCH_HEADER from the Next.js client. App Shell
// prefetches carry the value '3' (FetchStrategy.RuntimeShell). The App Shell is
// the param/searchParam-independent chrome of a route — conceptually part of the
// route itself, not prefetch data in the way we normally think of it. By default
// we therefore exclude App Shell requests from all `act` assertion logic
// (`includes` matching, `no-requests`, `block: 'reject'`, and the "at least one
// request" check). They are still intercepted, fulfilled, and awaited so that the
// browser caches the shell and no requests are left in flight. Pass
// `includeAppShellRequests: true` to `createRouterAct` to assert on them directly
// (e.g. when testing App Shell behavior specifically).
const NEXT_ROUTER_PREFETCH_HEADER = 'next-router-prefetch'
const APP_SHELL_PREFETCH_VALUE = '3'
type Batch = { type Batch = {
pendingRequestChecks: Set<Promise<void>> pendingRequestChecks: Set<Promise<void>>
pendingRequests: Set<PendingRSCRequest> pendingRequests: Set<PendingRSCRequest>
// The number of pending requests in `pendingRequests` that are NOT App Shell
// requests. App Shell requests don't count toward the "at least one request"
// check, so we track this separately rather than scanning the set. Maintained
// in lockstep with `pendingRequests` membership.
pendingNonAppShellRequests: number
} }
type PendingRSCRequest = { type PendingRSCRequest = {
...@@ -17,6 +35,10 @@ type PendingRSCRequest = { ...@@ -17,6 +35,10 @@ type PendingRSCRequest = {
status: number status: number
}> }>
didProcess: boolean didProcess: boolean
// True if this is an App Shell prefetch request that should be ignored for
// assertion purposes (see note above). Always false when the caller passes
// `includeAppShellRequests: true`.
isAppShell: boolean
} }
let currentBatch: Batch | null = null let currentBatch: Batch | null = null
...@@ -63,8 +85,19 @@ export function createRouterAct( ...@@ -63,8 +85,19 @@ export function createRouterAct(
* provided, all error status codes are disallowed (400+). * provided, all error status codes are disallowed (400+).
*/ */
allowErrorStatusCodes?: number[] allowErrorStatusCodes?: number[]
/**
* By default, App Shell prefetch requests (those with a
* `next-router-prefetch: '3'` header) are ignored for the purposes of
* assertion matching, `no-requests`, `block: 'reject'`, and the "at least
* one request" check. They are still intercepted, fulfilled, and awaited.
*
* Set this to `true` to treat App Shell requests like any other router
* request. Use this when writing tests for App Shell behavior specifically.
*/
includeAppShellRequests?: boolean
} }
): <T>(scope: () => Promise<T> | T, config?: ActConfig) => Promise<T> { ): <T>(scope: () => Promise<T> | T, config?: ActConfig) => Promise<T> {
const includeAppShellRequests = options?.includeAppShellRequests ?? false
/** /**
* Helper function to wait for requestIdleCallback with retry logic. * Helper function to wait for requestIdleCallback with retry logic.
* Retries up to 3 times if "Execution context was destroyed" error occurs. * Retries up to 3 times if "Execution context was destroyed" error occurs.
...@@ -214,12 +247,21 @@ export function createRouterAct( ...@@ -214,12 +247,21 @@ export function createRouterAct(
headers['rsc'] !== undefined || // Matches navigations and prefetches headers['rsc'] !== undefined || // Matches navigations and prefetches
headers['next-action'] !== undefined // Matches Server Actions headers['next-action'] !== undefined // Matches Server Actions
// App Shell prefetch requests are intercepted and fulfilled like any
// other router request, but (unless the caller opts in) they don't
// participate in any assertion logic. See the note at the top of
// this file.
const isAppShell =
!includeAppShellRequests &&
headers[NEXT_ROUTER_PREFETCH_HEADER] === APP_SHELL_PREFETCH_VALUE
if (isRouterRequest) { if (isRouterRequest) {
// This request was initiated by the Next.js Router. Intercept it and // This request was initiated by the Next.js Router. Intercept it and
// add it to the current batch. // add it to the current batch.
pendingRequests.add({ pendingRequests.add({
url: request.url(), url: request.url(),
route, route,
isAppShell,
// `act` controls the timing of when responses reach the client, // `act` controls the timing of when responses reach the client,
// but it should not affect the timing of when requests reach the // but it should not affect the timing of when requests reach the
// server; we pass the request to the server the immediately. // server; we pass the request to the server the immediately.
...@@ -254,9 +296,14 @@ export function createRouterAct( ...@@ -254,9 +296,14 @@ export function createRouterAct(
})(), })(),
didProcess: false, didProcess: false,
}) })
if (onDidIssueFirstRequest !== null) { // App Shell requests don't count toward the "at least one request"
onDidIssueFirstRequest() // check, so only track and signal for non-App-Shell requests.
onDidIssueFirstRequest = null if (!isAppShell) {
batch.pendingNonAppShellRequests++
if (onDidIssueFirstRequest !== null) {
onDidIssueFirstRequest()
onDidIssueFirstRequest = null
}
} }
return return
} }
...@@ -280,6 +327,7 @@ export function createRouterAct( ...@@ -280,6 +327,7 @@ export function createRouterAct(
const orphanedRequests = batch.pendingRequests const orphanedRequests = batch.pendingRequests
batch.pendingRequests = new Set() batch.pendingRequests = new Set()
batch.pendingRequestChecks = new Set() batch.pendingRequestChecks = new Set()
batch.pendingNonAppShellRequests = 0
await Promise.all( await Promise.all(
Array.from(orphanedRequests).map((item) => item.route?.continue()) Array.from(orphanedRequests).map((item) => item.route?.continue())
) )
...@@ -297,6 +345,7 @@ export function createRouterAct( ...@@ -297,6 +345,7 @@ export function createRouterAct(
const batch: Batch = { const batch: Batch = {
pendingRequestChecks: new Set(), pendingRequestChecks: new Set(),
pendingRequests: new Set(), pendingRequests: new Set(),
pendingNonAppShellRequests: 0,
} }
currentBatch = batch currentBatch = batch
await page.route('**/*', routeHandler) await page.route('**/*', routeHandler)
...@@ -305,8 +354,12 @@ export function createRouterAct( ...@@ -305,8 +354,12 @@ export function createRouterAct(
// Call the user-provided scope function // Call the user-provided scope function
const returnValue = await scope() const returnValue = await scope()
// Wait until the first request is initiated, up to some timeout. // Wait until the first request is initiated, up to some timeout. App Shell
if (expectedResponses !== null && batch.pendingRequests.size === 0) { // requests don't count, so check the non-App-Shell pending request count.
if (
expectedResponses !== null &&
batch.pendingNonAppShellRequests === 0
) {
await new Promise<void>((resolve, reject) => { await new Promise<void>((resolve, reject) => {
const timerId = setTimeout(() => { const timerId = setTimeout(() => {
error.message = 'Timed out waiting for a request to be initiated.' error.message = 'Timed out waiting for a request to be initiated.'
...@@ -349,13 +402,21 @@ export function createRouterAct( ...@@ -349,13 +402,21 @@ export function createRouterAct(
const route = item.route const route = item.route
const url = item.url const url = item.url
// This request is being removed from `pendingRequests` for
// processing. Keep the non-App-Shell counter in lockstep. (If it ends
// up blocked and transferred to the outer batch, that batch's counter
// is incremented when the transfer happens, below.)
if (!item.isAppShell) {
batch.pendingNonAppShellRequests--
}
let shouldBlock = false let shouldBlock = false
const fulfilled = await item.result const fulfilled = await item.result
if (item.didProcess) { if (item.didProcess) {
// This response was already processed by an inner `act` call. // This response was already processed by an inner `act` call.
} else { } else {
item.didProcess = true item.didProcess = true
if (expectedResponses === null) { if (!item.isAppShell && expectedResponses === null) {
error.message = ` error.message = `
Expected no network requests to be initiated. Expected no network requests to be initiated.
...@@ -368,6 +429,8 @@ ${fulfilled.body} ...@@ -368,6 +429,8 @@ ${fulfilled.body}
throw error throw error
} }
// The error-status check applies to all requests, including App
// Shell requests — a 4xx/5xx App Shell is a real failure.
if ( if (
fulfilled.status >= 400 && fulfilled.status >= 400 &&
(allowStatuses === null || (allowStatuses === null ||
...@@ -385,7 +448,7 @@ ${fulfilled.body} ...@@ -385,7 +448,7 @@ ${fulfilled.body}
` `
throw error throw error
} }
if (forbiddenResponses !== null) { if (!item.isAppShell && forbiddenResponses !== null) {
for (const forbiddenResponse of forbiddenResponses) { for (const forbiddenResponse of forbiddenResponses) {
const includes = forbiddenResponse.includes const includes = forbiddenResponse.includes
if (fulfilled.body.includes(includes)) { if (fulfilled.body.includes(includes)) {
...@@ -401,7 +464,7 @@ ${fulfilled.body} ...@@ -401,7 +464,7 @@ ${fulfilled.body}
} }
} }
} }
if (expectedResponses !== null) { if (!item.isAppShell && expectedResponses !== null) {
// Check if this response matches any of the expectations. // Check if this response matches any of the expectations.
// //
// //
...@@ -539,7 +602,13 @@ ${fulfilled.body} ...@@ -539,7 +602,13 @@ ${fulfilled.body}
} }
})(), })(),
didProcess: false, didProcess: false,
// The target of a redirect is a navigation, not an App
// Shell prefetch.
isAppShell: false,
}) })
// Keep the counter in lockstep with the add above (drained
// and decremented on the next iteration of the while loop).
batch.pendingNonAppShellRequests++
page.off('response', handleResponse) page.off('response', handleResponse)
page.off('requestfailed', handleFailure) page.off('requestfailed', handleFailure)
resolve() resolve()
...@@ -612,6 +681,9 @@ ${fulfilled.body} ...@@ -612,6 +681,9 @@ ${fulfilled.body}
if (remaining.size !== 0 && prevBatch !== null) { if (remaining.size !== 0 && prevBatch !== null) {
for (const item of remaining) { for (const item of remaining) {
prevBatch.pendingRequests.add(item) prevBatch.pendingRequests.add(item)
if (!item.isAppShell) {
prevBatch.pendingNonAppShellRequests++
}
} }
} }
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment