End-to-End Testing Next.js with Playwright

The tea shop, tested in real Chrome

Testing components ended with a list of what a unit test can't check, because Next.js isn't running in it: an async Server Component, a part that streams in, a client-side navigation, and a Server Action's real request. An end-to-end test checks them from the outside. It builds and starts the whole app, opens its pages in a real browser, and clicks and types the way a visitor does.

Playwright is the tool Next.js's docs set up for it (version 1.64.1 on October 30, 2026). Its tests read like the React course's: find by role and label, click, check (Testing React components, and Testing the DOM & end to end for Playwright on its own). Here is the tea shop with three files of Playwright tests, a real Next.js 16.4.3 project. The recorder ran npx playwright test in it the way a job in continuous integration (CI) does: a server that runs the tests on every change, then built it again and asked next start for two pages.

1import { defineConfig, devices } from "@playwright/test";2 3const port = Number(process.env.PORT ?? 3000);4const baseURL = `http://localhost:${port}`;5const stockURL = `http://localhost:${port + 1}`;6 7export default defineConfig({8  testDir: "./e2e",9  forbidOnly: !!process.env.CI,10  retries: process.env.CI ? 2 : 0,11  workers: process.env.CI ? 1 : undefined,12  reporter: "list",13  use: { baseURL, trace: "on-first-retry" },14  projects: [{ name: "chrome", use: { ...devices["Desktop Chrome"], channel: "chrome" } }],15  webServer: [16    {17      command: "node e2e/stock-api.mjs",18      url: `${stockURL}/stock/mint`,19      env: { STOCK_PORT: String(port + 1) },20      reuseExistingServer: false,21    },22    {23      command: "npm run build && npm run start",24      url: baseURL,25      env: { STOCK_API_URL: stockURL },26      reuseExistingServer: false,27      timeout: 120_000,28    },29  ],30});

$ npx playwright testRunning 6 tests using 1 worker   ✓  1 [chrome] › e2e/navigation.spec.ts:4:5 › a link keeps what you typed in the layout  ✓  2 [chrome] › e2e/navigation.spec.ts:19:5 › a reload starts the layout again  ✓  3 [chrome] › e2e/newsletter.spec.ts:4:5 › joins with JavaScript: one POST, answered with an RSC payload  ✓  4 [chrome] › e2e/newsletter.spec.ts:20:7 › without JavaScript › joins with a plain form post and a 303  ✓  5 [chrome] › e2e/teas.spec.ts:4:5 › the teas page lists every tea  ✓  6 [chrome] › e2e/teas.spec.ts:10:5 › the stock streams in after its loading message   6 passed $ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (10/10)  Finalizing page optimization ... Route (app)┌ ○ /├ ○ /_not-found├ ○ /newsletter├ ○ /newsletter/thanks├ ○ /teas└   /teas/[id]  ├ ◐ /teas/[id]  ├ ◐ /teas/green  ├ ◐ /teas/mint  └ ◐ /teas/lemon ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

Open the Terminal tab. Playwright printed Running 6 tests using 1 worker, then a ✓ for each test, in file order: two in e2e/navigation.spec.ts, two in e2e/newsletter.spec.ts and two in e2e/teas.spec.ts, and 6 passed. Before the first test, Playwright had built the app and started it, because of line 23 of playwright.config.ts. In each test, it opened the Google Chrome installed on the computer (line 14), not a browser of its own. After the tests, the recorder's own $ next build printed the routes: ○ /teas, and ◐ /teas/mint with its stock streamed in.

Playwright against next build and next start

npm init playwright@latest asks a few questions and writes a config, an example test and a GitHub Actions workflow. To add only the test runner yourself:

npm install --save-dev @playwright/test

By default, Playwright runs its own builds of Chromium, Firefox and WebKit, which npx playwright install downloads. This config uses the Google Chrome already on the computer instead, so nothing is downloaded. That tests one browser: to check Firefox and Safari's engine too, add projects that use Playwright's Firefox and WebKit. The whole config, from the tea shop's project:

1import { defineConfig, devices } from "@playwright/test";2 3const port = Number(process.env.PORT ?? 3000);4const baseURL = `http://localhost:${port}`;5const stockURL = `http://localhost:${port + 1}`;6 7export default defineConfig({8  testDir: "./e2e",9  forbidOnly: !!process.env.CI,10  retries: process.env.CI ? 2 : 0,11  workers: process.env.CI ? 1 : undefined,12  reporter: "list",13  use: { baseURL, trace: "on-first-retry" },14  projects: [{ name: "chrome", use: { ...devices["Desktop Chrome"], channel: "chrome" } }],15  webServer: [16    {17      command: "node e2e/stock-api.mjs",18      url: `${stockURL}/stock/mint`,19      env: { STOCK_PORT: String(port + 1) },20      reuseExistingServer: false,21    },22    {23      command: "npm run build && npm run start",24      url: baseURL,25      env: { STOCK_API_URL: stockURL },26      reuseExistingServer: false,27      timeout: 120_000,28    },29  ],30});31 

• Lines 3 to 5 pick the addresses. The app listens on PORT, 3000 unless something sets it, and the stand-in stock API on the port after it.
• Lines 15 to 29 are webServer: the programs Playwright starts before the first test and stops after the last. The second one, on lines 22 to 28, runs npm run build && npm run start: next build, then next start. Line 24 tells Playwright to wait until that address answers, and line 27 gives the build two minutes. Line 25 passes the stand-in's address to the app in STOCK_API_URL.
• Lines 20 and 26 set reuseExistingServer: false: Playwright always starts its own programs. If something already answers at one of the addresses, like a next dev you left running, the run stops with an error instead of testing it. So every run tests a fresh build of your current code.
• Lines 9 to 11 change three settings when CI is set, as it is on GitHub's runners and in the recordings.

Next.js's Playwright guide recommends testing the production build, because that's what visitors get. next dev compiles each page the first time it's asked for and adds checks that only run in development, so a test against it waits longer and checks something else. Each row is one setting, what it does, and why it matters for a Next.js app:

Async Server Components, end to end

In the last lesson, Testing Library couldn't render the async teas page: React DOM printed that it was an async Client Component, and the test failed. Here is the same page, with a link on each tea, and its first end-to-end test:

1import { expect, test } from "@playwright/test";2import { holdStock, releaseStock } from "./stock";3 4test("the teas page lists every tea", async ({ page }) => {5  await page.goto("/teas");6  await expect(page.getByRole("heading", { name: "Our teas" })).toBeVisible();7  await expect(page.getByRole("listitem")).toHaveText(["Green tea: $4", "Mint tea: $3", "Lemon tea: $3"]);8});9 10test("the stock streams in after its loading message", async ({ page, request }) => {11  await holdStock(request);12  await page.goto("/teas/mint", { waitUntil: "commit" });13  await expect(page.getByRole("heading", { name: "Mint tea" })).toBeVisible();14  await expect(page.getByText("Checking stock…")).toBeVisible();15  await releaseStock(request);16  await expect(page.getByText("12 boxes in stock")).toBeVisible();17  await expect(page.getByText("Checking stock…")).toBeHidden();18});19 

Line 5 opens /teas on the running app. Playwright adds the path to baseURL from the config, and waits for the page's load event. Line 6 checks the heading. Line 7 checks that the list items, in order, say exactly the three teas. Next.js rendered the async TeasPage on the server, as it does for every visitor, so the test needs no trick and no mock: the report shows ✓ 5 [chrome] › e2e/teas.spec.ts:4:5 › the teas page lists every tea.

Open the Browser tab of the example above and pick /teas: that's the page next start sent, the same three teas. An end-to-end test doesn't care how a page was made, prerendered as ○ or streamed as ◐. It checks what the visitor ends up with.

Streaming and loading states, without fixed waits

The Mint tea page shows its name at once and the stock when the supplier answers, with Checking stock… in between, as Streaming showed:

1import { Suspense } from "react";2import { notFound } from "next/navigation";3import { connection } from "next/server";4import { teas } from "@/lib/teas";5 6export function generateStaticParams() {7  return teas.map((tea) => ({ id: tea.id }));8}9 10async function Stock({ id }: { id: string }) {11  await connection();12  const response = await fetch(`${process.env.STOCK_API_URL}/stock/${id}`);13  const { boxes } = await response.json();14  return <p>{boxes} boxes in stock</p>;15}16 17export default async function TeaPage({ params }: PageProps<"/teas/[id]">) {18  const { id } = await params;19  const tea = teas.find((item) => item.id === id);20  if (!tea) notFound();21  return (22    <main>23      <h1>{tea.name}</h1>24      <Suspense fallback={<p>Checking stock…</p>}>25        <Stock id={tea.id} />26      </Suspense>27    </main>28  );29}30 

Line 11, connection(), makes the stock part wait for a request, so it's never made during the build. Line 12 asks the supplier, at STOCK_API_URL, for each request. Lines 24 to 26 show Checking stock… until it answers. The recorder's own request shows both states: in the Network tab, the first HTML of /teas/mint had Checking stock…, and the streamed part replaced it with 12 boxes in stock.

To test the loading message, the test must look while it's on the screen. How long that is depends on the supplier, and on how busy the computer is. A test that waits two seconds and then looks will pass on one machine and fail on a slower one. So the test controls the supplier instead. In the tests, the supplier is a stand-in, which the config starts on lines 16 to 21:

1// A stand-in for the supplier's stock API, for end-to-end tests only.2// POST /hold makes stock requests wait; POST /release answers them.3import { createServer } from "node:http";4 5let held = false;6const waiting = [];7 8createServer((request, response) => {9  if (request.method === "POST" && request.url === "/hold") {10    held = true;11    return response.end("held");12  }13  if (request.method === "POST" && request.url === "/release") {14    held = false;15    for (const answer of waiting.splice(0)) answer();16    return response.end("released");17  }18  const answer = () => response.end(JSON.stringify({ boxes: 12 }));19  if (held) waiting.push(answer);20  else answer();21}).listen(Number(process.env.STOCK_PORT));22 

After POST /hold (lines 9 to 12), each stock request waits in a list (line 19). POST /release answers them all, with 12 boxes (lines 13 to 17). Two small functions in e2e/stock.ts send those posts:

import type { APIRequestContext } from "@playwright/test";

// The stand-in stock API listens on the port after the app's (see playwright.config.ts).
const stockURL = `http://localhost:${Number(process.env.PORT ?? 3000) + 1}`;

export async function holdStock(request: APIRequestContext) {
  await request.post(`${stockURL}/hold`);
}

export async function releaseStock(request: APIRequestContext) {
  await request.post(`${stockURL}/release`);
}

Now the second test of e2e/teas.spec.ts, above, reads like what a visitor sees. Line 11 holds the stock. Line 12 opens the page with waitUntil: "commit". Playwright's docs say goto waits for the load event by default, and the page doesn't finish loading until its last streamed part has arrived, which the hold prevents. With commit, goto returns as soon as the answer starts. Lines 13 and 14 check the heading and the loading message. Line 15 releases the stock, line 16 waits for 12 boxes in stock, and line 17 checks that the loading message is gone.

Every check waited for what it checks. expect(…).toBeVisible() looks again and again until the element is visible, for up to 5 seconds by default. Each row is one way to wait in Playwright, and what it waits for:

Testing a client-side navigation

When a visitor clicks a Link, Next.js's router swaps the page in place, without loading a new HTML document, and the layout stays on the screen with its state (Linking and navigating). The tea shop's layout has a search box, a Client Component that keeps what was typed in state.

First, wait for hydration. The HTML arrives with the search box and the links already drawn, but they only behave like the app once React has hydrated the page: run the Client Components in the browser and attached their event handlers to that HTML. Before then, typing changes the box without React knowing, a click on a link loads a whole new page, and a form posts the way it does without JavaScript. Playwright waits until an element is visible, still and enabled before it clicks, not until React has hydrated it. On a fast computer, hydration usually wins the race; on a busy CI server, the test can click first and fail now and then. So the shop marks the page once it's hydrated:

1"use client";2 3import { useEffect } from "react";4 5// Effects run only after React has hydrated this part of the page, so end-to-end6// tests can wait for this attribute before they click or type.7export default function HydrationMarker() {8  useEffect(() => {9    document.documentElement.dataset.hydrated = "true";10  }, []);11  return null;12}13 

An Effect runs only after React has hydrated the component, so lines 8 to 10 set data-hydrated="true" on <html> at the moment the layout, and everything it renders outside a Suspense boundary, works. (A control inside a Suspense boundary can hydrate later; give it a marker of its own.) The tests wait for the attribute with one line:

1import { expect, type Page } from "@playwright/test";2 3// HydrationMarker sets data-hydrated on <html> once React has attached the page's event handlers.4export async function waitForHydration(page: Page) {5  await expect(page.locator("html")).toHaveAttribute("data-hydrated", "true");6}7 

Line 5 is an expect, so it checks again and again until the attribute is there, for up to 5 seconds. Every test that types or clicks something that needs JavaScript calls it first. Now the navigation tests:

1import { expect, test } from "@playwright/test";2import { waitForHydration } from "./hydration";3 4test("a link keeps what you typed in the layout", async ({ page }) => {5  await page.goto("/");6  await waitForHydration(page);7  await page.getByLabel("Search teas").fill("mint");8  const documents: string[] = [];9  page.on("request", (request) => {10    if (request.resourceType() === "document") documents.push(request.url());11  });12  await page.getByRole("link", { name: "Teas", exact: true }).click();13  await expect(page).toHaveURL("/teas");14  await expect(page.getByRole("heading", { name: "Our teas" })).toBeVisible();15  await expect(page.getByLabel("Search teas")).toHaveValue("mint");16  expect(documents).toEqual([]);17});18 19test("a reload starts the layout again", async ({ page }) => {20  await page.goto("/");21  await waitForHydration(page);22  await page.getByLabel("Search teas").fill("mint");23  await page.reload();24  await waitForHydration(page);25  await expect(page.getByLabel("Search teas")).toHaveValue("");26});27 

Line 6 waits for hydration, and line 7 types mint into the search box. Lines 8 to 11 start a list of every HTML document the page asks for from now on. Line 12 clicks the Teas link; exact: true keeps it from matching a longer name. Lines 13 and 14 wait for the new address and heading. Line 15 checks that the search box still says mint, and line 16 that the click loaded no new document. The second test reloads the page on line 23: a whole page load, which starts the layout again, so after hydration line 25 finds the box empty.

Both passed, so the layout kept its state through the click and lost it in the reload. A unit test with next/navigation mocked can check that a component asked for /teas; only the real router can show that the layout stayed.

Forms and Server Actions, with and without JavaScript

The newsletter form's action is a Server Action, join, which redirects to a thanks page (Server Actions). Anyone may join, so it checks the email, not who is asking, and the list is a stand-in. The form works before the page's JavaScript has loaded, and differently after. One test for each:

1import { expect, test } from "@playwright/test";2import { waitForHydration } from "./hydration";3 4test("joins with JavaScript: one POST, answered with an RSC payload", async ({ page }) => {5  await page.goto("/newsletter");6  await waitForHydration(page);7  await page.getByLabel("Email").fill("asha@example.com");8  const answer = page.waitForResponse((response) => response.request().method() === "POST");9  await page.getByRole("button", { name: "Join" }).click();10  const response = await answer;11  expect(response.status()).toBe(200);12  expect(response.headers()["content-type"]).toContain("text/x-component");13  await expect(page.getByRole("heading", { name: "Thanks for joining" })).toBeVisible();14  await expect(page).toHaveURL("/newsletter/thanks");15});16 17test.describe("without JavaScript", () => {18  test.use({ javaScriptEnabled: false });19 20  test("joins with a plain form post and a 303", async ({ page }) => {21    await page.goto("/newsletter");22    await page.getByLabel("Email").fill("ben@example.com");23    const answer = page.waitForResponse((response) => response.request().method() === "POST");24    await page.getByRole("button", { name: "Join" }).click();25    expect((await answer).status()).toBe(303);26    await expect(page.getByRole("heading", { name: "Thanks for joining" })).toBeVisible();27    await expect(page).toHaveURL("/newsletter/thanks");28  });29});30 

In the first test, line 6 waits for hydration: without it, the click could post the form before React handles it, and the test would get the answer the second test expects. Line 8 starts waiting for the page's next POST before the click, so it can't miss it. Lines 11 and 12 check its answer: status 200, with the type text/x-component, an RSC payload: the React data Next.js's router uses to update the page, instead of a new HTML page. With JavaScript, the router sent the action itself and got the redirect back as that data, in one round trip. Lines 13 and 14 check the thanks page and its address.

Line 18 turns JavaScript off for every test in its describe block, as for a visitor whose JavaScript hasn't loaded yet. There's nothing to hydrate, so this test doesn't wait for it. The browser posts the form itself, and line 25 checks the answer: 303, a redirect the browser follows to the thanks page. Both passed: the same form, the same action, two different journeys.

Both tests also passed through Next.js's action layer, which a unit test skips: the action was found by its id, and its origin check passed, because the browser sent the post from the app's own page.

Signing in once with storageState

The account pages from Authentication need a signed-in visitor. Signing in through the form in every test is slow and repeats the same steps. Playwright can sign in once, save the browser's cookies to a file, and start other tests from it. That saved state is storageState:

1import { expect, test as setup } from "@playwright/test";2import { waitForHydration } from "./hydration";3 4const asha = "playwright/.auth/asha.json";5 6setup("sign in as Asha", async ({ page }) => {7  await page.goto("/sign-in");8  await waitForHydration(page);9  await page.getByLabel("Email").fill("asha@example.com");10  // Asha's password in the stand-in users table: a test fixture, never a real account's.11  await page.getByLabel("Password").fill("green-tea-123");12  await page.getByRole("button", { name: "Sign in" }).click();13  await expect(page.getByText("Signed in as Asha")).toBeVisible();14  await page.context().storageState({ path: asha });15});

$ npx playwright testRunning 3 tests using 1 worker   ✓  1 [setup] › e2e/auth.setup.ts:6:6 › sign in as Asha  ✓  2 [chrome] › e2e/account.spec.ts:3:5 › Asha sees her orders  ✓  3 [chrome] › e2e/account.spec.ts:12:7 › a visitor who isn't signed in › is asked to sign in   3 passed $ next build▲ Next.js 16.4.3 (Turbopack)- Environments: .env- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (5/5)  Finalizing page optimization ... Route (app)┌ ○ /├ ○ /_not-found├ ◐ /account└ ○ /sign-in ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

e2e/auth.setup.ts opens the real sign-in page (line 7) and waits for hydration (line 8), as the shop's tests do; this layout has the same marker. It fills in Asha's email and password (lines 9 and 11) and clicks Sign in (line 12). The password is the stand-in users table's, a fixture: fixed data made only for tests, never a real account's. Line 13 waits until the account page says Signed in as Asha, so the session cookie is set. Line 14 saves the browser's cookies to the file on line 4.

In playwright.config.ts, line 14 makes a setup project for files ending in .setup.ts. The chrome project, on lines 15 to 19, starts each test's browser from playwright/.auth/asha.json (line 17), and line 18 makes it run after setup. In e2e/account.spec.ts, the first test opens /account already signed in. The second, in a describe block whose line 10 sets an empty storageState, starts with no cookies and is asked to sign in. The Terminal tab shows the order: [setup] first, then the two [chrome] tests.

The saved file holds a working session cookie: anyone who has it is signed in as Asha until the session ends. Keep it out of git. The project's .gitignore does:

1# Dependencies, build output and secrets (create-next-app's .gitignore, shortened)2/node_modules3/.next/4.env*5 6# Playwright: the saved sign-in, a working session cookie, and each run's results7/playwright/.auth/8/test-results/9/playwright-report/10 

Line 7 keeps playwright/.auth out, and lines 8 and 9 the folders each run writes. Line 4 keeps .env files out too: the session secret in this project's .env is the Authentication lesson's recording fixture. In CI, the app reads a secret made for tests from the job's environment instead.

Running the tests in CI

A test is most useful when it runs on every change, before anyone merges it. In GitHub Actions, a workflow file does it. This is the workflow Playwright's own setup writes, changed for this config (not recorded: it runs on GitHub's computers):

1name: End-to-end tests2on:3  push:4    branches: [main]5  pull_request:6    branches: [main]7jobs:8  e2e:9    runs-on: ubuntu-latest10    steps:11      - uses: actions/checkout@v612      - uses: actions/setup-node@v613        with:14          node-version: lts/*15      - run: npm ci16      - run: npx playwright install --with-deps chrome17      - run: npx playwright test18        env:19          SESSION_SECRET: ${{ secrets.TEST_SESSION_SECRET }}20      - uses: actions/upload-artifact@v421        if: ${{ !cancelled() }}22        with:23          name: test-results24          path: test-results/25          retention-days: 3026 

Lines 11 to 15 check out the code, set up Node.js and install the packages. Line 16 installs Google Chrome and what it needs on Linux, for channel: "chrome". Line 17 runs the same command as the recordings, and GitHub sets CI on its runners, so the config's CI settings apply. Line 19 gives the app a session secret from the repository's secrets; webServer passes the job's environment on to next build and next start. Lines 20 to 25 keep test-results/ after the run, failed or not, unless it was cancelled.

Here is what a failure looks like in CI. Pick each run and read the Terminal tab:

1import { expect, test } from "@playwright/test";2import { holdStock, releaseStock } from "./stock";3 4test("the teas page lists every tea", async ({ page }) => {5  await page.goto("/teas");6  await expect(page.getByRole("heading", { name: "Our teas" })).toBeVisible();7  await expect(page.getByRole("listitem")).toHaveText(["Green tea: $4", "Mint tea: $3", "Lemon tea: $3"]);8});9 10test("the stock streams in after its loading message", async ({ page, request }) => {11  await holdStock(request);12  await page.goto("/teas/mint", { waitUntil: "commit" });13  await expect(page.getByRole("heading", { name: "Mint tea" })).toBeVisible();14  await expect(page.getByText("Checking stock…")).toBeVisible();15  await releaseStock(request);16  await expect(page.getByText("12 boxes in stock")).toBeVisible();17  await expect(page.getByText("Checking stock…")).toBeHidden();18});

$ npx playwright testRunning 6 tests using 1 worker   ✓  1 [chrome] › e2e/navigation.spec.ts:4:5 › a link keeps what you typed in the layout  ✓  2 [chrome] › e2e/navigation.spec.ts:19:5 › a reload starts the layout again  ✓  3 [chrome] › e2e/newsletter.spec.ts:4:5 › joins with JavaScript: one POST, answered with an RSC payload  ✓  4 [chrome] › e2e/newsletter.spec.ts:20:7 › without JavaScript › joins with a plain form post and a 303  ✓  5 [chrome] › e2e/teas.spec.ts:4:5 › the teas page lists every tea  ✓  6 [chrome] › e2e/teas.spec.ts:10:5 › the stock streams in after its loading message   6 passed $ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (10/10)  Finalizing page optimization ... Route (app)┌ ○ /├ ○ /_not-found├ ○ /newsletter├ ○ /newsletter/thanks├ ○ /teas└   /teas/[id]  ├ ◐ /teas/[id]  ├ ◐ /teas/green  ├ ◐ /teas/mint  └ ◐ /teas/lemon ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

The failing test ran three times: once, then (retry #1) and (retry #2), because of retries: 2. A test that fails and then passes on a retry is marked flaky, which is worth fixing too. Each failure printed the locator, the 5-second timeout, and the line. Each attempt also wrote an error-context.md: in Playwright 1.64.1, a Markdown file with the error, a snapshot of the page as a tree of roles and names, and the test's code. The first retry also saved trace.zip, because of trace: "on-first-retry". Download the job's test-results and open the trace with npx playwright show-trace: it steps through every action, with the page, its network requests and the console at each one.

Does this line wait for the right thing?

Most flaky end-to-end tests wait for the wrong thing: a fixed time, a quiet network, a button that's drawn but not hydrated, or nothing at all. This is the kind of line to look for in a review:

await page.goto("/teas/mint");
await page.waitForTimeout(2000);
expect(await page.getByText("12 boxes in stock").isVisible()).toBe(true);

Line 2 waits two seconds, whether the stock took one second or three, and line 3 looks once. Sort each line from the tea shop's tests and from code like this:

A good mix for the tea shop: Vitest tests for every component, action and helper, and a handful of end-to-end tests for the journeys visitors take: browse the teas, open one, sign in, join the newsletter. Each journey is worth more than a dozen checks of one page, and each end-to-end test takes seconds where a unit test takes milliseconds.

Common mix-ups

• "End-to-end tests should run against next dev." Next.js's guide recommends the production build: next build, then next start, as visitors get it.
• "A short waitForTimeout makes a streaming test work." It makes it pass on fast machines. Control what the page waits for, and use expect, which waits for the thing itself.
• "page.goto returns as soon as the page shows something." By default it waits for load, after the last streamed part. Use waitUntil: "commit" to check what shows first.
• "Server Actions can't work without JavaScript." A form whose action is one posts like any form, and the redirect comes back as a 303. The recorded test passed with JavaScript off.
• "Each test should sign in through the form." Sign in once in a setup project and reuse its storageState; test the sign-in form itself in one test.
• "Playwright waits until the page is ready before it clicks." It waits until the element is visible, still and enabled, not until React has hydrated it. Wait for a hydration marker first.
• "Playwright always downloads its own browsers." With channel: "chrome", it drives the installed Google Chrome.

Practice exercises

These exercises are about Next.js projects and their tests, which can't run inside this page. Answer first, then use the hints.

import { defineConfig, devices } from "@playwright/test";

const port = Number(process.env.PORT ?? 3000);
const baseURL = `http://localhost:${port}`;
const stockURL = `http://localhost:${port + 1}`;

export default defineConfig({
  testDir: "./e2e",
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: "list",
  use: { baseURL, trace: "on-first-retry" },
  projects: [{ name: "chrome", use: { ...devices["Desktop Chrome"], channel: "chrome" } }],
  webServer: [
    {
      command: "node e2e/stock-api.mjs",
      url: `${stockURL}/stock/mint`,
      env: { STOCK_PORT: String(port + 1) },
      reuseExistingServer: false,
    },
    {
      command: "npm run build && npm run start",
      url: baseURL,
      env: { STOCK_API_URL: stockURL },
      reuseExistingServer: false,
      timeout: 120_000,
    },
  ],
});

import { expect, test } from "@playwright/test";
import { holdStock, releaseStock } from "./stock";

test("the teas page lists every tea", async ({ page }) => {
  await page.goto("/teas");
  await expect(page.getByRole("heading", { name: "Our teas" })).toBeVisible();
  await expect(page.getByRole("listitem")).toHaveText(["Green tea: $4", "Mint tea: $3", "Lemon tea: $3"]);
});

test("the stock streams in after its loading message", async ({ page, request }) => {
  await holdStock(request);
  await page.goto("/teas/mint", { waitUntil: "commit" });
  await expect(page.getByRole("heading", { name: "Mint tea" })).toBeVisible();
  await expect(page.getByText("Checking stock…")).toBeVisible();
  await releaseStock(request);
  await expect(page.getByText("12 boxes in stock")).toBeVisible();
  await expect(page.getByText("Checking stock…")).toBeHidden();
});

import { expect, test } from "@playwright/test";
import { waitForHydration } from "./hydration";

test("a link keeps what you typed in the layout", async ({ page }) => {
  await page.goto("/");
  await waitForHydration(page);
  await page.getByLabel("Search teas").fill("mint");
  const documents: string[] = [];
  page.on("request", (request) => {
    if (request.resourceType() === "document") documents.push(request.url());
  });
  await page.getByRole("link", { name: "Teas", exact: true }).click();
  await expect(page).toHaveURL("/teas");
  await expect(page.getByRole("heading", { name: "Our teas" })).toBeVisible();
  await expect(page.getByLabel("Search teas")).toHaveValue("mint");
  expect(documents).toEqual([]);
});

test("a reload starts the layout again", async ({ page }) => {
  await page.goto("/");
  await waitForHydration(page);
  await page.getByLabel("Search teas").fill("mint");
  await page.reload();
  await waitForHydration(page);
  await expect(page.getByLabel("Search teas")).toHaveValue("");
});

import { expect, test } from "@playwright/test";
import { waitForHydration } from "./hydration";

test("joins with JavaScript: one POST, answered with an RSC payload", async ({ page }) => {
  await page.goto("/newsletter");
  await waitForHydration(page);
  await page.getByLabel("Email").fill("asha@example.com");
  const answer = page.waitForResponse((response) => response.request().method() === "POST");
  await page.getByRole("button", { name: "Join" }).click();
  const response = await answer;
  expect(response.status()).toBe(200);
  expect(response.headers()["content-type"]).toContain("text/x-component");
  await expect(page.getByRole("heading", { name: "Thanks for joining" })).toBeVisible();
  await expect(page).toHaveURL("/newsletter/thanks");
});

test.describe("without JavaScript", () => {
  test.use({ javaScriptEnabled: false });

  test("joins with a plain form post and a 303", async ({ page }) => {
    await page.goto("/newsletter");
    await page.getByLabel("Email").fill("ben@example.com");
    const answer = page.waitForResponse((response) => response.request().method() === "POST");
    await page.getByRole("button", { name: "Join" }).click();
    expect((await answer).status()).toBe(303);
    await expect(page.getByRole("heading", { name: "Thanks for joining" })).toBeVisible();
    await expect(page).toHaveURL("/newsletter/thanks");
  });
});

await page.goto("/teas/mint");
await page.waitForTimeout(2000);
expect(await page.getByText("12 boxes in stock").isVisible()).toBe(true);

await page.goto("/teas/mint");
await expect(page.getByText("12 boxes in stock")).toBeVisible();

import { expect, test } from "@playwright/test";

test("Asha sees her orders", async ({ page }) => {
  await page.goto("/account");
  await expect(page.getByText("Signed in as Asha")).toBeVisible();
  await expect(page.getByRole("listitem")).toHaveText(["2 boxes of Mint tea", "3 boxes of Green tea"]);
});

test.describe("a visitor who isn't signed in", () => {
  test.use({ storageState: { cookies: [], origins: [] } });

  test("is asked to sign in", async ({ page }) => {
    await page.goto("/account");
    await expect(page.getByText("You're not signed in.")).toBeVisible();
  });
});

Check your understanding

Key takeaways

• Let Playwright's webServer run next build and next start, and test the production build in the Chrome visitors use.
• Async Server Components need nothing special end to end: open the page and check what it shows.
• For a streamed part, control what it waits for, open the page with waitUntil: "commit", check the fallback, release, and check the content. Never wait a fixed time.
• Before a test clicks or types something that needs JavaScript, wait until React has hydrated the page: Playwright's own waiting doesn't cover it.
• A client-side navigation keeps the layout's state and loads no new document; a reload does neither. A Server Action form answers 200 with an RSC payload with JavaScript, and 303 without.
• Sign in once in a setup project and reuse its storageState. In CI, retries and a trace on the first retry show what went wrong.

Coming next: Debugging. The error overlay, the server's debugger and the browser's DevTools, for when a test tells you something is wrong.