skip to content

docs / Migrate

From Playwright

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

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.

agent prompt

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 every Playwright config key, API, and CLI flag to e2e and marks what e2e does not 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 tables. 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. Rewrite that 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. Where the guide marks a feature missing, use the workaround it gives, or leave that test in Playwright and tell me why.
  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.

For a migration that spans several sessions, the migrate-to-e2e skill records what moved in a progress file and keeps the old suite running until you retire each test.

Port the config

Install e2e and configure a model with the quickstart.

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 lists every key.

App, targets, and output

Playwrighte2eStatus
use.baseURLapp: { url } on the targetrenamed
webServerapp: { url, command } on the target, see Starting your apprenamed
webServer arrayapp: { url, command } on each target; targets declaring the same command share one process. Other dependency processes are not started by this versionmissing
webServer.reuseExistingServerapp.command: { reuseExisting: true }; CI ignores itrenamed
globalSetup, globalTeardowntest.setup for sign-in, hooks and fixtures for setup codemissing
projectstargets, one engine instance eachrenamed
testDir, testMatchtests, globs relative to the project rootrenamed
testIgnorea tests entry with a leading !: tests: ['tests/**/*.e2e.ts', '!tests/wip/**']renamed
fullyParallela file’s tests run in order on one worker, files run in parallelmissing
maxFailures--max-failures <n>; no config keyrenamed
globalTimeoutmaxDuration, or --max-duration <ms>; the clock starts with the tests, not app startuprenamed
reporterreporters: ['list', 'junit']; also json and markdownrenamed
reporter: 'html'htmlReporter() from @e2e-dev/html-reporter writes .e2e/report.htmlrenamed
outputDiroutput, default .e2e, holding results/ (cleared when a run starts, like outputDir) beside the reportrenamed
metadatanot yetmissing

Browser, timeouts, and artifacts

Playwrighte2eStatus
use.viewport, use.browserNameweb({ viewport, browser })renamed
use.testIdAttributeweb({ testIdAttribute })renamed
use.httpCredentialsweb({ basicAuth }), answered for the app’s origin only; credentialOrigins adds morerenamed
use.extraHTTPHeadersweb({ headers }), sent on requests that start at the app’s origin; credentialOrigins adds morerenamed
chromium.connectOverCDP(url)web({ connect: { cdpEndpoint: () => url } }), chromium onlyrenamed
use.connectOptions (wsEndpoint)web({ connect }) attaches over CDP onlymissing
retries, workers, timeoutthe same names at the top level. workers takes an integer from 1 to 1024, not '50%'; retries stops at 10. The defaults differ, see belowrenamed
expect.timeoutassertionTimeoutrenamed
use.actionTimeoutactionTimeoutrenamed
use.navigationTimeouttimeout, the test budget; browser.goto(url, { timeout }) overrides one callrenamed
use.storageState, a setup project in projects[].dependenciestest.setup(title, { sessions }, fn) with session.save(name), then { session } on a test, see Authentication; no file, see What differs on purposeby design
use.storageState: { cookies } with fixed valuesbrowser.setCookies(cookies) in a fixturerenamed
use.tracetrace: 'off', 'on', 'retain-on-failure', 'on-first-retry', or 'on-all-retries', at the top of the config, per target, per test, or --trace [mode]. A trace is a markdown page, trace.md, in each test’s directory under .e2e/results/, not a zip, with no viewer. No 'retain-on-first-failure', 'retain-on-failure-and-retries', or object form. The default differs, see belowrenamed
use.videovideo, with the modes and places of trace, and --video [mode]; no { mode, size } objectrenamed
use.headless: false--headed on the CLIrenamed
use.locale, use.timezoneIdweb({ locale, timezoneId })renamed
use.colorScheme, use.reducedMotionweb({ colorScheme, reducedMotion })renamed
use.userAgentweb({ userAgent })renamed
devices['iPhone 15'], deviceScaleFactor, isMobile, hasTouchweb({ viewport }) sets the size onlymissing
use.permissionsapp.permissions on the target, { 'clipboard-read': 'grant' }: grant only, held by every page on any origin, see Granting browser permissionsrenamed
geolocation (the position; the permission is app.permissions above), ignoreHTTPSErrors, bypassCSP, offline, launchOptions, proxynot yetmissing

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.

Playwright
import { test, expect } from '@playwright/test';

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');
});
e2e
import { test } from '@e2e-dev/web';
import { expect } from '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

Status is same, renamed, web only, by design, or missing with what to do today. See What differs on purpose for the by design rows. Calls on browser run only in a browser, so a test that uses it declares requires: ['browser'] and other targets skip it. Calls on screen, app, agent, and expect(locator) run on every target.

Locators
Playwrighte2eStatus
page.getByRole, getByLabel, getByText, getByTestId, getByPlaceholderthe same on screen; getByRole also takes the name positionally, getByRole('button', 'Save')same
getByRole(role, { name }), getByLabel, getByPlaceholder, getByText with a stringan exact, case-sensitive match, see What differs on purposeby design
getByRole('img')the same; img is an alias of imagesame
getByAltText(alt)getByRole('image', alt)renamed
getByTitlethe node carries no titlemissing
getByRole(role, { includeHidden })a role query never matches a hidden node; { visible: true } on the other queries drops hidden twinsby design
locator.filter({ hasText, hasNotText, has, hasNot }), first(), last(), nth(i), count()the samesame
locator.or(other)the same; web branches need identical literal frame-selector chains. A locator is strict, so add first() when both matchsame
locator.and(other)not yetmissing
locator.all(), allTextContents()the same; allInnerTexts() is allTextContents()same
page.locator('css'), page.locator('xpath=...')browser.locator('css'): the string is a Playwright selector, so xpath= (or a leading //) and >> chains work tooweb only
page.waitForSelector(selector)browser.locator(selector).waitFor(); a locator is strict, see What differs on purposerenamed
page.click(selector), page.fill(selector, value), page.getAttribute(selector, name), and the other page methods that take a selectorbrowser.locator(selector).tap(), .fill(value), .getAttribute(name). Playwright acts on the first match; a locator is strict, so add first() for the old behavior, see What differs on purposerenamed
locator.locator('css')a semantic query inside the scope (cell.getByRole('textbox') for cell.locator('input')), browser.locator('css').getByRole(...) the other way round, or one browser.locator selector for the whole pathmissing
page.frameLocator('#frame')browser.frameLocator('#frame'), then screen queries inside it. An element inside a visibility: hidden iframe reads as visibleweb only
Actions
Playwrighte2eStatus
locator.click()locator.tap(); click() is an aliassame
click({ button: 'right' })secondaryTap()renamed
dblclick()doubleTap(); dblclick() is an aliassame
click({ position })tap({ position }), an offset from the node’s top-left corner inside its borderrenamed
click({ force })tap({ position }) skips every actionability check but the scroll into viewmissing
click({ modifiers }), dblclick({ modifiers })tap({ modifiers }), doubleTap({ modifiers }) or dblclick({ modifiers }), secondaryTap({ modifiers }); not beside position yetrenamed
click({ clickCount, delay, trial })not yetmissing
{ trial }, { force }, { noWaitAfter } on check(), fill(), and the other actionsan unknown option is INVALID_ARGUMENT, never ignoredmissing
fill(value)the same; also takes a Secretsame
pressSequentially(text, { delay })the same; keystrokes through the platform keyboard, a Secret is refusedsame
press(key)the same; modifiers join with +, see the key grammarsame
clear(), focus(), hover(), setInputFiles(), dragTo()the same verbs, each with timeout as the only option: no force, trial, position, modifiers, or sourcePosition. Another key is INVALID_ARGUMENT. setInputFiles is web only, and setInputFiles([]) clears the inputrenamed
check(), uncheck()the same, except when the state updates late or the click removes the control, see What differs on purpose. uncheck() on a checked native radio is ACTION_FAILED; a role=radio is clicked, as in Playwrightby design
selectOption('pro')selectOption('Pro'): a string matches the option’s label only, where Playwright matches its value or its label; selectOption({ value: 'pro' }) for the valueby design
selectOption(['a', 'b'])one option per call. An array is INVALID_ARGUMENTmissing
setInputFiles({ name, buffer })paths only, resolved from the project rootmissing
scrollIntoViewIfNeeded()scrollIntoView()renamed
locator.innerText()textContent(), whitespace collapsed to single spacesrenamed
locator.textContent()the rendered text, what innerText() reads, see What differs on purposeby design
getAttribute(), isVisible(), isHidden(), isEnabled(), isDisabled(), isChecked(), boundingBox()the samesame
inputValue()the same, and reads a contenteditable editor, where Playwright throwsby design
inputValue(), isChecked() on a <label>throws, where Playwright reads its control. Locate the control with getByLabelmissing
isEditable()not yetmissing
waitFor({ state: 'visible' }), 'hidden', 'attached', 'detached'the samesame
locator.evaluate(fn), evaluateAll(fn)browser.evaluate(fn, selector) with a CSS selector argumentmissing
locator.screenshot()app.screenshot(label) captures the viewportmissing
innerHTML(), dispatchEvent(), selectText(), blur(), highlight()browser.evaluatemissing
ariaSnapshot()not yetmissing
page.keyboard.press, keyboard.typebrowser.keyboard.press, browser.keyboard.type; plain text only, never a Secretweb only
keyboard.down, keyboard.upbrowser.keyboard.down, browser.keyboard.up; keys and modifiers stay held until releasedweb only
keyboard.insertTextnot yetmissing
page.mouse.click(x, y)screen.tapAt({ x, y }), viewport coordinatesrenamed
mouse.move, down, up as a dragscreen.swipe({ from, to })renamed
page.dragAndDrop(source, target, { sourcePosition, targetPosition })source.dragTo(target), which takes no positions; for sourcePosition or targetPosition, screen.swipe({ from, to }) with each boundingBox() origin plus its offsetrenamed
page.mouse.dblclick(x, y)screen.doubleTapAt({ x, y }), viewport coordinatesrenamed
page.mouse.move, wheel, down, upbrowser.mouse.*web only
Assertions
Playwrighte2eStatus
expect(locator).toBeVisible(), toBeHidden(), toBeEnabled(), toBeDisabled(), toBeFocused(), toHaveValue(), toHaveAttribute(), toHaveCount(), toHaveAccessibleName()the samesame
a Playwright Locator (page.getByRole(...)) passed to expect from e2ea plain value, so toBeVisible() and the other locator matchers fail to compile (TS2339 on ValueExpectation). Rewrite the query on screenmissing
toBeChecked()the same on a checkable node; on any other node .not.toBeChecked() passes, see What differs on purposeby design
toHaveText(), toContainText()compare the rendered text, see What differs on purposeby design
toHaveText(['a', 'b']), toContainText([...]) on several matchesthe same: toHaveText needs the count to match, toContainText an ordered subsequencesame
toBeChecked({ checked: false }), toBeEnabled({ enabled }), toBeVisible({ visible }), toBeAttached({ attached })the samesame
{ ignoreCase } on toHaveText(), toContainText(), toHaveAccessibleName(), toHaveAttribute(name, value)the samesame
toBeChecked({ indeterminate }), { useInnerText }INVALID_ARGUMENT, so the matcher never passes on its defaultmissing
toHaveAttribute('aria-selected', 'true'), 'aria-expanded'toBeSelected(), toBeExpanded()renamed
.not.toBeVisible(), .not.toBeChecked(), .not.toBeEnabled()toBeHidden(), toBeChecked({ checked: false }), toBeDisabled(). A .not locator matcher holds for up to 1 s before it passes, see What differs on purposeby design
a positive matcher on several matchesLOCATOR_AMBIGUOUS at once, see What differs on purposeby design
toBeAttached()the same; passes on a hidden match toosame
toBeEmpty(), toBeInViewport(), toBeEditable(), toHaveRole(), toHaveAccessibleDescription()not yetmissing
expect(locator).toHaveClass(cls)expect(browser).toHaveClass(locator, cls); a DOM fact is asserted through browser; reads the class attribute, so '' matches class="" and not a missing attributeweb only
toHaveCSS(), toHaveId(), toHaveJSProperty(), toContainClass(), toHaveValues()browser.evaluate plus a value matchermissing
expect(page).toHaveURL(), toHaveTitle()expect(browser).toHaveURL(), toHaveTitle(); toHaveURL takes ignoreCaseweb only
expect(page).toHaveScreenshot(), expect(locator).toHaveScreenshot()expect(screen).toHaveScreenshot(), expect(locator).toHaveScreenshot() on every target, a device included, with threshold, maxDiffPixels, maxDiffPixelRatio, mask, maskColor, and timeout. See Visual comparisonsame
toHaveScreenshot({ fullPage, clip, animations, caret, scale, stylePath })always the viewport, at CSS scale, animations stopped and the caret hiddenmissing
toMatchSnapshot(), toMatchAriaSnapshot()not yetmissing
expect(value).toBe(), toEqual(), toMatchObject(), toBeTruthy(), toBeFalsy(), toBeNull(), toBeUndefined(), toBeDefined(), toHaveLength(), toHaveProperty(), toMatch(), toBeGreaterThan(), toBeGreaterThanOrEqual(), toBeLessThan(), toBeLessThanOrEqual(), toBeCloseTo()the same, plus toMatchSchema(), see value matchers. toContain differs, belowsame
expect(collection).toContain()compares items by deep equality, like Playwright’s toContainEqual, so toContain({ id: 1 }) passes on [{ id: 1 }]. Containment in a string is the sameby design
toStrictEqual(), toThrow(), toBeInstanceOf(), toBeNaN(), toContainEqual()toEqual on the shape you need; toContain for toContainEqualmissing
expect.any(), anything(), objectContaining(), arrayContaining(), stringMatching(), stringContaining()the same, see asymmetric matcherssame
expect.closeTo(), expect.not.objectContaining() and the other expect.not.*not yetmissing
expect(async () => { ... }).toPass()expect.poll(async () => { ...; return true }).toBe(true) retries the block. Its timeout is assertionTimeout (5 s), not the test timeout, with one fixed intervalmissing
expect.poll(read, { intervals })expect.poll(read, { interval }), one number in ms, default 100renamed
expect.soft()the same; kept failures fail the attempt once the body settles. In afterEach a soft failure throws at once. See soft assertionssame
expect(locator, 'message')expect(locator); a locator failure already names the locator, the matcher, and what was observed. Only a value expectation takes a messageby design
expect.extend()not yetmissing
expect(promise).resolves, .rejectsawait first, then expect(value)missing
Navigation and app
Playwrighte2eStatus
page.goto(path)app.open(path); browser.goto(url, { waitUntil, timeout }) for the browser optionsrenamed
page.goto('data:text/html,...')POLICY_DENIED, see What differs on purpose. Serve the HTML from a browser.route with route.fulfill({ body, contentType: 'text/html' }) on an app URLby design
const response = await page.goto()app.open and browser.goto resolve to void; take the response from browser.waitForResponseby design
page.goBack()app.back(), or browser.back()renamed
page.goForward(), page.reload()browser.forward(), browser.reload()web only
page.url(), page.title()browser.url(), browser.title()web only
page.waitForURL()browser.waitForURL(), with a string or RegExp and timeout as the only option. A string is an absolute URL, or a relative one resolved against app.url, matched exactly, not a glob: '**/orders' never matches, so pass a RegExpweb only
page.waitForLoadState()browser.goto(url, { waitUntil }) on the navigation itselfmissing
page.waitForFunction(fn)expect.poll(() => browser.evaluate(fn)).toBeTruthy()missing
page.waitForTimeout(ms)a locator assertion on the state you are waiting for: toBeVisible() on what appears, toBeHidden() on what goes awayby design
page.setViewportSize()browser.setViewport(), before or after the first navigationweb only
page.viewportSize()browser.evaluate(() => ({ width: innerWidth, height: innerHeight }))missing
page.screenshot()app.screenshot(label): the viewport, redacted, attached to the report; no fullPagerenamed
a fresh context per testevery attempt starts in a fresh context; app.restart() recreates it, app.clearState() also clears storage. No page opens before the first app.open or browser.goto, where Playwright starts on about:blanksame
page.pause()--step --headed runs the first step, then holds each later one until a key; e2e mcp to drive the app from a coding agentmissing
Network and browser
Playwrighte2eStatus
page.route(pattern, handler)browser.route(pattern, handler); a string or RegExp pattern, no predicate function; the handler decides exactly once. A string is a glob on the full URL, never resolved against app.url. ? matches any one character on purpose, where Playwright reads it literally; {a,b} is literal, and **/ needs at least one segmentweb only
route.fulfill({ json, body, path, status, headers, contentType })the same; one of json, body, or path, and path is relative to the project root. body is a string, Buffer, or Uint8Array, and a \n-joined set-cookie sets each cookieweb only
route.continue({ url, method, headers, postData }), route.fallback()the same; a url resolves against app.url and keeps the request’s http or https scheme. A header set to undefined is dropped; configured headers still apply to an allowed origin. fallback() takes no overridesweb only
route.fetch()argument-free: no timeout, headers, or maxRedirects options, and redirects return unfollowed; returns { url, status, headers, body(), text(), json() } without deciding the routeweb only
route.abort(code), route.fallback(overrides)none yet; abort() takes no error codemissing
page.unroute()browser.unroute()web only
page.unrouteAll()browser.unrouteAll()web only; clears test routes
page.waitForResponse(pattern)browser.waitForResponse(pattern): a string or RegExp, no predicate function; url, status, headers, body(), json(), text(). A string is the glob of browser.route, tested against the whole URL, query included: Playwright’s '/api/orders' is the full URL or '**/api/orders', and '\\?' is a literal ?web only
{ timeout: 0 } for no timeoutthe same; the test timeout, or cleanupTimeout in afterEach, still bounds itsame
response.ok(), response.request()statusmissing
page.waitForRequest(), request.postDataJSON()none yet for waitForRequest; route.request.postData is a stringmissing
routeFromHAR(), routeWebSocket()not yetmissing
page.on('dialog')browser.onDialog('accept'), or a handler that calls accept or dismissweb only
page.waitForEvent('download')browser.waitForDownload(() => trigger)web only
page.waitForEvent('popup'), context.on('page')a window the app opens is not drivenmissing
page.on('console'), page.on('pageerror')assert on what the page showsmissing
page.evaluate(fn, arg)browser.evaluate(fn, arg); JSON in and out, no handles. It and the locator reads run in the page’s main world, so a page that deletes a global such as Map or Array breaks themweb only
page.addInitScript(script, arg), context.addInitScript()browser.addInitScript(script, arg), or web({ initScripts }) for every test; pass { content } as a plain stringweb only
page.emulateMedia({ colorScheme, reducedMotion })browser.emulateMedia(), for every open tab and every tab opened after it; media, forcedColors, and contrast are not yet supportedweb only
page.exposeFunction(), addStyleTag(), setExtraHTTPHeaders(), clocknone yet; for addStyleTag, browser.evaluate can append a <style> once the page is openmissing
context.addCookies(), context.cookies()browser.setCookies(), browser.cookies()web only
context.clearCookies(options)browser.clearCookies(options)web only
request fixtureNode fetch, see APIby design
context.storageState({ path })no file, see What differs on purposeby design
Test structure
Playwrighte2eStatus
import { test, expect } from '@playwright/test'import { test } from '@e2e-dev/web' and import { expect } from 'e2e'renamed
test(title, fn), test.describe, beforeEach, afterEachthe same; describe and the hooks are also top-level imports. A hook takes no title and gets the fixtures only, no testInfo, so afterEach can’t read the test’s statusrenamed
test.beforeAll, afterAllthe same, with platform as the only fixture; no browser, request, or workerInfo. A failed test re-imports the file, so beforeAll runs again for the tests after itrenamed
{ page } in a test{ screen, app, browser }; no raw Page in tests, see What differs on purposeby design
test.skip(title, fn)the samesame
test.skip(condition, reason)the same inside a test body or a beforeEach hook. At file or describe level it is a COLLECTION_ERROR, and test.skip(({ ... }) => condition) is missing: use platforms, { skip }, or test.describe(title, { skip: true }, fn)renamed
test.onlythe same; CI rejects it with ONLY_IN_CIsame
test.describe.onlytest.only on each membermissing
test.describe.skiptest.describe(title, { skip: true }, fn)renamed
test.describe.serial, describe.configure({ mode: 'serial' })test.describe(title, { serial: true }, fn): one retry unit with shared app staterenamed
describe.configure({ mode: 'parallel' })a file’s tests run in order on one workermissing
describe.configure({ retries, timeout }){ retries, timeout } on the grouprenamed
test.setTimeout(ms), test.slow()a fixed test(title, { timeout }, fn) or test.describe(title, { timeout }, fn); no change at runtimemissing
test.fixme(){ skip: 'reason' }missing
test.fail()the same inside a test or beforeEach, plus a fail option; no file or group form, so mark each test; serial group members and setup tests can’t be marked; a timeout counts as the expected failure; infrastructure errors are not covered, see test.failsame
test.step(title, fn)every screen, browser, and agent call is already a named step in the report, with its arguments redactedmissing
test.info(), attach(), annotationsapp.screenshot(label) attaches a screenshotmissing
{ tag: '@smoke' }{ tags: ['smoke'] } on a test or grouprenamed
test.use({ ... })no file or describe override. Runner options go on the group: test.describe(title, { timeout, retries, agent, trace, video, session }, fn). Engine options go per target in the config; browser.setViewport at runtime, web onlymissing
test.extend({ fixture })the same shape; a fixture that needs another goes in a chained extend. Not yet on demand: every fixture of the chain sets up for every test on that test, named or not. Give each setup its own testmissing
{ scope: 'worker' } fixtures, option fixturesbeforeAll for per-file setupmissing
CLI
Playwrighte2eStatus
npx playwright testnpx e2e runrenamed
npx playwright test tests/login.spec.tsnpx e2e run tests/login.e2e.ts; a directory, a bare name, or a glob also selectssame
--project web--target webrenamed
-g, --grep, --grep-invert--grep and --grep-invert, no -g; matched against the describe titles and the test title joined by spaces; tags are --tag and --exclude-tagrenamed
tests/login.spec.ts:12tests/login.e2e.ts:12, the test whose test( call opens on that line. A describe line or file:line:column selects nothingrenamed
--debug--step --headed runs the first step, then holds each later one until a key; there is no inspector. e2e run --debug prints phase timings and the agent step tablerenamed
--ui--watch reruns on save with vitest’s keys, --headed to watch, e2e mcp to drive the app from a coding agentmissing
--headed, --retries, --workers, --config, --pass-with-no-teststhe same long flags, no -j or -c. --workers takes a number, not 50%; --config takes a file, not a directoryrenamed
--reporterthe same flag; the ids are list, json, junit, markdown. No dot, line, html, blob, github, or null; a custom reporter goes in the config’s reportersrenamed
--output--output, the results directory; each test’s trace page and artifacts are in its results/same
--trace <mode>--trace [mode] with the five modes of trace, no retain-on-first-failure or retain-on-failure-and-retries; a bare --trace is onrenamed
--last-failed, --shard, --repeat-each, --max-failuresthe same names; --shard keeps serial groups togethersame
--only-changed--changed-since <ref> with a test filter in filters, such as decisionFilter({ model }), which asks a model which tests the change can affectby design
--quietnot yetmissing
-u, --update-snapshotsPlaywright’s -u changed: writes the stored screenshots that are missing or differ. No mode argument (all, missing, none) and no updateSnapshots config key. In CI a missing screenshot is written only with -urenamed
--listnpx e2e list, with the same selection flagsrenamed
npx playwright codegennpx e2e explore walks the app from a goal and reports what it found; npx e2e mcp lets a coding agent drive the app while it writes the test, see MCP serverrenamed
npx playwright show-traceno viewer; open the trace.md under .e2e/results/ that the terminal namesby design
npx playwright show-report.e2e/summary.md from the markdown reportermissing
npx playwright installnpx @e2e-dev/web install, for the Playwright version the engine pins; a run also installs a missing browser on its ownrenamed

Port page objects

A page object takes screen for queries and actions, and browser for keyboard, mouse, CSS selectors, and evaluate. Hand page objects out as fixtures, so every test gets them without a beforeEach:

tests/page-models/account-page.ts
import type { Locator, Screen } from 'e2e';
import type { Browser } from '@e2e-dev/web';

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);
  }
}
tests/fixtures.ts
import { test as base } from '@e2e-dev/web';
import { AccountPage } from './page-models/account-page.ts';

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

A fixture that reads browser makes every test on that test web only. See Keep it portable.

locator.page() has no counterpart, so pass browser with the locator. Drop newPage() and page.close() from the hooks: every attempt starts in a fresh context.

What differs on purpose

  • A string name is exact. Playwright’s getByRole names, getByLabel, getByPlaceholder, and getByText match a case-insensitive substring, so Save also hits Save as draft. In e2e a string matches the whole text, case-sensitive. Pass { exact: false } or a RegExp for a fragment, and drop Playwright’s { exact: true }, which is the default here. A query that misses passes a negated assertion, so check it with a positive one first. See 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. On the web, textContent() and toHaveText read what innerText returns, like Playwright’s { useInnerText: true }. Playwright reads the DOM’s textContent by default. Queries still match the source text: getByText('Draft') finds the tag below, getByText('DRAFT') does not. browser.evaluate reads the raw DOM text. See locator reads.

    ts
    // <span data-testid="tag" style="text-transform: uppercase">Draft</span>
    // <p data-testid="total">Total <span style="display: none">debug</span>42</p>
    // <p data-testid="address">Line one<br>Line two</p>
    await expect(screen.getByTestId('tag')).toHaveText('DRAFT');                 // Playwright: 'Draft'
    await expect(screen.getByTestId('total')).toHaveText('Total 42');            // Playwright: 'Total debug42'
    await expect(screen.getByTestId('address')).toHaveText('Line one Line two'); // Playwright: 'Line oneLine two'
  • .not.toBeChecked() passes on a button or a heading, where Playwright throws, as isChecked() does. Query a checkable control by role, so the query fails when the control changes kind.

    ts
    await expect(screen.getByRole('checkbox', 'Subscribe')).not.toBeChecked();
  • A negated locator matcher passes only after its condition holds for 1 s, or for its whole timeout when that is shorter. The positive inverse, such as toBeHidden(), passes on the first read that holds.

  • check() and uncheck() read the state back until the action timeout, so a controlled checkbox that updates late passes. A click that removes the control passes too, where Playwright fails. Assert on what replaced it.

  • One match or LOCATOR_AMBIGUOUS, isVisible() included, where Playwright reads the first match silently. Narrow with filter, first(), or { visible: true }, or add a >> visible=true step to a browser.locator selector. See screen.

  • Navigation opens http, https, and about:blank only. data:, file:, and every other scheme are POLICY_DENIED, whether from app.open, browser.goto, or route.continue({ url }).

  • browser.evaluate takes and returns JSON only, so the report can record and redact the result. Pass values in through arg.

  • A password is a Secret with no string value, and the model never sees it. See Authentication.

  • Sessions are per run. test.setup saves state under a name, one time per run and target, and { session } restores it. The file is encrypted and deleted at cleanup, so there is no .auth/user.json to reuse across runs.

  • No raw Page in tests. Nothing on a raw page is recorded, redacted, or masked. surfaceOf(engine) is for custom executors, not test code.

Defaults that differ

SettingPlaywrighte2e
Test timeout30 s120 s, timeout
Action timeoutnone30 s, actionTimeout
Expect timeout5 s5 s, assertionTimeout
Navigation timeoutnone120 s, the test budget
Retries01 in CI, 0 locally
Workershalf the CPU cores1 in CI, half the CPU cores locally
Traceoff (on-first-retry in the scaffolded config)retain-on-failure

Next

was this page helpful?