> ## Documentation Index
> Fetch the complete documentation index at: https://e2e.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# From Playwright

> Run e2e alongside Playwright and migrate tests one file at a time.

export const migrationPrompt = `Migrate this project's Playwright tests to e2e, one spec at a time. Docs: \`https://e2e.com/docs/migrate/playwright.md\`

1. Read the migration guide above. It maps the Playwright config keys, APIs, and CLI flags that work in e2e, and lists what e2e doesn't have yet.
2. If the project has no e2e config (\`e2e.config.ts\`, \`.mts\`, \`.js\`, or \`.mjs\`), run \`npx e2e init --yes\` (or the pnpm or bun equivalent). It writes a config and an example test, and installs nothing yet.
3. Read the e2e skill (\`npx e2e guide\` prints it, \`npx e2e guide <topic>\` prints a topic) and follow it for every step below.
4. If you ran init, ask me which model to use for agent steps: a ChatGPT, GitHub Copilot, OpenCode Console, or SuperGrok subscription, an API key, or a local model. Configure it with its provider package. If it needs a sign-in, give me the \`npx e2e login\` command and wait until I confirm.
5. Port \`playwright.config.ts\` into the e2e config with the guide's config table. Keep \`@playwright/test\` installed and the two file patterns apart.
6. Install dependencies.
7. List the Playwright specs and ask me which one to move first. Suggest a flow whose steps change often, such as a wizard or a checkout.
8. Check each Playwright API in that spec against "What e2e doesn't have yet". Use the "Use today" or "Use instead" entry, or leave that test in Playwright and tell me why. Then rewrite the spec as a \`.e2e.ts\` file under \`tests/\` (e2e runs \`tests/**/*.e2e.ts\` by default). Map each \`page\` call to \`screen\`, \`app\`, or \`browser\` with the guide. Where a Playwright query matched a fragment, add \`{ exact: false }\` or a RegExp.
9. Keep navigation and the final assertions deterministic, with \`app.open()\` and locator assertions. Where a run of scripted interactions breaks often, propose an \`agent.act\` goal for it instead.
10. Run the new file with \`npx e2e run <file>\` and fix it until it passes. Keep the Playwright spec until I confirm it can go.
11. Summarize which tests moved, which stayed in Playwright, and why.`;

e2e can run beside Playwright in one project while you move tests one file
at a time. `@e2e-dev/web` brings its own pinned `playwright-core`, so your
`@playwright/test` version stays yours. e2e reads `e2e.config.ts` and finds
`tests/**/*.e2e.ts` by default, so keep the two file patterns apart.

<SetupPrompt>

<Prompt description={migrationPrompt} children={migrationPrompt} actions={["copy", "cursor"]} />

</SetupPrompt>

For a migration that spans several sessions, the [`migrate-to-e2e` skill](https://e2e.com/docs/coding-agents#migrate-an-existing-suite) records what moved in a progress file and keeps the old suite running until you retire each test.

## Port the config

<Note>Install e2e and configure a model with the [quickstart](https://e2e.com/docs/quickstart).</Note>

A Playwright key such as `testDir`, `baseURL`, `use`, `webServer`, or
`projects` fails with a message that names the e2e key to use. The
[config reference](https://e2e.com/docs/reference/config) lists every key.

| Playwright | e2e |
| --- | --- |
| `use.baseURL`, `webServer` | `app: { url, command }` on the target, see [Starting your app](https://e2e.com/docs/web#starting-your-app) |
| `webServer.reuseExistingServer` | `app.command: { reuseExisting: true }`; CI ignores it |
| `projects` | `targets`, one engine instance each |
| `testDir`, `testMatch`, `testIgnore` | `tests`, globs from the project root; a leading `!` excludes |
| `retries`, `workers`, `timeout` | the same names, with [other defaults](#defaults-that-differ); `workers` is an integer |
| `expect.timeout`, `use.actionTimeout`, `globalTimeout` | `assertionTimeout`, `actionTimeout`, `maxDuration`; the `maxDuration` clock starts with the tests, not app startup |
| `expect.toPass` | Top-level [`toPass`](https://e2e.com/docs/reference/config#topass) |
| `maxFailures`, `use.headless: false` | `--max-failures <n>` and `--headed` on the CLI |
| `reporter`, `outputDir` | `reporters: ['list', 'junit', htmlReporter()]`, with `htmlReporter` from `@e2e-dev/html-reporter`; also `dot`, `json`, and `markdown`; `output`, default `.e2e` |
| `use.viewport`, `locale`, `timezoneId`, `colorScheme`, `reducedMotion`, `userAgent`, `testIdAttribute` | the same keys in `web({ ... })` |
| `use.browserName`, `httpCredentials`, `extraHTTPHeaders` | `web({ browser, basicAuth, headers })`; `basicAuth` and `headers` apply to the app's origin only, [`credentialOrigins`](https://e2e.com/docs/reference/web#credentialorigins) adds more |
| `chromium.connectOverCDP(url)` | `web({ connect: { cdpEndpoint: () => url } })`, chromium only |
| `use.trace`, `use.video` | `trace`, `video`: a mode in the config, on a target, or on a test. `web({ screencast: { size } })` sets the video size |
| `use.permissions` | `app.permissions` on the target, see [Granting browser permissions](https://e2e.com/docs/web#granting-browser-permissions) |
| `use.storageState` from a `setup` project | `test.setup` with `session.save(name)`, then `{ session }` on a test, see [Authentication](https://e2e.com/docs/authentication) |
| `use.storageState: { cookies }` with fixed values | `browser.setCookies(cookies)` in a fixture |

## Rewrite one spec

Start with a flow whose steps change often, such as a wizard or a checkout.
Stable Playwright tests can stay where they are.

```ts title="Playwright"

test('checkout', async ({ page }) => {
  await page.goto('/cart');
  await page.getByRole('button', { name: 'Checkout' }).click();
  await page.getByLabel('Card number').fill('4242424242424242');
  await page.getByLabel('Expiry').fill('12/30');
  await page.getByLabel('CVC').fill('123');
  await page.getByRole('button', { name: 'Pay' }).click();
  await expect(page.getByRole('heading')).toHaveText('Order confirmed');
});
```

```ts title="e2e"

test('checkout', async ({ app, agent, screen }) => {
  await app.open('/cart');
  await agent.act('pay with the test card 4242 4242 4242 4242, expiry 12/30, CVC 123');
  await expect(screen.getByRole('heading')).toHaveText('Order confirmed');
});
```

The agent does the checkout steps and adapts when the form changes. A test
can also stay fully deterministic, with a `screen.getBy*` line for every
`page.getBy*` line.

## Map each API

Every row works today. For an API that is not here, check
[What e2e doesn't have yet](#what-e2e-doesnt-have-yet). Calls on `browser`
run only in a browser, so a test that uses it declares
`requires: ['browser']` and other targets skip it.

<AccordionGroup>
<Accordion title="Locators">

| Playwright | e2e |
| --- | --- |
| `page.getByRole`, `getByLabel`, `getByText`, `getByTestId`, `getByPlaceholder` | the same on `screen`; a string matches [the whole text](#what-differs-on-purpose) |
| `getByAltText(alt)` | `getByRole('image', alt)` |
| `filter({ hasText, hasNotText, has, hasNot })`, `first()`, `last()`, `nth(i)`, `count()`, `or()`, `all()` | the same |
| `page.locator(selector)`, `page.frameLocator(selector)` | the same on `browser`; CSS, `xpath=`, and `>>` chains work |
| `page.click(selector)`, `page.fill(selector, value)`, `page.waitForSelector(selector)` | `browser.locator(selector).tap()`, `.fill(value)`, `.waitFor()` |

</Accordion>
<Accordion title="Actions">

| Playwright | e2e |
| --- | --- |
| `click()`, `dblclick()` | `tap()`, `doubleTap()`; `click()` and `dblclick()` are aliases |
| `click({ button: 'right' })`, `click({ delay })` | `secondaryTap()`, `longPress({ duration })` |
| `click({ position })`, `click({ modifiers })` | `tap({ position })`, `tap({ modifiers })` |
| `fill()`, `pressSequentially()`, `clear()`, `focus()`, `blur()`, `hover()`, `check()`, `uncheck()`, `dragTo()`, `setInputFiles(path)`, `selectOption({ label })` or `{ value }` | the same, without `force`, `trial`, or `position` |
| `press(key)` | the same for one character or a [named key](https://e2e.com/docs/reference/engine#keys); `browser.keyboard.press` after `focus()` for a key code |
| `innerText()`, `allInnerTexts()`, `scrollIntoViewIfNeeded()` | `textContent()`, `allTextContents()`, `scrollIntoView()` |
| `textContent()`, `allTextContents()`, `inputValue()`, `getAttribute()`, `boundingBox()`, `isVisible()`, `isHidden()`, `isEnabled()`, `isDisabled()`, `isChecked()`, `waitFor({ state })` | the same |
| `page.keyboard.press`, `type`, `down`, `up`; `page.mouse.move`, `wheel`, `down`, `up` | the same on `browser.keyboard` and `browser.mouse` |
| `page.mouse.click(x, y)`, `page.mouse.dblclick(x, y)`, `page.dragAndDrop(source, target)` | `screen.tapAt({ x, y })`, `screen.doubleTapAt({ x, y })`, `source.dragTo(target)` |

</Accordion>
<Accordion title="Assertions">

| Playwright | e2e |
| --- | --- |
| `toBeVisible()`, `toBeHidden()`, `toBeEnabled()`, `toBeDisabled()`, `toBeChecked()`, `toBeFocused()`, `toBeAttached()`, `toHaveText()`, `toContainText()`, `toHaveValue()`, `toHaveAttribute()`, `toHaveCount()`, `toHaveAccessibleName()`, `toHaveRole()` | the same, with `{ visible }`, `{ enabled }`, `{ checked }`, `{ attached }`, and `{ ignoreCase }` |
| `toHaveId(id)`, `toContainClass(name)` | `toHaveAttribute('id', id)`, `toHaveAttribute('class', RegExp)` |
| `expect(page).toHaveURL()`, `toHaveTitle()` | `expect(browser).toHaveURL()`, `toHaveTitle()` |
| `expect(page).toHaveScreenshot()`, `expect(locator).toHaveScreenshot()` | `expect(screen).toHaveScreenshot()` and the locator form, see [Visual comparison](https://e2e.com/docs/visual-testing) |
| `expect(value)` with `toBe()`, `toEqual()`, `toMatchObject()`, `toContain()`, `toHaveLength()`, `toHaveProperty()`, `toMatch()`, and the truthiness and number matchers | the same, see [value matchers](https://e2e.com/docs/reference/expect#value-matchers) |
| `expect(locator, 'message')`, `expect(page, 'message').toHaveScreenshot()`, `expect(value, 'message')` | the same, `expect(screen, 'message')` for the page; the message opens the failure, see [locator matchers](https://e2e.com/docs/reference/expect#locator-matchers) |
| `expect.any()`, `anything()`, `objectContaining()`, `arrayContaining()`, `stringMatching()`, `stringContaining()`, `expect.poll()`, `expect.soft()` | the same |
| `expect.poll(read, { intervals })` | the same. See [Polling a value](https://e2e.com/docs/reference/expect#polling-a-value) |
| `expect(fn).toPass(options?)` | the same. See [Retrying a block](https://e2e.com/docs/reference/expect#retrying-a-block) |

</Accordion>
<Accordion title="Navigation and app">

| Playwright | e2e |
| --- | --- |
| `page.goto(path)` | `app.open(path)`; `browser.goto(url, { waitUntil, timeout })` for the options |
| `page.goBack()`, `goForward()`, `reload()`, `url()`, `title()`, `setViewportSize()` | `browser.back()`, `forward()`, `reload()`, `url()`, `title()`, `setViewport()` |
| `page.waitForURL(url)` | `browser.waitForURL(url)` with a `RegExp` or an exact URL, not a glob |
| `page.screenshot()` | `app.screenshot(label)`, the viewport, attached to the report |
| A fresh `context` for each test | the same for each attempt; `app.restart()` recreates it, `app.clearState()` also clears storage |

</Accordion>
<Accordion title="Network and browser">

| Playwright | e2e |
| --- | --- |
| `page.route(pattern, handler)`, `unroute()`, `unrouteAll()` | the same on `browser`; a pattern is a `RegExp`, a glob on the full URL, or `{ method, url }` for one HTTP method |
| `route.fulfill()`, `continue()`, `fallback()`, `abort()`, `fetch()` | the same, see [`route`](https://e2e.com/docs/reference/web#route) for the options each takes |
| `page.waitForResponse(pattern)` | `browser.waitForResponse(pattern)`; `'**/api/orders'`, not `'/api/orders'` |
| `page.on('dialog')`, `page.waitForEvent('download')` | `browser.onDialog('accept')` or a handler; `browser.waitForDownload(() => trigger)` |
| `page.waitForEvent('popup')` | `browser.waitForPopup(() => trigger)`, which makes the new tab active, see [Tabs](https://e2e.com/docs/reference/web#tabs) |
| `context.pages()`, `context.newPage()`, `page.bringToFront()` | `browser.tabs()`, `browser.newTab()`, `tab.activate()`; no `context.on('page')` event |
| `page.evaluate(fn, arg)` | `browser.evaluate(fn, arg)`, JSON in and out |
| `page.addInitScript()`, `page.emulateMedia({ colorScheme, reducedMotion })` | `browser.addInitScript()` or `web({ initScripts })`; `browser.emulateMedia()` |
| `context.addCookies()`, `cookies()`, `clearCookies()` | `browser.setCookies()`, `browser.cookies()`, `browser.clearCookies()` |

</Accordion>
<Accordion title="Test structure">

| Playwright | e2e |
| --- | --- |
| `import { test, expect } from '@playwright/test'` | `import { test } from '@e2e-dev/web'` and `import { expect } from 'e2e'` |
| `{ page }` in a test | `{ screen, app, browser }` |
| `test()`, `test.describe()`, `test.only`, `test.fail()`, `test.skip(title, fn)`, `test.skip(condition, reason)`, `test.fixme(title, fn)`, `test.fixme(condition, reason)` | the same, but a serial group takes `skip` on the group instead; the conditional forms work inside a test body or `beforeEach` |
| `test.setTimeout()` | the same inside a test body, `beforeEach`, or `beforeAll` (that hook's own timeout); `afterEach` and `afterAll` cannot call it. In a `describe` callback, pass `{ timeout }` to `test.describe` instead. There is no `0` for no timeout: pass a large value |
| `beforeEach`, `afterEach`, `beforeAll`, `afterAll` | the same, with no title; `beforeAll` and `afterAll` get worker fixtures, not `browser`, `app`, or `screen` |
| `test.describe.skip`, `test.describe.serial`, `describe.configure({ mode: 'serial', retries, timeout })` | `test.describe(title, { skip, serial, retries, timeout }, fn)` |
| `test.fail()` on a describe | `test.describe.fail(title, fn)`, or `{ fail: 'reason' }` on the group; for a condition, `test.fail(condition, 'reason')` in a `beforeEach` |
| `{ tag: '@smoke' }` | `{ tags: ['smoke'] }` on a test or group |
| `test.extend({ fixture })` | the same shape, set up on demand: a test, a hook, or a fixture gets the fixtures it names in its first parameter |
| `[fn, { scope: 'worker' }]` fixtures | the same, typed with the second type argument of `extend` |
| `[fn, { auto: true }]` fixtures | the same, in either scope |
| Overriding a fixture, `page: async ({ page }, use) => {}` | the same for `app`, `screen`, `browser`, and your own fixtures, see [Extending a fixture](https://e2e.com/docs/reference/test#extending-a-fixture) |
| `page.pause()` | `screen.pause()`, with `--headed` to look at the browser |

</Accordion>
<Accordion title="CLI">

| Playwright | e2e |
| --- | --- |
| `npx playwright test tests/login.spec.ts:12` | `npx e2e run tests/login.e2e.ts:12`; a directory, a bare name, or a glob also selects |
| `--project web`, `--list` | `--target web`, `npx e2e list` |
| `--grep`, `--grep-invert`, `--headed`, `--retries`, `--workers`, `--config`, `--output`, `--reporter`, `--trace`, `--shard`, `--repeat-each`, `--max-failures`, `--last-failed`, `--pass-with-no-tests`, `-u` | the same; of the short flags, only `-u` |
| `npx playwright install` | `npx @e2e-dev/web install`; a run also installs a missing browser |

</Accordion>
</AccordionGroup>

## Port page objects

A page object takes `screen` for queries and actions, and `browser` for
keyboard, mouse, CSS selectors, and `evaluate`. Hand it out as a fixture:

```ts title="tests/page-models/account-page.ts"

export class AccountPage {
  readonly accountName: Locator;

  constructor(
    readonly screen: Screen,
    readonly browser: Browser,
  ) {
    this.accountName = screen.getByTestId('account-name');
  }

  async filterByNote(note: string) {
    await this.screen.getByRole('button', 'Filter').click();
    await this.screen.getByRole('button', 'Note').click();
    await this.browser.keyboard.type(note);
  }
}
```

```ts title="tests/fixtures.ts"

export const test = base.extend<{ accountPage: AccountPage }>({
  accountPage: async ({ screen, browser }, use) => {
    await use(new AccountPage(screen, browser));
  },
});
```

A fixture that names `browser` makes every test that uses it web only, see
[Keep it portable](https://e2e.com/docs/page-object-model#keep-it-portable). Drop `newPage()` and
`page.close()` from the hooks: every attempt starts in a fresh context.

## What e2e doesn't have yet

Planned is on the roadmap. Not yet has no date. Not planned is left out on
purpose. Use the workaround, or keep the test in Playwright.

### Planned

<AccordionGroup>
<Accordion title="Locators and actions">

| Playwright | Use today |
| --- | --- |
| `locator.locator(selector)`, `locator.and()`, `filter({ visible })` | One `browser.locator` selector, such as `'.card >> .close'`, or a `screen` query inside the scope |
| `locator.evaluate()`, `expect(locator).toHaveClass()`, `toHaveCSS()`, `dispatchEvent()` | `browser.evaluate(fn, selector)`; `expect(browser).toHaveClass(locator, cls)` |
| `setInputFiles({ buffer })`, `selectOption([...])`, `click({ clickCount })`, `hover({ position })` | A temp file path; `browser.evaluate` for a multi-select; `browser.mouse` with `boundingBox()` |

</Accordion>
<Accordion title="Assertions">

| Playwright | Use today |
| --- | --- |
| `toBeEmpty()`, `toBeEditable()`, `toBeInViewport()` | `toHaveValue('')` on a form control, `toHaveText('')` on other elements; `toBeEnabled()` and `.not.toHaveAttribute('readonly')`; `expect.poll` over `boundingBox()` |
| `locator.screenshot()`, `{ fullPage, clip }`, `snapshotPathTemplate`, `ignoreSnapshots` | The viewport or one locator in `toHaveScreenshot`; a tag and `--exclude-tag` to skip visual tests |
| `expect.configure()` | `{ timeout }` on each call |
| `@axe-core/playwright` | axe-core through `browser.addInitScript({ path: 'node_modules/axe-core/axe.min.js' })`, then `axe.run()` in `browser.evaluate` |
| `.resolves`, `.rejects`, `toThrow()`, `toStrictEqual()`, `toContainEqual()`, `toBeInstanceOf()`, `expect.closeTo()` | `await` first, or catch the error and assert on it; `toEqual`; `toContain`, which compares by deep equality; `toBeCloseTo` |
| A `.not` locator matcher that passes on the first read | It passes after the condition holds for 1 s. The positive inverse passes on the first read: `toBeHidden()`, `toBeDisabled()`, `toBeChecked({ checked: false })` |
| `expect.extend()` | An async helper that calls `expect` |

</Accordion>
<Accordion title="Navigation, network, and browser">

| Playwright | Use today |
| --- | --- |
| `devices['iPhone 15']`, `isMobile`, `hasTouch`, `deviceScaleFactor` | `web({ viewport, userAgent })`; a mobile target for real touch |
| `waitForURL(glob)`, `waitForFunction()` | A `RegExp`; `expect.poll` over `browser.evaluate` |
| `waitForResponse(predicate)`, `waitForRequest()`, `page.on('request')`, `response.ok()` | `browser.waitForResponse(pattern)`, or `{ method, url }` to filter on the request's method, then check the response in the test, `status` for `ok()`. For requests, a `browser.route` handler that records `route.request`, then calls `route.fallback()` |
| `route.fulfill({ response })`, `route.abort(code)`, `route.fetch(options)`, `request.postDataJSON()` | `status`, `headers`, and `body` from `route.fetch()`; `JSON.parse(route.request.postData)` |
| `page.addLocatorHandler()` | Dismiss the overlay in `beforeEach`, or set its consent cookie with `browser.setCookies` |
| `page.on('console')`, `page.on('pageerror')`, `page.clock` | A `browser.addInitScript` that records to a `window` array, or that stubs `Date` |
| `context.setOffline()`, `setGeolocation()`, `grantPermissions()` | A route that aborts every request; a `browser.addInitScript` stub; `app.permissions` on the target |
| `ignoreHTTPSErrors`, `proxy`, `channel`, `launchOptions` | Serve the app over `http`; start the browser yourself and attach with `web({ connect })` |
| The `request` fixture, `page.request`, `expect(response).toBeOK()` | Node `fetch` with `app.baseUrl`, see [API](https://e2e.com/docs/api-testing); `expect(response.status).toBe(200)` |

</Accordion>
<Accordion title="Test structure, reports, and CLI">

| Playwright | Use today |
| --- | --- |
| `test.step()`, `testInfo.attach()` | Each call is already a named step in the report; `app.screenshot(label)` attaches a screenshot |
| `test.info()`, `testInfo` in hooks and fixtures, `annotations` | Your own fixture or module state; an issue id in the title or a tag |
| `fullyParallel`, `describe.configure({ mode: 'parallel' })` | Split the file. Files run in parallel, a file's tests in order |
| `mergeTests()` | One chain of `extend` calls |
| `globalSetup`, `globalTeardown`, a `webServer` array | A script around the run, or one `app.command` that starts every process |
| `projects[].testMatch`, `testDir`, `testIgnore`, `grep` | `platforms` or tags on the tests, or one run for each target |
| `--ui`, `npx playwright show-report`, `--reporter html` | `--watch --headed`; `npx e2e report` (opens `<output>/report.html` written by `htmlReporter()`) |
| `test.slow()`, `test.describe.only()`, `test.describe.fixme()`, `test.fixme(title, details, body)` | `{ timeout }` or `{ skip: 'fixme' }` on the test or group, with any `tags` from the details beside it, reported with skip cause `explicit`, not `fixme`; `test.only` on each test |
| `test.skip(callback, description)`, `test.fixme(callback, description)` | `test.skip(condition, reason)` or `test.fixme(condition, reason)` inside the body, or `platforms` on the test |
| `failOnFlakyTests`, `use.navigationTimeout`, `--timeout`, `--quiet` | `run.summary.flaky` in `report.json`; `browser.goto(url, { timeout })`; `timeout` in the config |
| The `blob` reporter and `merge-reports` | One report for each shard |
| The Playwright Docker image | The image for the `playwright-core` version `@e2e-dev/web` pins, or `npx @e2e-dev/web install chromium --with-deps` |
| `test.use({ ... })` in a file or describe | Runner options on the group, engine options on a target, `browser.setViewport` at runtime |
| `projects[].dependencies`, `teardown` | A top-level `test.setup` for sign-in; a script around the run |
| The `line` and `github` reporters | `list`; `github()` posts a pull request comment |

</Accordion>
</AccordionGroup>

### Not yet

| Playwright | Use today |
| --- | --- |
| `projects[].retries`, `projects[].timeout` | Options on a group |
| `--debug`, the VS Code extension | `--step --headed` holds each step until a key; `screen.debug()` prints the tree |
| Option fixtures, overriding `page` or `context` in `extend` | `process.env` in the fixture; a new fixture under its own name |
| `const response = await page.goto()` | Start `browser.waitForResponse` before the navigation |
| A Playwright `Reporter` class, third-party reporters | A [custom reporter](https://e2e.com/docs/reference/reporters#custom-reporters) with `onEvent` and `onRunFinished`; `junit.xml` for a dashboard |
| `browser.newContext()` for a second user | Drive the second user through the API with `fetch` |
| `page.exposeFunction()`, `addStyleTag()`, `innerHTML()`, `page.viewportSize()` | `browser.evaluate` |
| `routeFromHAR()`, `routeWebSocket()`, `page.setExtraHTTPHeaders()` | A `browser.route` for each endpoint or header; a `browser.addInitScript` that stubs `WebSocket` |
| `emulateMedia({ media, forcedColors, contrast })` | - |
| `npx playwright show-trace`, `trace.zip`, `context.tracing` | `trace.md` in the test's directory under `.e2e/results/`. A trace is a markdown page, with no zip and no viewer |

### Not planned

| Playwright | Use instead |
| --- | --- |
| `selectOption('pro')` by value | `selectOption({ value: 'pro' })`. A bare string matches the label only |
| `use.storageState: 'file.json'`, `context.storageState({ path })` | `test.setup` and `{ session }`. [Sessions last one run](#what-differs-on-purpose), so there is no file |
| `page.waitForTimeout(ms)`, `page.waitForNavigation()` | A locator assertion on the state you wait for; `browser.waitForURL(url)` |
| `?` as a literal and `{a,b}` in a route glob | A `RegExp`. In a glob, `?` is a wildcard and `{a,b}` is literal |
| `--only-changed` | `--changed-since <ref>` with a [test filter](https://e2e.com/docs/filters) in `filters` |
| `page.$()`, `$eval()`, `elementHandle()`, non-JSON `evaluate` values, `locator.page()` | Locators, and `browser.evaluate` with JSON in and out, which the report records and redacts. Pass `browser` to a page object |
| A dialog with no handler, dismissed silently | `browser.onDialog('dismiss')`. An unhandled dialog fails the next step |
| `page.goto('data:...')`, `'file://...'` | `route.fulfill({ body, contentType: 'text/html' })` on an app URL. Only `http` and `https` open |
| `getByRole(role, { includeHidden })` | `browser.locator('role=button[include-hidden=true]')`. A role query follows the accessibility tree |
| `--grep @smoke` for a tag, a regex positional, `file:line:column` | `--tag smoke`; a glob or a bare name; `file:line` |
| `getByTitle()` | `browser.locator('[title="Close"]')`. A title is a DOM attribute, so it has no `screen` query |
| `page.waitForLoadState()` | An assertion on what the next page shows. A navigation waits for `load`, and each action and assertion waits for its node |
| `npx playwright codegen`, the Inspector | [`npx e2e mcp`](https://e2e.com/docs/mcp-server) lets a coding agent drive the app while it writes the test; `screen.debug()` prints the tree |
| `{ force: true }`, `{ trial: true }` | `tap({ position })` skips the actionability checks; `toBeVisible()` and `toBeEnabled()` for a trial |
| `ariaSnapshot()`, `toMatchAriaSnapshot()`, `toMatchSnapshot()` | `expect(await screen.tree()).toContain(...)`; a fixture file and `toEqual` |
| `keyboard.insertText()`, `inputValue()` on a `<label>` | `fill()`; the control itself, located with `getByLabel` |
| `use.connectOptions`, trace modes `retain-on-first-failure` and `retain-on-failure-and-retries` | `web({ connect })` over CDP, chromium only; `retain-on-failure` |

## What differs on purpose

- A string matches the whole text, case-sensitive. Playwright's `getByRole`
  name, `getByLabel`, `getByPlaceholder`, and `getByText` match a
  case-insensitive substring. Pass `{ exact: false }` or a `RegExp` for a
  fragment. See [queries](https://e2e.com/docs/reference/screen#queries).

  ```ts
  // <button>Save changes</button>, <label>Email address <input></label>
  screen.getByRole('button', 'Save');                  // no match
  screen.getByRole('button', { name: 'Save', exact: false });    // matches
  screen.getByRole('button', 'save changes');          // no match, case differs
  screen.getByLabel('Email');                                    // no match
  ```
- Text reads are rendered text. `textContent()`, `toHaveText`, and
  `toContainText` read what `innerText` returns, so hidden text is left out
  and `text-transform` applies. See [locator reads](https://e2e.com/docs/reference/screen#locator-reads).
- `toHaveRole` takes the `getByRole` vocabulary, so `paragraph`, `generic`,
  and the other roles it leaves out are type errors, and `img` reads as
  `image`. It compares the role the tree reads, where a `contenteditable`
  editor is a `textbox`.
- A locator is strict. An action, a read, or a positive matcher on several
  matches is `LOCATOR_AMBIGUOUS`, where Playwright's `page.click(selector)`
  and `isVisible()` take the first. Narrow with `filter` or `first()`.
- `.not.toBeChecked()` passes on a button or a heading. Query the control
  by its role, so the assertion fails when the control changes kind.
- If an `expect.poll` read throws, it's retried.
- For `toPass`, you'll see only the steps inside each try in the report.
- Sessions last one run. `test.setup` saves state under a name and
  `{ session }` restores it. The file is encrypted and deleted at cleanup,
  so there is no `.auth/user.json` to reuse.
- Tests get no raw `Page`, because nothing on one is recorded, redacted, or
  masked. `surfaceOf(engine)` is for
  [custom executors](https://e2e.com/docs/executors#driving-the-page-yourself), not test code.

## Defaults that differ

| Setting | Playwright | e2e |
| --- | --- | --- |
| Test timeout | 30 s | 120 s, `timeout` |
| Action timeout | none | 30 s, `actionTimeout` |
| Expect timeout | 5 s | 5 s, `assertionTimeout` |
| Navigation timeout | none | 120 s, the test budget |
| Retries | 0 | 1 in CI, 0 locally |
| Workers | half the CPU cores | 1 in CI, half the CPU cores locally |
| Trace | `off` (`on-first-retry` in the scaffolded config) | `retain-on-failure` |

## Next

<CardGroup cols={2}>
  <Card title="Core concepts" icon="pen-to-square" href="/core-concepts">
    Goals, assertions, and locators instead of scripted selectors.
  </Card>
  <Card title="Web engine reference" icon="masks-theater" href="/reference/web">
    Every option and every `browser` method.
  </Card>
</CardGroup>
