diff --git a/docs/migrate/playwright.mdx b/docs/migrate/playwright.mdx index d41402b16a..333e9cfe9f 100644 --- a/docs/migrate/playwright.mdx +++ b/docs/migrate/playwright.mdx @@ -73,14 +73,14 @@ A Playwright key such as `testDir`, `baseURL`, `use`, `webServer`, or | `use.extraHTTPHeaders` | `web({ headers })`, sent to the app's site only | renamed | | `chromium.connectOverCDP(url)` | `web({ connect: { cdpEndpoint: () => url } })`, chromium only | renamed | | `use.connectOptions` (`wsEndpoint`) | `web({ connect })` attaches over CDP only | missing | -| `retries`, `workers`, `timeout` | the same names at the top level; the defaults differ, see [below](#defaults-that-differ) | same | +| `retries`, `workers`, `timeout` | the same names at the top level. `workers` takes an integer from 1 to 1024, not `'50%'`; `retries` stops at 10. The defaults differ, see [below](#defaults-that-differ) | renamed | | `expect.timeout` | `assertionTimeout` | renamed | | `use.actionTimeout` | `actionTimeout` | renamed | | `use.navigationTimeout` | `timeout`, the test budget; `browser.goto(url, { timeout })` overrides one call | renamed | | `use.storageState`, a `setup` project in `projects[].dependencies` | `test.setup(title, { sessions }, fn)` with `session.save(name)`, then `{ session }` on a test, see [Signing in](/authentication); no file, see [What differs on purpose](#what-differs-on-purpose) | by design | | `use.storageState: { cookies }` with fixed values | `browser.setCookies(cookies)` in a fixture | renamed | -| `use.trace` | `trace`: `'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. The default differs, see [below](#defaults-that-differ) | same | -| `use.video` | `video`, with the modes and places of `trace`, and `--video [mode]` | same | +| `use.trace` | `trace`: `'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 [below](#defaults-that-differ) | renamed | +| `use.video` | `video`, with the modes and places of `trace`, and `--video [mode]`; no `{ mode, size }` object | renamed | | `use.headless: false` | `--headed` on the CLI | renamed | | `use.locale`, `use.timezoneId` | `web({ locale, timezoneId })` | renamed | | `use.colorScheme`, `use.reducedMotion` | `web({ colorScheme, reducedMotion })` | renamed | @@ -150,7 +150,7 @@ uses it declares `requires: ['browser']` and other targets skip it. Calls on | `page.waitForSelector(selector)` | `browser.locator(selector).waitFor()`; a locator is strict, see [What differs on purpose](#what-differs-on-purpose) | renamed | | `page.click(selector)`, `page.fill(selector, value)`, `page.getAttribute(selector, name)`, and the other `page` methods that take a selector | `browser.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 purpose](#what-differs-on-purpose) | renamed | | `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 path | missing | -| `page.frameLocator('#frame')` | `browser.frameLocator('#frame')`, then `screen` queries inside it | web only | +| `page.frameLocator('#frame')` | `browser.frameLocator('#frame')`, then `screen` queries inside it. An element inside a `visibility: hidden` iframe reads as visible | web only | @@ -162,21 +162,22 @@ uses it declares `requires: ['browser']` and other targets skip it. Calls on | `dblclick()` | `doubleTap()`; `dblclick()` is an alias | same | | `click({ position })` | `tap({ position })`, an offset from the node's top-left corner | renamed | | `click({ force })` | `tap({ position })` skips every actionability check but the scroll into view | missing | -| `click({ modifiers })`, `dblclick({ modifiers })` | `tap({ modifiers })`, `doubleTap({ modifiers })` or `dblclick({ modifiers })`, `secondaryTap({ modifiers })`; not beside `position` yet | same | +| `click({ modifiers })`, `dblclick({ modifiers })` | `tap({ modifiers })`, `doubleTap({ modifiers })` or `dblclick({ modifiers })`, `secondaryTap({ modifiers })`; not beside `position` yet | renamed | | `click({ clickCount, delay, trial })` | not yet | missing | | `{ trial }`, `{ force }`, `{ noWaitAfter }` on `check()`, `fill()`, and the other actions | an unknown option is `INVALID_ARGUMENT`, never ignored | missing | | `fill(value)` | the same; also takes a `Secret` | same | | `pressSequentially(text, { delay })` | the same; keystrokes through the platform keyboard, a `Secret` is refused | same | | `press(key)` | the same; modifiers join with `+`, see the [key grammar](/reference/engine#keys) | same | -| `clear()`, `focus()`, `hover()`, `setInputFiles()`, `dragTo()` | the same | same | -| `check()`, `uncheck()` | the same, except when the state updates late or the click removes the control, see [What differs on purpose](#what-differs-on-purpose) | by design | +| `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 | renamed | +| `check()`, `uncheck()` | the same, except when the state updates late or the click removes the control, see [What differs on purpose](#what-differs-on-purpose). `uncheck()` on a checked radio, `role=radio` included, is `NOT_ACTIONABLE` | by 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 value | by design | | `selectOption(['a', 'b'])` | one option per call. An array is `INVALID_ARGUMENT` | missing | -| `setInputFiles({ name, buffer })` | paths only, resolved from the project root | missing | +| `setInputFiles({ name, buffer })`, `setInputFiles([])` | paths only, resolved from the project root; an empty list is `INVALID_ARGUMENT`, so there is no clear | missing | | `scrollIntoViewIfNeeded()` | `scrollIntoView()` | renamed | | `locator.innerText()` | `textContent()`, whitespace collapsed to single spaces | renamed | | `locator.textContent()` | the rendered text, what `innerText()` reads, see [What differs on purpose](#what-differs-on-purpose) | by design | -| `inputValue()`, `getAttribute()`, `isVisible()`, `isHidden()`, `isEnabled()`, `isDisabled()`, `boundingBox()` | the same | same | +| `inputValue()` | the same on an input, textarea, or select; `""` on any other element, where Playwright throws | missing | +| `getAttribute()`, `isVisible()`, `isHidden()`, `isEnabled()`, `isDisabled()`, `boundingBox()` | the same | same | | `isChecked()` | the same on a checkbox, radio, or `aria-checked` node; `false` on any other, see [What differs on purpose](#what-differs-on-purpose) | by design | | `isEditable()` | not yet | missing | | `waitFor({ state: 'visible' })`, `'hidden'`, `'attached'`, `'detached'` | the same | same | @@ -206,6 +207,7 @@ uses it declares `requires: ['browser']` and other targets skip it. Calls on | `{ ignoreCase }` on `toHaveText()`, `toContainText()`, `toHaveAccessibleName()`, `toHaveAttribute(name, value)` | the same | same | | `toBeChecked({ indeterminate })`, `{ useInnerText }` | `INVALID_ARGUMENT`, so the matcher never passes on its default | missing | | `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 purpose](#what-differs-on-purpose) | by design | | a positive matcher on several matches | `LOCATOR_AMBIGUOUS` at once, see [What differs on purpose](#what-differs-on-purpose) | by design | | `toBeAttached()` | the same; passes on a hidden match too | same | | `toBeEmpty()`, `toBeInViewport()`, `toBeEditable()`, `toHaveRole()`, `toHaveAccessibleDescription()` | not yet | missing | @@ -215,13 +217,14 @@ uses it declares `requires: ['browser']` and other targets skip it. Calls on | `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 comparison](/visual-testing) | same | | `toHaveScreenshot({ fullPage, clip, animations, caret, scale, stylePath })` | always the viewport, at CSS scale, animations stopped and the caret hidden | missing | | `toMatchSnapshot()`, `toMatchAriaSnapshot()` | not yet | missing | -| `expect(value).toBe()`, `toEqual()`, `toMatch()`, `toBeTruthy()`, `toBeCloseTo()`, `toHaveLength()`, `toMatchObject()`, `toHaveProperty()`, and the rest | the same, except `toContain`, below, see [value matchers](/reference/expect#value-matchers) | same | +| `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](/reference/expect#value-matchers). `toContain` differs, below | same | | `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 same | by design | -| `toStrictEqual()`, `toThrow()`, `toBeInstanceOf()` | `toEqual` on the shape you need | missing | -| `expect.any()`, `objectContaining()`, `arrayContaining()`, `stringMatching()` | the same, plus `anything()` and `stringContaining()`, see [asymmetric matchers](/reference/expect#asymmetric-matchers) | same | -| `expect(async () => { ... }).toPass()` | `expect.poll(read).toBe(...)`; poll an array with `toEqual([a, b])` for several values at once | renamed | -| `expect.poll()` | the same | same | -| `expect.soft()` | the same; kept failures fail the attempt once the body settles, see [soft assertions](/reference/expect#soft-assertions) | same | +| `toStrictEqual()`, `toThrow()`, `toBeInstanceOf()`, `toBeNaN()`, `toContainEqual()` | `toEqual` on the shape you need; `toContain` for `toContainEqual` | missing | +| `expect.any()`, `anything()`, `objectContaining()`, `arrayContaining()`, `stringMatching()`, `stringContaining()` | the same, see [asymmetric matchers](/reference/expect#asymmetric-matchers) | same | +| `expect.closeTo()`, `expect.not.objectContaining()` and the other `expect.not.*` | not yet | missing | +| `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 interval | missing | +| `expect.poll(read, { intervals })` | `expect.poll(read, { interval })`, one number in ms, default 100 | renamed | +| `expect.soft()` | the same; kept failures fail the attempt once the body settles. In `afterEach` a soft failure throws at once. See [soft assertions](/reference/expect#soft-assertions) | same | | `expect(locator, 'message')` | `expect(locator)`; a locator failure already names the locator, the matcher, and what was observed. Only a value expectation takes a message | by design | | `expect.extend()` | not yet | missing | | `expect(promise).resolves`, `.rejects` | `await` first, then `expect(value)` | missing | @@ -232,6 +235,7 @@ uses it declares `requires: ['browser']` and other targets skip it. Calls on | Playwright | e2e | Status | | --- | --- | --- | | `page.goto(path)` | `app.open(path)`; `browser.goto(url, { waitUntil, timeout })` for the browser options | renamed | +| `page.goto('data:text/html,...')` | `POLICY_DENIED`, see [What differs on purpose](#what-differs-on-purpose). Serve the HTML from a `browser.route` with `route.fulfill({ body, contentType: 'text/html' })` on an app URL | by design | | `const response = await page.goto()` | `app.open` and `browser.goto` resolve to `void`; take the response from `browser.waitForResponse` | by design | | `page.goBack()` | `app.back()`, or `browser.back()` | renamed | | `page.goForward()`, `page.reload()` | `browser.forward()`, `browser.reload()` | web only | @@ -243,7 +247,7 @@ uses it declares `requires: ['browser']` and other targets skip it. Calls on | `page.setViewportSize()` | `browser.setViewport()`, before or after the first navigation | web only | | `page.viewportSize()` | `browser.evaluate(() => ({ width: innerWidth, height: innerHeight }))` | missing | | `page.screenshot()` | `app.screenshot(label)`: the viewport, redacted, attached to the report; no `fullPage` | renamed | -| a fresh `context` per test | every attempt starts in a fresh context; `app.restart()` recreates it, `app.clearState()` also clears storage | same | +| a fresh `context` per test | every 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:blank` | same | | `page.pause()` | `--headed` to watch, [`e2e mcp`](/mcp-server) to drive the app from a coding agent | missing | @@ -251,14 +255,15 @@ uses it declares `requires: ['browser']` and other targets skip it. Calls on | Playwright | e2e | Status | | --- | --- | --- | -| `page.route(pattern, handler)` | `browser.route(pattern, handler)`; a string or `RegExp` pattern, no predicate function; the handler decides exactly once | web 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 | web only | -| `route.continue({ url, method, headers, postData })`, `route.fallback()` | the same; a `url` goes through the navigation rule, and `fallback()` takes no overrides | web only | +| `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, where Playwright reads it literally; `{a,b}` is literal, and `**/` needs at least one segment | web 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, not a `Buffer`, and each header has one value, so one `set-cookie` | web 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. Header values are strings, so `undefined` can't delete a header. `fallback()` takes no overrides | web only | | `route.fetch()` | argument-free: no `timeout`, `headers`, or `maxRedirects` options, and redirects return unfollowed; returns `{ url, status, headers, text(), json() }` without deciding the route | web only | | `route.abort(code)`, `route.fallback(overrides)` | none yet; `abort()` takes no error code | missing | | `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`, `json()`, `text()`. A string is a glob tested against the whole URL, query included, and never resolved against `app.url`: Playwright's `'/api/orders'` is the full URL or `'**/api/orders'`, and `?` matches any one character (write `'\\?'` for a literal one) | web only | +| `page.waitForResponse(pattern)` | `browser.waitForResponse(pattern)`: a string or `RegExp`, no predicate function; `url`, `status`, `headers`, `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 timeout | a positive number of ms. `0` on `browser.waitForResponse`, `waitForDownload`, or `toHaveScreenshot` is `INVALID_ARGUMENT`; on other calls it times out at once | missing | | `response.ok()`, `response.body()`, `response.request()` | `status` and `text()` | missing | | `page.waitForRequest()`, `request.postDataJSON()` | none yet for `waitForRequest`; `route.request.postData` is a string | missing | | `routeFromHAR()`, `routeWebSocket()` | not yet | missing | @@ -266,7 +271,7 @@ uses it declares `requires: ['browser']` and other targets skip it. Calls on | `page.waitForEvent('download')` | `browser.waitForDownload(() => trigger)` | web only | | `page.waitForEvent('popup')`, `context.on('page')` | a window the app opens is not driven | missing | | `page.on('console')`, `page.on('pageerror')` | assert on what the page shows | missing | -| `page.evaluate(fn, arg)` | `browser.evaluate(fn, arg)`; JSON in and out, no handles | web only | +| `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 them | web only | | `page.addInitScript(script, arg)`, `context.addInitScript()` | `browser.addInitScript(script, arg)`, or `web({ initScripts })` for every test; pass `{ content }` as a plain string | web only | | `page.emulateMedia({ colorScheme, reducedMotion })` | `browser.emulateMedia()`, for every open tab and every tab opened after it; `media`, `forcedColors`, and `contrast` are not yet supported | web only | | `page.exposeFunction()`, `addStyleTag()`, `setExtraHTTPHeaders()`, `clock` | none yet; for `addStyleTag`, `browser.evaluate` can append a `