e2e 0.15.2 → 0.17.0

package/docs/executors.mdx

@@ -128,7 +128,7 @@ The executor receives this context:
 
 | Member | What it is |
 | --- | --- |
-| `ctx.step` | The instruction, params, and `index` in the attempt's timeline |
+| `ctx.step` | The instruction, params, and `index` in the attempt's timeline. A registered secret value the test spelled into the instruction or a param string reads `<secret:name>`; a `secrets.get()` handle is a placeholder you fill with `typeSecret` |
 | `ctx.observe({ tree, pixels })` | Redacted screen text, with an optional node tree and masked screenshot |
 | `ctx.actions` | Checked and recorded actions: `tap`, `doubleTap`, `longPress`, `secondaryTap`, `hover`, `type`, `typeSecret`, `press`, `select`, `check`, `drag`, `scrollTo`, `scrollUntil`, `upload`, `scroll`, `navigate`, `back`, and the point and keyboard verbs below |
 | `ctx.target` | The target's `name` and `platform`, and `verbs`, the actions its engine supports. Offer only these to the model. |
@@ -215,8 +215,10 @@ default, follows the configured cache mode. A recorded step replays without
 calling `runStep`. A replay that stops partway calls `runStep` with
 `ctx.replayedPrefix`: continue from the current screen and do not redo the
 replayed actions. What a step does through `ctx.actions` is recorded; a
-mutating tool call leaves a gap the executor fills on replay. Entries are not
-keyed by executor, so an entry one agent recorded replays for another.
+mutating tool call leaves a gap the executor fills on replay. Entries are
+keyed by the configured agent and its context, so an entry one agent
+recorded never replays for another; the executor itself is not part of the
+key, so changing an agent's executor keeps its entries.
 
 `'off'` never replays or records the executor's steps, so every step reaches
 `runStep`. Use it for a brain whose own history or memory is the source of

package/docs/github.mdx

@@ -63,7 +63,10 @@ Upload artifacts even when a retry passes. Each failure's evidence links open
 the run's Artifacts section; inside the download, every test has a directory
 named after it and the agent that ran it
 (`web/tests_billing.e2e.ts__upgrades/default/attempt-0/`), so keep
-`path: .e2e/artifacts` and the download lines up with the report. A project
+`path: .e2e/artifacts` and the download lines up with the report. A
+`--last-failed` rerun keeps the first run's directories and puts its own
+under `rerun-1/`, so a flaky test's failed attempt still links to its own
+files. A project
 below the checkout root, such as `packages/e2e-tests`, gets source links under
 that path. The checkout root is the nearest directory holding `.git` inside
 `GITHUB_WORKSPACE`, so `actions/checkout` with a `path` input works too.
@@ -143,9 +146,14 @@ passes:
 
 The comment covers the whole suite, not only the tests the rerun ran again.
 A test that failed and then passed shows as flaky, a test that failed twice
-stays failed, and the rest keep their first-pass results. The comment
-matches the job's status: it stays red when another filter kept a failed
-test out of the rerun.
+stays failed, one that was interrupted and then passed shows as passed, and
+the rest keep their first-pass results. The comment stays red while the
+rerun left out something it owed: a failed test, one `--max-failures` stopped
+before it ran, or a failed `beforeAll` or `afterAll` whose tests another
+filter kept out of the rerun. It shows ⏹️ when the rerun left out a test the
+first pass never finished. The rerun's own exit code counts only what it ran.
+A failed attempt's evidence links to the first run's files, which the rerun
+keeps.
 
 ## Matrix jobs
 

package/docs/{writing-tests.mdx → goals.mdx}

@@ -1,10 +1,11 @@
 ---
-title: Writing tests
-description: Goals, checks, extraction, and the deterministic APIs.
+title: Goals
+description: Write test steps as goals with agent.act, and structure the tests around them.
 ---
 
-Use agent calls for goals and questions about the screen. Use `screen` and
-`expect` when you know the exact action or value to check. A test can freely mix both.
+Use agent calls for goals and questions about the screen. Use
+[locators](/locators) when you know the exact action or value to check. A test
+can freely mix both.
 
 ```ts title="tests/todos.e2e.ts"
 import { test, expect } from 'e2e';
@@ -23,7 +24,9 @@ test('todos survive a filter round-trip', async ({ app, agent, screen }) => {
 ## Goals: `agent.act`
 
 Give `act` one goal. The agent chooses and performs the actions, then returns
-when the goal passes or throws when it fails.
+when the goal passes or throws when it fails. Await every agent and screen
+call, and every `expect.poll`; a test that returns while one is still running
+fails with `STEP_NOT_AWAITED`.
 
 ```ts
 await agent.act('complete checkout with the test card');
@@ -68,60 +71,9 @@ A step can pass, fail, or be blocked by something such as missing credentials.
 [How agent steps work](/agent-steps#how-a-step-ends) explains the verdicts and
 exit codes.
 
-## Checks: `assert`, `waitFor`, `extract`
-
-`assert` checks a statement against the current screen. A false statement
-fails with `ASSERTION_FAILED`. If the screen does not provide enough evidence,
-it fails with `ASSERTION_INCONCLUSIVE`.
-
-The judging model sees the statement and the current screen. It does not see
-earlier steps or the acting agent's summaries.
-
-```ts
-await agent.assert('the dashboard shows a trial badge');
-```
-
-`assert` checks the screen now. Use `waitFor` when the condition may become true
-later. It polls the screen and only calls the model when the observation changes.
-
-```ts
-await agent.waitFor('the export finishes and a download link appears', {
-  interval: 500,
-  timeout: 120_000,
-});
-```
-
-`extract` reads structured data from the screen. Provide a
-[Standard Schema](https://standardschema.dev) validator, such as Zod, to define
-the result.
-
-```ts
-import { z } from 'zod';
-
-const data = await agent.extract('every todo title and how many remain', {
-  schema: z.object({ titles: z.array(z.string()), remaining: z.number().int() }),
-});
-expect(data.titles).toContain('Buy milk');
-```
-
-<Tip>
-For model-generated descriptions, check the relevant meaning rather than the
-entire sentence. Use a locator assertion when the exact text matters.
-</Tip>
-
-### Judging pixels
-
-By default, judgments read a redacted text snapshot of the screen. Add
-`vision: true` for visual checks, such as charts or layout. Use
-`vision: 'only'` to judge the screenshot alone.
-
-```ts
-await agent.assert('the chart trends upward', { vision: true });
-await agent.assert('the search form is not covered by a banner', { vision: 'only' });
-```
-
-`act` requests screenshots itself when it needs them, so it has no `vision`
-option. On supported engines, it can tap and type at points in the image:
+`act` requests screenshots itself when it needs them, so unlike the
+[judgments](/assertions#judging-pixels) it has no `vision` option. On
+supported engines, it can tap and type at points in the image:
 
 ```ts
 await agent.act('enter the code 3141 on the drawn keypad and press OK');
@@ -131,44 +83,8 @@ Images add input tokens. Screenshots are withheld for the rest of an attempt
 after a secret is filled. The [agent reference](/reference/agent#vision)
 lists the modes and restrictions.
 
-## Deterministic APIs: `screen` and `expect`
-
-Use locators to interact with known controls and check exact values.
-An `expect` after `act` checks the exact result. It is also what lets the
-[replay cache](/cache) record the step and keep it.
-
-```ts
-// Semantic queries: role and name first, label second, test ID last.
-await screen.getByRole('button', 'Sign in').tap();
-await screen.getByLabel('Email').fill('ada@example.test');
-await screen.getByTestId('todo').first().tap();
-
-// Scope into a row, gesture like a user:
-const row = screen.getByRole('listitem').filter({ hasText: 'Design review' });
-await row.getByRole('button', 'Archive').tap();
-await screen.swipe({ direction: 'up', momentum: 'fast' });
-
-// Coordinates, for what the tree does not list:
-await screen.getByRole('image', 'Seat map').tap({ position: { x: 120, y: 48 } });
-await screen.swipe({ from: { x: 300, y: 400 }, to: { x: 40, y: 400 } });
-
-// Polling assertions:
-await expect(screen.getByRole('status')).toHaveText('2 remaining');
-await expect(screen.getByRole('heading', 'Dashboard')).toBeVisible();
-```
-
-Actions and single-node reads or assertions fail when a query matches more
-than one node. Narrow it with `.filter()`, `.first()`, or `.nth()`.
-Locator assertions retry until they pass or time out. Direct reads such as
-`textContent()` do not retry a mismatched value.
-
-Use the `browser` fixture for browser features such as routes, cookies, dialogs,
-frames, and downloads; see [Working with the browser](/browser). The
-[screen reference](/reference/screen) lists every query and action.
-
-Share setup and cleanup through `test.extend`. A fixture can create a test
-workspace before the test and delete it afterward, including when the test
-fails. See [Your own fixtures](/reference/test#your-own-fixtures).
+To check what a goal left on screen, follow it with an
+[assertion](/assertions) or a [locator check](/locators).
 
 ## Tests without a screen
 
@@ -220,6 +136,10 @@ fixtures or hooks. When a flow must span several tests, mark the group
 `{ serial: true }`. Members share app state, run in order on one worker,
 and retry as a whole.
 
+Share setup and cleanup through `test.extend`. A fixture can create a test
+workspace before the test and delete it afterward, including when the test
+fails. See [Your own fixtures](/reference/test#your-own-fixtures).
+
 ## Run one test
 
 <CodeGroup>
@@ -247,10 +167,10 @@ The [CLI reference](/reference/cli#e2e-run) lists every flag.
 ## Next
 
 <CardGroup cols={2}>
-  <Card title="Signing in" icon="key" href="/authentication">
-    Sessions and secrets.
+  <Card title="Assertions" icon="circle-check" href="/assertions">
+    Check the screen with `assert`, `waitFor`, and `extract`.
   </Card>
-  <Card title="Agents and personas" icon="users" href="/agents">
-    Several agents in one suite, and running a flow as each of them.
+  <Card title="Locators" icon="crosshairs" href="/locators">
+    Exact actions and checks with `screen` and `expect`.
   </Card>
 </CardGroup>

package/docs/index.mdx

@@ -9,9 +9,9 @@ e2e is a next-generation testing framework for web and mobile
 apps, built to keep up with the speed we ship software today.
 
 You choose how agentic each test is: fully deterministic with
-[locators](/writing-tests#deterministic-apis-screen-and-expect) and
+[locators](/locators) and
 [assertions](/reference/expect#locator-matchers), fully driven by an agent
-from [goals](/writing-tests#goals-agent-act) in natural language, or a mix of
+from [goals](/goals) in natural language, or a mix of
 both in the same test.
 
 <VideoCard
@@ -70,8 +70,8 @@ you shipped.
   <Card title="Quickstart" icon="rocket" href="/quickstart">
     One prompt for your coding agent, or set up by hand.
   </Card>
-  <Card title="Writing tests" icon="pen-to-square" href="/writing-tests">
-    Write goals, check outcomes, and extract data.
+  <Card title="Goals" icon="pen-to-square" href="/goals">
+    Write test steps as goals in natural language.
   </Card>
   <Card title="Coding agents" icon="robot" href="/coding-agents">
     Let your coding agent write, run, and debug tests.

package/docs/integrations/kernel.mdx

@@ -90,7 +90,7 @@ cookies and storage are not there.
 that browser's default context, on its own first tab, so a `profile` applies
 and the live view shows one tab. It costs a browser start per test and
 carries the limits of a [per-attempt lease](/browser#hosted-browsers): no
-`headers`, `basicAuth`, or `userAgent`, no `app.clearState()`, and no
+`headers`, `basicAuth`, `userAgent`, `locale`, or `timezoneId`, no `app.clearState()`, and no
 [sessions](/authentication), which fail the run before any test.
 
 ## Recordings

package/docs/locators.mdx

@@ -0,0 +1,64 @@
+---
+title: Locators
+description: Deterministic actions and checks with screen and expect.
+---
+
+Use locators to interact with known controls and check exact values. Locator
+steps call no model.
+
+```ts title="tests/todos.e2e.ts"
+import { test, expect } from 'e2e';
+
+test('adds a todo', async ({ app, screen }) => {
+  await app.open('/todos');
+  await screen.getByLabel('New todo').fill('Buy milk');
+  await screen.getByRole('button', 'Add').tap();
+  await expect(screen.getByTestId('todo')).toHaveCount(1);
+});
+```
+
+An `expect` after an [`agent.act` goal](/goals) checks the exact result. It is
+also what lets the [replay cache](/cache) record the step and keep it.
+
+## Queries, actions, and assertions
+
+```ts
+// Semantic queries: role and name first, label second, test ID last.
+await screen.getByRole('button', 'Sign in').tap();
+await screen.getByLabel('Email').fill('ada@example.test');
+await screen.getByTestId('todo').first().tap();
+
+// Scope into a row, gesture like a user:
+const row = screen.getByRole('listitem').filter({ hasText: 'Design review' });
+await row.getByRole('button', 'Archive').tap();
+await screen.swipe({ direction: 'up', momentum: 'fast' });
+
+// Coordinates, for what the tree does not list:
+await screen.getByRole('image', 'Seat map').tap({ position: { x: 120, y: 48 } });
+await screen.swipe({ from: { x: 300, y: 400 }, to: { x: 40, y: 400 } });
+
+// Polling assertions:
+await expect(screen.getByRole('status')).toHaveText('2 remaining');
+await expect(screen.getByRole('heading', 'Dashboard')).toBeVisible();
+```
+
+Actions and single-node reads or assertions fail when a query matches more
+than one node. Narrow it with `.filter()`, `.first()`, or `.nth()`.
+Locator assertions retry until they pass or time out. Direct reads such as
+`textContent()` do not retry a mismatched value.
+
+Use the `browser` fixture for browser features such as routes, cookies, dialogs,
+frames, and downloads; see [Working with the browser](/browser). The
+[screen reference](/reference/screen) lists every query and action, and the
+[expect reference](/reference/expect#locator-matchers) lists every matcher.
+
+## Next
+
+<CardGroup cols={2}>
+  <Card title="Signing in" icon="key" href="/authentication">
+    Sessions and secrets.
+  </Card>
+  <Card title="Agents and personas" icon="users" href="/agents">
+    Several agents in one suite, and running a flow as each of them.
+  </Card>
+</CardGroup>

package/docs/migrate/cypress.mdx

@@ -115,8 +115,8 @@ Start with a spec that often breaks and whose fixed `cy.wait` calls can
 become assertions on the condition the test needs.
 
 <CardGroup cols={2}>
-  <Card title="Writing tests" icon="pen-to-square" href="/writing-tests">
-    Goals, checks, extraction, and the deterministic APIs.
+  <Card title="Goals" icon="pen-to-square" href="/goals">
+    Write test steps as goals instead of scripted selectors.
   </Card>
   <Card title="Working with the browser" icon="globe" href="/browser">
     Routes, dialogs, downloads, iframes, and page evaluation.

package/docs/migrate/maestro.mdx

@@ -223,7 +223,7 @@ often need updating.
   <Card title="Testing iOS and Android" icon="mobile-screen" href="/mobile">
     Configure your app and devices.
   </Card>
-  <Card title="Writing tests" icon="pen-to-square" href="/writing-tests">
-    Goals, checks, extraction, and the deterministic APIs.
+  <Card title="Goals" icon="pen-to-square" href="/goals">
+    Write test steps as goals instead of scripted selectors.
   </Card>
 </CardGroup>

package/docs/migrate/playwright.mdx

@@ -3,8 +3,8 @@ title: From Playwright
 description: Run e2e alongside Playwright and migrate tests one file at a time.
 ---
 
-`@e2e-dev/web` uses your installed Playwright when its version satisfies
-the engine's peer dependency (`>=1.63.0 <2`). Both runners can stay in one
+`@e2e-dev/web` brings its own pinned `playwright-core`, so your
+`@playwright/test` version is yours to keep. Both runners can stay in one
 project. e2e reads `e2e.config.ts` and finds `tests/**/*.e2e.ts` by default,
 so keep the two file patterns apart.
 
@@ -59,7 +59,8 @@ A Playwright key the runner recognizes (`testDir`, `baseURL`, `webServer`,
 | `use.trace` | `trace` with the same modes (`'off'`, `'on'`, `'retain-on-failure'`, `'on-first-retry'`, `'on-all-retries'`), at the top of the config, per target, `test('x', { trace }, ...)`, or `--trace [mode]` for one run; the default differs, see [below](#defaults-that-differ) | same |
 | `use.video` | `video` with the same modes as `trace`, at the top of the config, per target in place of a project, `test('x', { video }, ...)` in place of `test.use`, or `--video [mode]` for one run | same |
 | `use.headless: false` | `--headed` on the CLI | renamed |
-| `use.locale`, `timezoneId`, `colorScheme`, `geolocation`, `permissions` | not yet | missing |
+| `use.locale`, `use.timezoneId` | `web({ locale, timezoneId })` | renamed |
+| `colorScheme`, `geolocation`, `permissions` | not yet | missing |
 | `use.userAgent` | `web({ userAgent })` | renamed |
 | `devices['iPhone 15']`, `deviceScaleFactor`, `isMobile`, `hasTouch` | not yet; `web({ viewport })` sets the size only | missing |
 | `ignoreHTTPSErrors`, `bypassCSP`, `offline`, `launchOptions`, `proxy` | not yet | missing |
@@ -139,7 +140,9 @@ what to do today.
 | `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()`, `check()`, `uncheck()`, `focus()`, `hover()`, `selectOption()`, `setInputFiles()`, `dragTo()` | the same | same |
+| `clear()`, `focus()`, `hover()`, `setInputFiles()`, `dragTo()` | the same | same |
+| `check()`, `uncheck()` | the same, except for a control the click removes or navigates away from, such as a radio the app replaces with its selected view: the click landed, so the action passes, even when the app renders an unchecked control in its place. Playwright fails it because it cannot read the state back. Assert on what replaced the control | 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'])` | not yet; one option per call. An array is `INVALID_ARGUMENT` | missing |
 | `setInputFiles({ name, buffer })` | not yet; paths only, resolved from the project root | missing |
 | `scrollIntoViewIfNeeded()` | `scrollIntoView()` | renamed |
@@ -149,8 +152,7 @@ what to do today.
 | `isChecked()` | the same on a checkbox, radio, or `aria-checked` node; `false` on any other node, where Playwright throws | by design |
 | `isHidden()`, `isDisabled()` | the same | same |
 | `isEditable()` | not yet | missing |
-| `waitFor({ state: 'visible' })`, `'hidden'` | the same | same |
-| `waitFor({ state: 'attached' })`, `'detached'` | not yet; `expect(locator).toBeAttached()` and `.not.toBeAttached()` | missing |
+| `waitFor({ state: 'visible' })`, `'hidden'`, `'attached'`, `'detached'` | the same | same |
 | `locator.evaluate(fn)`, `evaluateAll(fn)` | not yet; `browser.evaluate(fn, selector)` with a CSS selector argument | missing |
 | `locator.screenshot()` | not yet; `app.screenshot(label)` captures the viewport | missing |
 | `innerHTML()`, `dispatchEvent()`, `selectText()`, `blur()`, `highlight()` | not yet; `browser.evaluate` | missing |
@@ -171,13 +173,16 @@ what to do today.
 | `toHaveText()`, `toContainText()` | compare the rendered text, as `{ useInnerText: true }` does in Playwright | by design |
 | `toHaveValue()`, `toHaveAttribute()`, `toHaveCount()`, `toHaveAccessibleName()` | the same | same |
 | `toHaveText(['a', 'b'])`, `toContainText([...])` on several matches | the same: `toHaveText` needs the count to match, `toContainText` an ordered subsequence | same |
+| `toBeChecked({ checked: false })`, `toBeEnabled({ enabled })`, `toBeVisible({ visible })`, `toBeAttached({ attached })` | the same | same |
+| `{ ignoreCase }` on `toHaveText()`, `toContainText()`, `toHaveAccessibleName()`, `toHaveAttribute(name, value)` | the same | same |
+| `toBeChecked({ indeterminate })`, `{ useInnerText }` | not yet; `INVALID_ARGUMENT`, so the matcher never passes on its default | missing |
 | `toHaveAttribute('aria-selected', 'true')`, `'aria-expanded'` | `toBeSelected()`, `toBeExpanded()` | renamed |
 | a positive matcher on several matches | `LOCATOR_AMBIGUOUS` at once; narrow with `filter`, `first`, or `{ visible: true }` | by design |
 | `toBeAttached()` | the same; passes on a hidden match too | same |
 | `toBeEmpty()`, `toBeInViewport()`, `toBeEditable()`, `toHaveRole()`, `toHaveAccessibleDescription()` | not yet | missing |
 | `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 attribute | web only |
 | `toHaveCSS()`, `toHaveId()`, `toHaveJSProperty()`, `toContainClass()`, `toHaveValues()` | not yet; `browser.evaluate` plus a value matcher | missing |
-| `expect(page).toHaveURL()`, `toHaveTitle()` | `expect(browser).toHaveURL()`, `toHaveTitle()` | web only |
+| `expect(page).toHaveURL()`, `toHaveTitle()` | `expect(browser).toHaveURL()`, `toHaveTitle()`; `toHaveURL` takes `ignoreCase` | web only |
 | `toHaveScreenshot()`, `toMatchSnapshot()` | not yet; `agent.assert('...', { vision: true })` is a judgment, not a pixel diff | missing |
 | `toMatchAriaSnapshot()` | not yet | missing |
 | `expect(value).toBe()`, `toEqual()`, `toMatch()`, `toBeTruthy()`, `toBeCloseTo()` and the rest | the same, except `toContain`, below, see [value matchers](/reference/expect#value-matchers) | same |
@@ -201,7 +206,7 @@ what to do today.
 | `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()`; a string or `RegExp`, no predicate function | web only |
+| `page.waitForURL()` | `browser.waitForURL()`; a string or `RegExp`, no predicate function, and `timeout` is its only option, so `waitUntil` is `INVALID_ARGUMENT` | web only |
 | `page.waitForLoadState()` | not yet; `browser.goto(url, { waitUntil })` on the navigation itself | missing |
 | `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 away | by design |
@@ -216,9 +221,9 @@ what to do today.
 | 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, status, headers })` | the same; `json` or `body`, never both | web only |
-| `route.fulfill({ path, contentType })`, `route.fetch()` | not yet; read the file in the test and pass `body` | missing |
-| `route.continue(overrides)`, `route.abort(code)` | `continue()` and `abort()` take no arguments | missing |
+| `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 |
+| `route.fetch()`, `route.abort(code)`, `route.fallback(overrides)` | not yet; `abort()` takes no error code | missing |
 | `page.unroute()` | `browser.unroute()` | web only |
 | `page.waitForResponse(pattern)` | `browser.waitForResponse(pattern)`: a string or `RegExp`, no predicate function; `url`, `status`, `headers`, `json()`, `text()` | web only |
 | `response.ok()`, `response.body()`, `response.request()` | not yet; `status` and `text()` | missing |
@@ -229,7 +234,8 @@ what to do today.
 | `page.waitForEvent('popup')`, `context.on('page')` | not yet; a window the app opens is not driven | missing |
 | `page.on('console')`, `page.on('pageerror')` | not yet; assert on what the page shows | missing |
 | `page.evaluate(fn, arg)` | `browser.evaluate(fn, arg)`; JSON in and out, no handles | web only |
-| `page.exposeFunction()`, `addInitScript()`, `addStyleTag()`, `setExtraHTTPHeaders()`, `emulateMedia()`, `clock` | not yet; `browser.evaluate` appends a `<style>` once the page is open, and returns `null` since its result must be JSON | missing |
+| `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.exposeFunction()`, `addStyleTag()`, `setExtraHTTPHeaders()`, `emulateMedia()`, `clock` | not yet; `browser.evaluate` appends a `<style>` once the page is open, and returns `null` since its result must be JSON | missing |
 | `context.addCookies()`, `context.cookies()` | `browser.setCookies()`, `browser.cookies()` | web only |
 | `context.clearCookies()` | not yet; `app.clearState()` also clears other persisted state and recreates the context | missing |
 | `request` fixture | Node `fetch`, see [Testing APIs](/api-testing) | by design |
@@ -281,9 +287,9 @@ what to do today.
 | `--update-snapshots` | no equivalent; there is no pixel assertion | missing |
 | `--list` | `npx e2e list`, with the same selection flags | renamed |
 | `npx playwright codegen` | `npx e2e explore` walks the app from a goal and reports what it found; `npx e2e mcp` gives a coding agent a live session so it writes the test while driving the app, see [Coding agents](/coding-agents) | renamed |
-| `npx playwright show-trace` | the same, on `trace/<name>.zip` under the attempt's artifact directory | same |
+| `npx playwright show-trace` | `npx playwright-core@1.63.0 show-trace` (`pnpm dlx` under pnpm), on `trace/<name>.zip` under the attempt's artifact directory | renamed |
 | `npx playwright show-report` | not yet; `.e2e/summary.md` from the `markdown` reporter | missing |
-| `npx playwright install` | still works; the engine also installs a missing browser once per run, before the run's clock starts | same |
+| `npx playwright install` | `npx @e2e-dev/web install`, for the Playwright version the engine pins; the engine also installs a missing browser once per run, before the run's clock starts | renamed |
 
 ## Page objects
 
@@ -418,8 +424,8 @@ Start with a flow whose interaction sequence changes often, such as a wizard
 or checkout; stable Playwright tests can stay where they are.
 
 <CardGroup cols={2}>
-  <Card title="Writing tests" icon="pen-to-square" href="/writing-tests">
-    Goals, checks, extraction, and where a deterministic call still belongs.
+  <Card title="Goals" icon="pen-to-square" href="/goals">
+    Write test steps as goals instead of scripted selectors.
   </Card>
   <Card title="Web engine reference" icon="masks-theater" href="/reference/web">
     Every option and every `browser` method.

package/docs/migrate/selenium.mdx

@@ -101,8 +101,8 @@ Start with one page object and the flows that use it; its setup code can
 become a fixture.
 
 <CardGroup cols={2}>
-  <Card title="Writing tests" icon="pen-to-square" href="/writing-tests">
-    Goals, checks, extraction, and the deterministic APIs.
+  <Card title="Goals" icon="pen-to-square" href="/goals">
+    Write test steps as goals instead of scripted selectors.
   </Card>
   <Card title="screen reference" icon="crosshairs" href="/reference/screen">
     Every query, refinement, action, and read.

package/docs/mobile.mdx

@@ -3,8 +3,8 @@ title: Testing iOS and Android
 description: Set up a simulator or emulator target, write a device test, and know what differs from the web.
 ---
 
-`@e2e-dev/mobile` runs tests on iOS simulators and Android emulators. It is
-built on [agent-device](https://github.com/callstack/agent-device).
+`@e2e-dev/mobile` runs tests on iOS simulators, Android emulators, and
+phones connected to your machine. It is built on [agent-device](https://github.com/callstack/agent-device).
 Tests use the same `agent`, `screen`, and `expect` APIs as browser tests.
 A test launches the configured app with `app.open()`; between tests the app
 stays where the last one left it.
@@ -106,6 +106,46 @@ One test launches with its own through `device.openApp`:
 await device.openApp('com.example.app', { relaunch: true, permissions: { camera: 'deny' } });
 ```
 
+### Expo development builds
+
+A development build (`expo-dev-client`) opens on the dev launcher and loads
+its JavaScript from a dev server. On an iOS simulator, launch arguments open
+the server directly and turn off the dev menu, its onboarding sheet, and its
+floating action button, so nothing covers the app. `app.command` starts the
+server for the run:
+
+```ts title="e2e.config.ts"
+import type { E2EConfig } from 'e2e';
+import { mobile } from '@e2e-dev/mobile';
+
+export default {
+  targets: [
+    {
+      engine: mobile({ platform: 'ios' }),
+      app: {
+        bundleId: 'com.example.app',
+        launchArguments: [
+          '--initialUrl', 'http://localhost:8081',
+          '-EXDevMenuShowsAtLaunch', 'NO',
+          '-EXDevMenuIsOnboardingFinished', 'YES',
+          '-EXDevMenuShowFloatingActionButton', 'NO',
+        ],
+        command: { executable: 'npx', args: ['expo', 'start', '--port', '8081'] },
+        readyUrl: 'http://localhost:8081/status',
+      },
+    },
+  ],
+} satisfies E2EConfig;
+```
+
+Start each test with `app.open()`: the warm-up in `prepare` passes no launch
+arguments, so it rests on the dev launcher. The first launch waits for the dev
+server to bundle the app; a test's first check may need a longer timeout than
+the rest. A test that relaunches with its own `launchArguments` replaces the
+target's, so it lists these again. expo-dev-launcher on Android does not read
+`--initialUrl`: open the server there with `device.openLink` and the build's
+`exp+<slug>://expo-development-client/?url=<encoded server URL>` link.
+
 ## Several devices
 
 Add a target for each platform:
@@ -138,6 +178,12 @@ mobile({ platform: 'ios', device: ['iPhone 17', 'iPhone 17 Pro'] })
 Without `device`, the engine uses booted devices up to the worker limit.
 If none are booted, it boots one. Two workers never drive the same device.
 
+## Physical devices
+
+A phone connected to your machine works as a device too: name it in
+`device`. Setup and the controls that need a simulator are on
+[Physical devices](/physical-devices).
+
 ## Hosted devices
 
 A `device` can also be a `DeviceProvider`: an object that leases one hosted
@@ -520,6 +566,17 @@ daemon (`npx agent-device daemon stop`) and reboot the simulator
 
 Do what it says.
 
+**`device.installApp()` on Android reports no bundle id or package.** The
+build installed, but agent-device could not say which package it is, so
+`app.open()` would have nothing to launch. agent-device 0.21.18 cannot parse
+the manifest of an APK built with aapt2 (every current Android build), so it
+falls back to the Android SDK's `aapt`, which it looks for under
+`ANDROID_SDK_ROOT`, `ANDROID_HOME`, or `~/Android/Sdk`, not the macOS default
+`~/Library/Android/sdk`. Without `aapt` it names only a package the install
+added, and a build already on the emulator adds none. Set the target's
+`app.bundleId`, or export `ANDROID_HOME` and stop the agent-device daemon
+(`daemon stop` below) so the next run starts it with the variable.
+
 **A timeout on the device.** A simulator boot, runner connection, or app
 launch that times out on the device is `ENGINE_FAILURE` with agent-device's
 message and hint, never one of e2e's own timeout codes (`LAUNCH_TIMEOUT`,
@@ -549,7 +606,7 @@ xcrun simctl shutdown <udid> && xcrun simctl boot <udid>
   <Card title="Mobile engine reference" icon="mobile-screen" href="/reference/mobile">
     Every option, the `device` fixture, and the tool pack.
   </Card>
-  <Card title="Writing tests" icon="pen-to-square" href="/writing-tests">
-    Goals, checks, and the deterministic APIs, on any platform.
+  <Card title="Locators" icon="crosshairs" href="/locators">
+    Exact taps, swipes, and checks with `screen` and `expect`, on any platform.
   </Card>
 </CardGroup>