Files
e2e/docs/frameworks/nextjs.mdx
Donny/강동윤andClaude Sonnet 5.5 d88aa99e0f docs: add a Next.js guide page (#1952)
* docs: add a Next.js guide page

One page takes a Next.js developer from `e2e init` to CI: `next dev`
locally and `next start` on the build in CI from one config, the port,
`reuseExisting`, and the Next.js problems (`allowedDevOrigins` on
127.0.0.1, the route announcer that `getByRole('alert')` also matches, a
webpack watcher that reads `.e2e/`), plus the `create-next-app` starter
and the Vercel template. The hydration accordion moves here from web.mdx;
web, cache, and example-projects link to the page, with ja and zh
translations, and the e2e skill's setup reference carries the same
guidance.

Refs ENG-1378

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: move the Next.js page into a Frameworks group

Next.js is not a platform like web, mobile, or desktop, so the page moves
to docs/frameworks/nextjs.mdx under a new Frameworks navigation group. The
web page no longer points at it from the app URL paragraph.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 10:14:53 +00:00

249 lines
7.1 KiB
Plaintext

---
title: Next.js
description: Add e2e to a Next.js app, test it on `next dev` locally and on a production build in CI.
---
import { SetupPrompt } from '../snippets/setup-prompt-card.jsx';
export const setupPrompt = `Set up e2e end-to-end tests in this Next.js app. Docs: \`https://e2e.com/docs/frameworks/nextjs.md\`
1. Run \`npx e2e init --yes\` (or the pnpm or bun equivalent for this project).
2. Replace the target in e2e.config.ts with the one on the page: \`next dev\` locally, \`next start\` when CI is set. Use the port and package manager this app uses.
3. Ask me which model to use for agent steps, and configure it as https://e2e.com/docs/models.md says.
4. Install dependencies, run the example test, and fix errors until it passes. Check the page's "Fix Next.js problems" section first.
5. Write one test for the most important user flow in this app, run it, and iterate until it passes.`;
This page adds e2e to an existing Next.js app. The runner starts `next dev`
on your machine and `next start` in CI, and the web engine tests the app in
Chromium. For a new app, [start from the example](#start-a-new-app).
<SetupPrompt>
<Prompt description={setupPrompt} children={setupPrompt} actions={["copy", "cursor"]} />
</SetupPrompt>
## Add e2e to your app
In your app's directory, run the wizard:
<CodeGroup>
```bash npm
npx e2e init
```
```bash pnpm
pnpm dlx e2e init
```
```bash bun
bunx e2e init
```
</CodeGroup>
Choose **Web (Playwright)** and a model provider. The wizard writes
`e2e.config.ts` and `tests/example.e2e.ts`, adds dependencies, and adds the
`.e2e/` run output to `.gitignore`. See the [Quickstart](/quickstart) for
each choice.
## Start the app from the config
Set `app.command` so the runner starts your app and waits until `app.url`
answers. Edit the config that `init` wrote to match. Keep its model import
and its `agents` entry:
```ts title="e2e.config.ts"
import type { E2EConfig } from 'e2e';
import { web } from '@e2e-dev/web';
// e2e reads CI the same way: unset, '', '0', and 'false' mean a local run.
const ci = !['', '0', 'false'].includes(process.env.CI?.trim().toLowerCase() ?? '');
export default {
// Keep the `agents` entry that `init` wrote.
targets: [{
engine: web(),
app: {
url: 'http://localhost:3000',
// CI serves the production build: run `next build` before `e2e run`.
command: ci
? { executable: 'npm', args: ['run', 'start'] }
: { executable: 'npm', args: ['run', 'dev'], reuseExisting: true },
},
}],
} satisfies E2EConfig;
```
- **Locally**, the runner starts `next dev`. With `reuseExisting: true`, it
uses a dev server you already started on that port.
- **In CI**, the runner starts `next start`, which serves the build.
`reuseExisting` doesn't apply there.
- **The port** in `app.url` must be the port that `dev` and `start` both
listen on. Next.js uses 3000. When one script sets `--port`, set the same
port in the other.
Then run the tests:
<CodeGroup>
```bash npm
npx e2e run
```
```bash pnpm
pnpm exec e2e run
```
```bash bun
bunx e2e run
```
</CodeGroup>
For the other `command` options, such as `log`, `env`, and port `0`, see
[Starting your app](/web#starting-your-app).
## Run in CI
Build the app before the tests. The CI service sets `CI`, so the config
starts `next start`:
<CodeGroup>
```bash npm
npm run build
npx e2e run
```
```bash pnpm
pnpm build
pnpm exec e2e run
```
```bash bun
bun run build
bunx e2e run
```
</CodeGroup>
For a full workflow, take the [GitHub Actions](/ci/github-actions#web) job
and add the build step before the e2e step. Leave out its `APP_URL`: this
config doesn't read it. For CI defaults, see
[Continuous integration](/ci).
To test each Vercel preview deployment instead, see
[Vercel Previews](/ci/vercel-previews).
## Fix Next.js problems
<AccordionGroup>
<Accordion title="The page renders but never hydrates">
Next.js 16 blocks cross-origin requests to its dev resources. When the
target opens `127.0.0.1` or `[::1]`, as
[port `0`](/web#let-the-runner-pick-the-port) does, `next dev` still
identifies as `localhost`. The page renders, locators resolve, and clicks
land, but no React handler runs.
Add the host the target opens to `allowedDevOrigins`. Use `'[::1]'` when
`app.url` opens `http://[::1]:0`:
```ts title="next.config.ts"
import type { NextConfig } from 'next';
const nextConfig: NextConfig = {
allowedDevOrigins: ['127.0.0.1'],
};
export default nextConfig;
```
A `localhost` target and a production `next start` target need no entry.
</Accordion>
<Accordion title="getByRole('alert') finds an extra element">
The App Router renders an empty `role="alert"` route announcer on every
page. `screen.getByRole('alert')` matches it too. Pick your alert by its
text:
```ts title="Test fragment"
await expect(screen.getByRole('alert').filter({ hasText: 'Enter a name first.' })).toBeVisible();
```
The agent doesn't see the route announcer, and the
[replay cache](/cache) doesn't count it as a change.
</Accordion>
<Accordion title="next dev recompiles while the tests run">
e2e writes its run output under `.e2e/`: results, logs, traces, and the
replay cache. A watcher that reads this folder can rebuild the app again
and again during a run.
- Keep the `.e2e/` entries that `init` adds to `.gitignore`. Tools that
scan the project for source files, such as Tailwind CSS, skip ignored
files.
- With webpack, the `next dev` default before Next.js 16, add `.e2e` to
the paths the watcher ignores:
```ts title="next.config.ts"
import type { NextConfig } from 'next';
const nextConfig: NextConfig = {
webpack: (config, { dev }) => {
if (dev) {
config.watchOptions = {
...config.watchOptions,
ignored: ['**/.git/**', '**/.next/**', '**/node_modules/**', '**/.e2e/**'],
};
}
return config;
},
};
export default nextConfig;
```
This list keeps the Next.js defaults. When your config already sets
`ignored`, add `'**/.e2e/**'` to it instead.
</Accordion>
</AccordionGroup>
## Start a new app
Create a Next.js App Router app with e2e already set up, from the
[`with-next` example](https://github.com/e2e-inc/e2e/tree/main/examples/with-next):
<CodeGroup>
```bash npm
npx create-next-app --example https://github.com/e2e-inc/e2e/tree/main/examples/with-next my-app
cd my-app
npm run test:e2e
```
```bash pnpm
pnpm create next-app --example https://github.com/e2e-inc/e2e/tree/main/examples/with-next my-app
cd my-app
pnpm test:e2e
```
```bash bun
bun create next-app --example https://github.com/e2e-inc/e2e/tree/main/examples/with-next my-app
cd my-app
bun run test:e2e
```
</CodeGroup>
The app has three locator tests and two agent tests. The agent tests skip
until you set `AI_GATEWAY_API_KEY`.
To deploy to Vercel and test every deployment, start from the
[Next.js with e2e template](https://github.com/e2e-inc/e2e-vercel-previews)
instead. Its README has a **Deploy** button.
## Next
<CardGroup cols={2}>
<Card title="Web" icon="globe" href="/web">
Every way to start the app, protected previews, and viewports.
</Card>
<Card title="Vercel Previews" icon="/images/integrations/vercel.svg" href="/ci/vercel-previews">
Test each preview deployment and hold production until the tests pass.
</Card>
</CardGroup>