Files
e2e/docs/web.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

311 lines
11 KiB
Plaintext

---
title: Web
description: Point the web engine at your app or let the runner start it, and run a suite at several viewport sizes.
"og:image": "https://e2e.com/docs/images/og/web.png?v=e860636537"
"twitter:image": "https://e2e.com/docs/images/og/web.png?v=e860636537"
---
`@e2e-dev/web` runs tests in a browser against your app's URL. For routes,
cookies, dialogs, and downloads, see [Working with the browser](/browser).
## Starting your app
Set your app's URL in the target's `app`. `app.open('/path')` resolves
against it:
```ts title="Target fragment"
engine: web(),
app: { url: process.env.APP_URL ?? 'http://localhost:3000' },
```
A URL without a scheme uses HTTPS, or HTTP for a loopback host. Plain HTTP
works only on a loopback host.
### Let the runner start it
Add `app.command` and the runner starts the dev server. It waits until
`app.url` answers, and stops a server it started when the run ends, fails, or
is interrupted:
```ts title="e2e.config.ts"
import type { E2EConfig } from 'e2e';
import { web } from '@e2e-dev/web';
export default {
targets: [{
engine: web(),
app: {
url: process.env.APP_URL ?? 'http://localhost:3000',
command: {
executable: 'npm',
args: ['run', 'dev'],
reuseExisting: true,
log: '.e2e/logs/app.log',
},
},
}],
} satisfies E2EConfig;
```
```text
✓ target "web" command at http://localhost:3000/ ready 1.20s
```
The command runs without a shell: `executable` comes from `PATH` and `args`
pass as written. The child gets only `PATH`, `HOME`, the temp-directory
variables, `inheritEnv`, and `env`.
| Option | Purpose |
| --- | --- |
| `reuseExisting: true` | Use a server that already runs, such as one an [MCP session](/mcp-server#run-tests-next-to-a-session) started. In CI, e2e ignores it, and a server that already answers is `APP_ALREADY_RUNNING`. |
| `log` | Save the app's stdout and stderr to a project-relative file. A startup error, or an unexpected exit during `e2e run`, quotes the lines any process appended to the file since the command started. A log of up to 40 lines inside 8 KiB is quoted whole; otherwise the quote keeps up to 20 lines from each end, with `[startup output omitted]` between them, and for a log past 8 KiB those lines come from its first and last 4 KiB. `command.env` and `inheritEnv` values of at least four characters are redacted from the quote. The file itself is not redacted. |
| `env` | Environment variables for the app. |
| `inheritEnv` | Host variables to pass through when set, by name or prefix: `['DATABASE_URL', 'STRIPE_*']`. `env` wins over them. |
| `startupTimeout` | How long to wait for the app to answer. Default 60 seconds. |
| `readyUrl` | Set beside `command`, not in it, to probe a health endpoint instead of `app.url`. |
See the [command reference](/reference/config#command) for all options.
<Note>
The runner starts only `app.command`. Start databases, mocks, and other
services before the run, or make `app.command` a script that starts them
and serves the app. A services API returns in a later release.
</Note>
### Let the runner pick the port
Use port `0` to run several checkouts without a port conflict. The runner
picks a free port and replaces `{port}` in the command's `args` and `env`:
```ts title="Target fragment"
engine: web(),
app: {
url: 'http://127.0.0.1:0',
command: { executable: 'pnpm', args: ['dev', '--port', '{port}'], env: { PORT: '{port}' } },
},
```
- Write `127.0.0.1` or `[::1]`, the address the command binds.
`localhost:0` is rejected.
- Tests read the URL with the real port from `app.baseUrl`.
- Cache entries stay valid when the port changes.
- `reuseExisting` doesn't work with port `0`.
- A Next.js dev server needs an `allowedDevOrigins` entry for the host. See
[Next.js](/frameworks/nextjs#fix-next-js-problems).
See [free ports](/reference/config#free-ports).
## Protected previews
Use `headers` to open a protected preview or skip a tunnel's warning page.
For example, a Vercel preview takes a protection bypass header:
```ts title="Target fragment"
engine: web({
headers: {
'x-vercel-protection-bypass': process.env.VERCEL_AUTOMATION_BYPASS_SECRET ?? '',
},
}),
app: {
url: process.env.PREVIEW_URL ?? 'http://localhost:3000',
identity: 'storefront',
},
```
The browser adds `headers` only to requests that start at the origin of
`app.url`: its scheme, host, and port. A request keeps them through its
redirects, to any origin. To add them for another origin, such as an API
host behind the same gate, list it in `credentialOrigins`. See
[request credentials](/reference/security#request-credentials). For ngrok,
use `'ngrok-skip-browser-warning': '1'`.
`app.identity` keeps the cache identity stable when the preview URL changes.
<Note>
Setting `headers` turns off the browser's HTTP cache and blocks service
workers.
</Note>
Use `basicAuth` for HTTP basic authentication. The browser answers a `401`
challenge from the origin of `app.url`, and from each origin in
`credentialOrigins`. WebKit answers any origin when one of those is on a
default port, such as an `https://` URL with no port, or has an IPv6 host.
Declare the password under `secrets` and pass `secrets.get(name)`:
```ts title="e2e.config.ts"
import type { E2EConfig } from 'e2e';
import { secrets } from 'e2e';
import { web } from '@e2e-dev/web';
export default {
targets: [
{
engine: web({
basicAuth: { username: 'preview', password: secrets.get('previewPassword') },
}),
app: { url: 'https://staging.example.com' },
},
],
secrets: { previewPassword: () => process.env.PREVIEW_PASSWORD ?? '' },
} satisfies E2EConfig;
```
The engine resolves the secret when each attempt starts, and the runner
keeps it out of reports, logs, and what the agent reads. An undeclared name
fails the config load with `INVALID_CONFIG`. A plain string password also
works, but e2e redacts only a `secrets.get` password.
## Viewports
Set a viewport on the target to run a suite at that size, or call
`browser.setViewport()` during a test. The agent resizes with its
[`resize_viewport`](/reference/agent#action-tools) tool.
### One size per target
`viewport` sets the initial size of each attempt, in pixels. The default is
1280 by 720. Add one target for each size:
```ts title="e2e.config.ts"
import type { E2EConfig } from 'e2e';
import { web } from '@e2e-dev/web';
const app = { url: 'http://localhost:3000' };
export default {
targets: [
{ name: 'desktop', engine: web(), app },
{ name: 'tablet', engine: web({ viewport: { width: 820, height: 1180 } }), app },
{ name: 'phone', engine: web({ browser: 'webkit', viewport: { width: 390, height: 844 } }), app },
],
} satisfies E2EConfig;
```
Every test runs on every target, with a separate result per target name.
Every retry starts at the target's size.
- Run one size with `npx e2e run --target phone`. List the test-target
pairs with `npx e2e list`.
- Targets that declare the same `app.command` share one dev server.
- A device target can sit in the same list. See the
[Mobile engine reference](/reference/mobile).
### Fill the window
`viewport: null` sets no size, so the page fills the browser window, and the
agent, screenshots, and videos use that size. Use it in a headed run, or
with a hosted browser whose live view would show a 1280 by 720 page in one
corner:
```ts title="Target fragment"
{ name: 'window', engine: web({ viewport: null }), app }
```
A local headed launch opens a small window. A hosted browser uses the
window size you requested from the service. `browser.setViewport` still
works.
### Resize inside a test
`browser.setViewport` resizes the page for the rest of the attempt, also
after `app.restart()` and `app.clearState()`. Use it when one test checks a
layout before and after a resize:
```ts
import { test } from '@e2e-dev/web';
import { expect } from 'e2e';
test('the menu collapses on a narrow screen', async ({ app, screen, browser }) => {
await app.open('/');
await expect(screen.getByRole('navigation')).toBeVisible();
await browser.setViewport({ width: 390, height: 844 });
await expect(screen.getByRole('button', 'Menu')).toBeVisible();
await expect(screen.getByRole('navigation')).toBeHidden();
});
```
Call it before `app.open` to load the first page at that size, with no
desktop render first.
### What the agent sees
The agent gets the current viewport size with each observation, so resize
before `agent.act`. Screenshots cover the viewport. Off-screen elements can
still be in the tree, a tap scrolls them into view, and the agent can
scroll to load lazy content.
A sentence with a link, emphasis, or code reaches the agent whole, and the
link is also listed as a control. The agent reads the first 512 characters
of each block of text. In a longer block, e2e also lists its links and
emphasized text on their own.
The agent also sees a checkbox or radio that a component library shrinks
to no size under its own label, as Element Plus does, with its checked
state. A tap on it clicks the label. When that label is or holds a link
or another control, the agent sees the label's text and that control but
not the checkbox, since a click on the label could land on the link. Locators still call that control hidden, as
Playwright does, so check it with `toBeChecked()`, not `toBeVisible()`.
### Scoping a test to one size
`platforms` and `requires` can't select a viewport, because every browser
target has platform `web`. To skip a test at some sizes, read the width in
the test:
```ts
test('the sidebar stays open', async ({ app, screen, browser }) => {
await app.open('/');
test.skip((await browser.evaluate(() => window.innerWidth)) < 768, 'desktop layout only');
await expect(screen.getByRole('complementary')).toBeVisible();
});
```
To keep a group of size-specific tests apart, give them their own config
and run it with `--config`.
### Limits
A narrow viewport tests responsive layout only. The browser is still a
desktop browser: scale factor 1, desktop pointer, and its usual user agent.
It doesn't emulate touch. To test on a simulator or emulator, use the
[mobile engine](/mobile). For dark mode and reduced motion, see
[Emulate dark mode and reduced motion](/browser#emulate-dark-mode-and-reduced-motion).
A video keeps the size the page had when recording started. Set
`web({ screencast: { size } })` for one fixed size. A browser provider that
records, such as [Kernel](/integrations/kernel#recordings), records the
whole screen instead.
## Granting browser permissions
Headless Chromium refuses a permission the target doesn't grant, so
`navigator.clipboard.writeText` fails even after a click. To let
the app use the clipboard, grant it on the target:
```ts
{
engine: web(),
app: {
url: 'http://localhost:3000',
permissions: { 'clipboard-read': 'grant', 'clipboard-write': 'grant' },
},
}
```
- Every page of every attempt holds the grant, on any origin.
- A web target takes `'grant'` only. `'deny'` and `'reset'` are
`INVALID_CONFIG`: leave the permission out instead.
- The names are Playwright's, and each browser grants its own set. See
[`permissions`](/reference/config#permissions).
## Next
<CardGroup cols={2}>
<Card title="Working with the browser" icon="globe" href="/browser">
Mock routes, set cookies, handle dialogs, and download files.
</Card>
<Card title="Web engine reference" icon="masks-theater" href="/reference/web">
Every `web()` option and every `browser` method.
</Card>
</CardGroup>