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.
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
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
Browser, timeouts, and artifacts
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.
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');
});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
Actions
Assertions
Navigation and app
Network and browser
Test structure
CLI
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:
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);
}
}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
getByRolenames,getByLabel,getByPlaceholder, andgetByTextmatch a case-insensitive substring, soSavealso hitsSave as draft. In e2e a string matches the whole text, case-sensitive. Pass{ exact: false }or aRegExpfor 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()andtoHaveTextread whatinnerTextreturns, like Playwright’s{ useInnerText: true }. Playwright reads the DOM’stextContentby default. Queries still match the source text:getByText('Draft')finds the tag below,getByText('DRAFT')does not.browser.evaluatereads 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, asisChecked()does. Query a checkable control by role, so the query fails when the control changes kind.tsawait 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()anduncheck()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 withfilter,first(), or{ visible: true }, or add a>> visible=truestep to abrowser.locatorselector. See screen. -
Navigation opens
http,https, andabout:blankonly.data:,file:, and every other scheme arePOLICY_DENIED, whether fromapp.open,browser.goto, orroute.continue({ url }). -
browser.evaluatetakes and returns JSON only, so the report can record and redact the result. Pass values in througharg. -
A password is a
Secretwith no string value, and the model never sees it. See Authentication. -
Sessions are per run.
test.setupsaves 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.jsonto reuse across runs. -
No raw
Pagein tests. Nothing on a raw page is recorded, redacted, or masked.surfaceOf(engine)is for custom executors, not test code.
