Unverified Commit 86df9c75 authored by Joseph's avatar Joseph Committed by GitHub

docs: cover direct visits and client navigations in the instant() e2e example (#95803)

Reworks the instant-navigation guide's e2e testing example to cover both
ways a route is reached: a direct visit (SSR document load) and a client
navigation.

Each test wraps the navigation in `instant()` and asserts the shell
renders while the streamed content is held back, then appears after.

Also documents where the testing API is available: automatically under
`next dev`, and in a production build via
`experimental.exposeTestingApiInProductionBuild`.

Closes:
https://linear.app/vercel/issue/DOC-6477/instant-e2e-helper-for-ssr-and-soft-navs-snippets-show-difference

---------
Co-authored-by: 's avatarAurora Scharff <aurora.sofie@gmail.com>
Co-authored-by: 's avatarAurora Scharff <66901228+aurorascharff@users.noreply.github.com>
parent 47a52c0d
...@@ -295,28 +295,64 @@ yarn add -D @next/playwright @playwright/test ...@@ -295,28 +295,64 @@ yarn add -D @next/playwright @playwright/test
bun add -D @next/playwright @playwright/test bun add -D @next/playwright @playwright/test
``` ```
Then use it in a test: A route can be reached two ways, and a `<Suspense>` boundary can cover one without covering the other:
```typescript filename="e2e/navigation.test.ts" - **Initial page load**: Use `page.goto()` to test the static UI from the document response.
- **Client navigation**: Click a `<Link>` to test the destination's prefetched UI. [Runtime prefetching](/docs/app/guides/runtime-prefetching) can add request-specific content to this UI.
```typescript filename="e2e/navigation.test.ts" highlight={6-14,20-25}
import { test, expect } from '@playwright/test' import { test, expect } from '@playwright/test'
import { instant } from '@next/playwright' import { instant } from '@next/playwright'
test('product title appears instantly', async ({ page }) => { test.describe('Product page (/store/[slug])', () => {
await page.goto('/store/shoes') test('is instant on an initial page load', async ({ page, baseURL }) => {
await instant(
await instant(page, async () => { page,
await page.click('a[href="/store/hats"]') async () => {
await expect(page.locator('h1')).toContainText('Baseball Cap') await page.goto('/store/hats')
await expect(page.locator('h1')).toContainText('Baseball Cap')
await expect(page.getByText('In stock')).toHaveCount(0)
},
{ baseURL }
)
await expect(page.getByText('In stock')).toBeVisible()
}) })
// After instant() exits, dynamic content streams in test('is instant on a client navigation', async ({ page }) => {
await expect(page.locator('text=in stock')).toBeVisible() await page.goto('/store/shoes')
await instant(page, async () => {
await page.click('a[href="/store/hats"]')
await page.waitForURL((url) => url.pathname === '/store/hats')
await expect(page.locator('h1')).toContainText('Baseball Cap')
await expect(page.getByText('In stock')).toHaveCount(0)
})
await expect(page.getByText('In stock')).toBeVisible()
})
}) })
``` ```
Inside the `instant()` callback, only the static shell is visible. After the callback finishes, dynamic content streams in and you can assert on the full page. Pass Playwright's `baseURL` to `instant()` when `page.goto()` is the first navigation. The helper needs the origin before requesting the document.
Inside the callback, an initial page load shows the static UI and a client navigation shows the destination's prefetched UI. Other dynamic content remains blocked until the callback finishes.
> **Good to know:** The start of the `instant()` scope is the same as turning on **Pause on navigations** in the Navigation Inspector, and the end of the scope releases the pause the way **Resume** does.
For client navigations, wait for the destination URL before asserting on its UI. Otherwise, a shared selector can match the source page before the destination commits. If the prefetched destination cannot commit, the URL wait times out and the test fails.
Run these against `next dev`, where the testing API is enabled automatically. To run them in CI against a production build, set `exposeTestingApiInProductionBuild` so `next start` exposes the same API:
```ts filename="next.config.ts" highlight={5}
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
experimental: { exposeTestingApiInProductionBuild: true },
}
export default nextConfig
```
Focus these tests on the user flows that matter most. Run them against your dev server during development, and in CI against your build output so regressions fail the pipeline. Focus these tests on the user flows that matter most.
## Fixing a navigation that blocks ## Fixing a navigation that blocks
......
...@@ -129,12 +129,12 @@ module.exports = { ...@@ -129,12 +129,12 @@ module.exports = {
} }
``` ```
Open the Next.js DevTools and select **Navigation Inspector**, then click **Start Capturing**. While capturing is active: Open the Next.js DevTools and select **Navigation Inspector**, then turn on **Pause on navigations**. While the toggle is on:
- Refresh the page to freeze the initial static UI generated for the route, before any dynamic data streams in. - Refresh the page to freeze the initial static UI generated for the route, before any dynamic data streams in.
- Click a link to freeze the prefetched UI for the destination route. - Click a link to freeze the prefetched UI for the destination route.
When the UI is frozen, click **Continue Rendering** to let the current navigation finish while keeping the Navigation Inspector in capturing mode. Click **Stop Capturing** when you are done. Use both page refreshes and link clicks to check that your loading states look right on first visit and on navigation. When the UI is frozen, click **Resume** to let the current navigation finish. The toggle stays on, so the next refresh or link click pauses too. Turn it off when you are done. Use both page refreshes and link clicks to check that your loading states look right on first visit and on navigation.
## Testing instant navigation ## Testing instant navigation
......
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