e2e 0.15.1 → 0.16.0

package/docs/integrations/kernel.mdx

@@ -0,0 +1,163 @@
+---
+title: Kernel browsers
+sidebarTitle: Kernel
+description: Run web targets in Kernel's hosted Chromium with the kernel() browser provider from @e2e-dev/kernel.
+---
+
+`kernel()` from `@e2e-dev/kernel` is a
+[browser provider](/browser#hosted-browsers) for [Kernel](https://kernel.sh).
+By default each worker slot gets its own hosted Chromium, created when the run
+starts and deleted when it ends; `scope: 'attempt'` leases one per test
+attempt instead. Tests and CI stay the same; the config changes only in the
+target's `browser`.
+
+## Setup
+
+<CodeGroup>
+```bash npm
+npm install --save-dev @e2e-dev/kernel @onkernel/sdk
+```
+
+```bash pnpm
+pnpm add -D @e2e-dev/kernel @onkernel/sdk
+```
+
+```bash bun
+bun add -d @e2e-dev/kernel @onkernel/sdk
+```
+</CodeGroup>
+
+```ts title="e2e.config.ts"
+import type { E2EConfig } from 'e2e';
+import { web } from '@e2e-dev/web';
+import { kernel } from '@e2e-dev/kernel';
+
+export default {
+  targets: [
+    {
+      name: 'kernel',
+      engine: web({ browser: kernel() }),
+      app: { url: 'https://staging.example.com' },
+    },
+  ],
+} satisfies E2EConfig;
+```
+
+Set `KERNEL_API_KEY` in the environment `e2e run` starts in, such as a CI
+secret. Each worker gets its own browser, so `workers` sets how many run at
+once.
+
+## Fill the screen
+
+Size the screen with Kernel's `viewport` and set the web engine's
+`viewport: null` so the page takes the window's size:
+
+```ts
+web({
+  browser: kernel({ viewport: { width: 1920, height: 1080 } }),
+  viewport: null,
+})
+```
+
+Each attempt's window then opens maximized, and the page
+[fills it](/viewports#fill-the-window): 1920 by 993 on a 1920 by 1080 screen,
+after the tab strip and address bar. With a fixed web `viewport`, the page is
+emulated at that size inside a smaller window, so Kernel's live view shows it
+cut off or in part of the window.
+
+## Options
+
+`kernel(options)` takes Kernel's create-browser body as is: `stealth`,
+`headless`, `timeout_seconds`, `profile`, `proxy_id`, `proxy`, `viewport`,
+`extensions`, `region`, `tags`, and the rest of `BrowserCreateParams` in the
+`@onkernel/sdk` you installed. On top of that:
+
+| Option   | Default    | Meaning |
+| -------- | ---------- | ------- |
+| `scope`  | `'worker'` | `'worker'`: one browser per worker slot for the run. `'attempt'`: a fresh browser per test attempt, retries included. See [Scopes](#scopes). |
+| `replay` | `true`     | How an attempt that records video is recorded. `true`, or Kernel's start-replay body (`framerate`, `max_duration_in_seconds`, `record_audio`): a Kernel replay of the browser's screen. `false`: the web engine's screencast of the page. See [Recordings](#recordings). |
+
+## Scopes
+
+`scope: 'worker'` keeps one browser per worker slot for the whole run and
+gives every attempt a new browser context on it, as a local run does: a test
+never sees another test's cookies, storage, or permissions. Kernel's initial
+tab stays open behind the attempts' windows. A context the engine creates
+does not share the browser's default context, so a Kernel `profile`'s saved
+cookies and storage are not there.
+
+`scope: 'attempt'` leases a fresh browser per attempt and runs the attempt in
+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
+[sessions](/authentication), which fail the run before any test.
+
+## Recordings
+
+An attempt that records [video](/reference/config#video) gets a Kernel
+replay of the browser's screen, saved as `video/replay.mp4` under the
+attempt's artifact directory. The replay shows the whole window, tabs and
+address bar included, where the web engine's screencast shows only the page.
+
+```ts title="e2e.config.ts"
+export default {
+  targets: [
+    {
+      name: 'kernel',
+      engine: web({ browser: kernel(), viewport: null }),
+      app: { url: 'https://staging.example.com' },
+      video: 'retain-on-failure',
+    },
+  ],
+} satisfies E2EConfig;
+```
+
+A test's own `video` overrides the target's, so one flow can keep its
+recording even when it passes:
+
+```ts
+test('checkout', { video: 'on' }, async ({ agent }) => {
+  await agent.act('Buy the first product in the catalog');
+});
+```
+
+A replay has the screen's size, which Kernel's `viewport` sets, at Kernel's
+default frame rate, 10 fps. Pass Kernel's start-replay body to change it:
+`kernel({ replay: { framerate: 20, max_duration_in_seconds: 600 } })`. A
+`framerate` above 20 needs `gpu: true` on the browser.
+
+Kernel replays headed browsers only, its default. With `headless: true`, or
+`replay: false`, the provider does not record, and the web engine records
+its screencast of the page instead, as it does for a local browser.
+
+## Downloads
+
+`browser.waitForDownload` works as it does locally. Each browser saves downloads
+under `/tmp/e2e-downloads` on its own disk, and the provider reads the
+finished file back through Kernel's browser filesystem API into the
+attempt's artifacts, in both scopes.
+
+## What the provider does
+
+- Tags every browser `e2e_run`, `e2e_target`, `e2e_slot`, and, per attempt,
+  `e2e_attempt`, merged over the `tags` you pass, so a session in Kernel's
+  dashboard names the run that started it.
+- Deletes, when the run ends, every browser still active with the run's
+  `e2e_run` and `e2e_target` tags: the browser of a worker that died
+  mid-attempt, in either scope, is released with the run rather than left
+  running.
+- Defaults `timeout_seconds` to 600, the backstop for a run that dies
+  itself before it can delete its browsers: Kernel deletes an idle browser
+  after that long. Pass your own to change it.
+- Logs `browser <id>, watch at <live view URL>` to the reporter as each
+  browser is created: at the start of the run in `worker` scope, and from
+  the worker for each attempt's browser in `attempt` scope and for a
+  replacement after a browser dropped.
+- Deletes a browser that arrives after its request was cancelled, and treats
+  one Kernel no longer knows as already deleted.
+
+A missing `KERNEL_API_KEY` or a Kernel error fails the lease with that
+message. In `worker` scope that ends the run before any test, and the
+browsers other slots got are still deleted; in `attempt` scope it fails the
+attempt.

package/docs/migrate/cypress.mdx

@@ -0,0 +1,124 @@
+---
+title: From Cypress
+description: Replace Cypress command chains with async tests and keep your data-cy attributes.
+---
+
+e2e tests run in Node. Use `await` for UI actions and call Node functions
+directly for work previously handled by `cy.task`. Both suites can stay in
+the project while you migrate one spec at a time.
+
+Start with the [quickstart](/quickstart) to install e2e and configure a model
+for the agent calls shown below.
+
+## Config
+
+| Cypress | e2e |
+| --- | --- |
+| `baseUrl` | `app: { url }` on the target |
+| `start-server-and-test` | `app: { url, command }`, see [Starting your app](/starting-your-app) |
+| `viewportWidth`, `viewportHeight` | `web({ viewport })` |
+| `data-cy` selectors | `web({ testIdAttribute: 'data-cy' })`, then `screen.getByTestId` |
+| `retries` | `retries` |
+| `env`, `Cypress.env()` | `process.env` |
+| `cypress.env.json` secrets | `credentials` and `secrets`, see [Signing in](/authentication) |
+| `cypress run --browser firefox` | A second target with `browser: 'firefox'` |
+| Component testing | No equivalent |
+
+```ts title="e2e.config.ts"
+import type { E2EConfig } from 'e2e';
+import { web } from '@e2e-dev/web';
+
+export default {
+  targets: [{
+    engine: web({ testIdAttribute: 'data-cy' }),
+    app: { url: 'http://localhost:3000' },
+  }],
+} satisfies E2EConfig;
+```
+
+## A test, before and after
+
+```js title="Cypress"
+describe('todos', () => {
+  it('completes one', () => {
+    cy.visit('/todos');
+    cy.get('[data-cy=new-todo]').type('Buy milk{enter}');
+    cy.get('[data-cy=new-todo]').type('Walk the dog{enter}');
+    cy.contains('li', 'Buy milk').find('[data-cy=toggle]').click();
+    cy.get('[data-cy=todo]').should('have.length', 2);
+    cy.contains('1 item left').should('be.visible');
+  });
+});
+```
+
+```ts title="e2e"
+import { describe, test } from '@e2e-dev/web';
+import { expect } from 'e2e';
+
+describe('todos', () => {
+  test('completes one', async ({ app, agent, screen }) => {
+    await app.open('/todos');
+    await agent.act('add todos "Buy milk" and "Walk the dog", then complete "Buy milk"');
+    await expect(screen.getByTestId('todo')).toHaveCount(2);
+    await expect(screen.getByText('1 item left')).toBeVisible();
+  });
+});
+```
+
+## API map
+
+| Cypress | e2e |
+| --- | --- |
+| `cy.visit(path)` | `app.open(path)` |
+| `cy.get('[data-cy=x]')` | `screen.getByTestId('x')` |
+| `cy.get('css')` | `browser.locator('css')`, not portable; prefer a role or label |
+| `cy.contains('text')` | `screen.getByText('text', { exact: false })` |
+| `cy.contains('li', 'text')` | `screen.getByRole('listitem').filter({ hasText: 'text' })` |
+| `.find()`, `.within()` | Chain a query off the locator: `row.getByRole(...)` |
+| `.first()`, `.eq(n)` | `.first()`, `.nth(n)` |
+| `.click()`, `.dblclick()`, `.rightclick()` | `.tap()`, `.doubleTap()`, `.secondaryTap()` |
+| `.type('text')` | `.fill('text')` replaces the content |
+| `.type('{enter}')` | `.press('Enter')` |
+| `.clear()`, `.check()`, `.select()` | `.clear()`, `.check()`, `.selectOption()` |
+| `.selectFile()` | `.setInputFiles()` |
+| `.should('be.visible')` | `await expect(locator).toBeVisible()` |
+| `.should('have.text', t)`, `.should('contain', t)` | `.toHaveText(t)`, `.toContainText(t)` |
+| `.should('have.length', n)` | `.toHaveCount(n)` |
+| `.should('have.value', v)` | `.toHaveValue(v)` |
+| `.should('not.exist')` | `.toHaveCount(0)`; `toBeHidden()` also accepts a node that is still in the DOM |
+| `cy.url().should('include', p)` | `expect(browser).toHaveURL(/p/)` |
+| `cy.title()` | `expect(browser).toHaveTitle()` |
+| `cy.intercept(url, body)` | `browser.route(url, route => route.fulfill({ json: body }))` |
+| `cy.wait('@alias')` | `browser.waitForResponse(url)` |
+| `cy.on('window:confirm')` | `browser.onDialog('accept')` |
+| `cy.window()`, `cy.document()` | `browser.evaluate(() => ...)` |
+| `cy.setCookie` | `browser.setCookies` |
+| `cy.viewport` | `browser.setViewport` |
+| `cy.session` | `test.setup` and `{ session }` |
+| `cy.task`, `cy.exec`, `cy.request` | Node code: `fetch`, `fs`, your database client |
+| `cy.fixture` | `import data from './fixture.json'` |
+| `Cypress.Commands.add` | A function, or a fixture from `test.extend` |
+| `cy.wait(ms)` | Use a locator assertion for the condition you need |
+| `cypress open` | `npx e2e run --headed`, plus `--debug` for the step table |
+
+Where the behavior differs from Cypress's:
+
+- There is no chain. Each command is awaited on its own line and returns a
+  value, so `const text = await locator.textContent()` works.
+- Actions and single-node reads or assertions need one match; several fail
+  with `LOCATOR_AMBIGUOUS`. Narrow with `.filter()`, `.first()`, or `.nth()`,
+  see [screen](/reference/screen).
+
+## What to migrate first
+
+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>
+  <Card title="Working with the browser" icon="globe" href="/browser">
+    Routes, dialogs, downloads, iframes, and page evaluation.
+  </Card>
+</CardGroup>

package/docs/migrate/detox.mdx

@@ -0,0 +1,140 @@
+---
+title: From Detox
+description: Use your existing app build and testIDs with screen, expect, and agent goals.
+---
+
+`@e2e-dev/mobile` drives a simulator or emulator using your normal debug
+or release build. It does not need the Detox framework. React Native
+`testID` props work with `getByTestId` on both platforms.
+
+Set up a target with the [mobile guide](/mobile) and a model with the
+[quickstart](/quickstart). You can use the same simulator for each runner
+while migrating one spec at a time.
+
+## Config
+
+| Detox (`.detoxrc.js`) | e2e |
+| --- | --- |
+| `apps.<name>.binaryPath` | `app: { appPath }` on the target plus one `device.installApp()` per device in a fixture; the engine installs nothing on its own |
+| `apps.<name>.bundleId` | `app: { bundleId: 'com.example.app' }` on the target, the app `app.open()` launches |
+| `devices.<name>.device.type` | `mobile({ device: 'iPhone 17' })` |
+| `configurations` | `targets`, one engine per platform |
+| Jest config, `maxWorkers` | `workers`, one per device |
+| `detox build` | Your normal build. No Detox framework, no `detox build` step |
+| `device.launchApp({ permissions })` | `app.permissions` on the target, set before every fresh launch, or `device.openApp(app, { relaunch: true, permissions })` for one; `grant`, `deny`, `reset` for `YES`, `NO`, `unset` |
+| `device.launchApp({ launchArgs })` | `app.launchArguments` on the target, or `device.openApp(app, { relaunch: true, launchArguments })` for one; a list of strings the platform launch command takes, not a map |
+
+```ts title="e2e.config.ts"
+import type { E2EConfig } from 'e2e';
+import { mobile } from '@e2e-dev/mobile';
+
+export default {
+  targets: [
+    {
+      name: 'ios',
+      engine: mobile({ platform: 'ios' }),
+      app: { bundleId: 'com.example.app', appPath: 'ios/build/MyApp.app' },
+    },
+    {
+      name: 'android',
+      engine: mobile({ platform: 'android' }),
+      app: { bundleId: 'com.example.app', appPath: 'android/app/build/outputs/apk/debug/app-debug.apk' },
+    },
+  ],
+  workers: 1,
+} satisfies E2EConfig;
+```
+
+## A test, before and after
+
+```js title="Detox"
+describe('login', () => {
+  beforeAll(async () => { await device.launchApp({ newInstance: true }); });
+
+  it('shows the home screen', async () => {
+    await element(by.id('email')).typeText('ada@example.test');
+    await element(by.id('password')).typeText('hunter2');
+    await element(by.text('Sign in')).tap();
+    await waitFor(element(by.id('home'))).toBeVisible().withTimeout(10000);
+    await expect(element(by.text('Welcome, Ada'))).toBeVisible();
+  });
+});
+```
+
+```ts title="e2e"
+import { test } from '@e2e-dev/mobile';
+import { expect, credentials } from 'e2e';
+
+test('shows the home screen', async ({ agent, app, screen }) => {
+  await app.open();
+  const ada = credentials.user('ada');
+  await agent.act('sign in as {username}', { params: { username: ada.username, password: ada.password } });
+  await expect(screen.getByTestId('home')).toBeVisible({ timeout: 10_000 });
+  await expect(screen.getByText('Welcome, Ada')).toBeVisible();
+});
+```
+
+`app.open()` launches the configured app fresh; nothing launches on its own.
+The password comes from [configured credentials](/authentication).
+
+## API map
+
+| Detox | e2e |
+| --- | --- |
+| `by.id('x')` | `screen.getByTestId('x')` |
+| `by.text('t')` | `screen.getByText('t')` |
+| `by.label('l')` | `screen.getByLabel('l')` |
+| `by.type('RCTImageView')` | `device.locator('role=Image')`, agent-device's selector syntax |
+| `by.id('x').withAncestor(by.id('row'))` | `screen.getByTestId('row').getByTestId('x')` |
+| `.atIndex(n)` | `.nth(n)` |
+| `.tap()`, `.multiTap(2)`, `.longPress()` | `.tap()`, `.doubleTap()`, `.longPress()` |
+| `.tap({ x, y })` | `.tap({ position: { x, y } })` |
+| `.typeText(t)`, `.replaceText(t)` | `.fill(t)` replaces the content |
+| `.clearText()` | `.clear()` |
+| `.tapReturnKey()` | `.press('Enter')` |
+| `.swipe('up', 'fast')` | `.swipe({ direction: 'down', momentum: 'fast' })`: Detox names the finger's direction, e2e the content's |
+| `.scroll(200, 'down')` | `screen.swipe({ direction: 'down' })` |
+| `waitFor(el).toBeVisible().whileElement(list).scroll(...)` | `screen.scrollUntilVisible(el)` |
+| `waitFor(el).toBeVisible().withTimeout(ms)` | `await expect(el).toBeVisible({ timeout: ms })` |
+| `expect(el).toBeVisible()`, `.toExist()` | `.toBeVisible()` for visibility; `.toHaveCount(1)` for existence |
+| `expect(el).not.toBeVisible()` | `.toBeHidden()` |
+| `expect(el).toHaveText(t)` | `.toHaveText(t)` |
+| `expect(el).toHaveToggleValue(true)` | `.toBeChecked()` |
+| `expect(el).toHaveValue(v)` | `.toHaveValue(v)` |
+| `device.launchApp({ newInstance: true })` | `app.restart()` |
+| `device.launchApp({ delete: true })` | `app.clearState()` |
+| `device.reloadReactNative()` | No equivalent. `app.restart()` is the nearest |
+| `device.sendToHome()`, `device.pressBack()` | `device.home()`, `device.back()` |
+| `device.setLocation(lat, lon)` | `device.setLocation({ latitude, longitude })` |
+| `device.setOrientation('landscape')` | `device.setOrientation('landscape-left')` |
+| `device.setBiometricEnrollment(true)` | `device.enrollBiometrics('faceid', true)` |
+| `device.matchFace()`, `device.unmatchFace()` | `device.setBiometrics('faceid', 'match' \| 'nonmatch')` |
+| `device.setStatusBar`, `device.setURLBlacklist` | No equivalent |
+| `device.disableSynchronization()` | No equivalent. e2e waits through actions and retrying assertions. |
+| `device.takeScreenshot()` | `app.screenshot('label')`, subject to the secret policy |
+| `:ios:` / `:android:` in a test name | `{ platforms: ['ios'] }` on the test |
+
+Where the behavior differs from Detox's:
+
+- Actions and single-node reads or assertions need one match; several fail
+  with `LOCATOR_AMBIGUOUS`. Narrow with `.filter()`, `.first()`, or `.nth()`,
+  see [screen](/reference/screen).
+- No `test.setup` or `{ session }` on a device, see
+  [what differs from the web](/mobile#what-differs-from-the-web).
+
+`by.text` is an exact match in Detox and `getByText` is exact here too.
+
+## What to migrate first
+
+Start with a flow that needs frequent maintenance. If its screens take time
+to settle, configure the engine's
+[`settle` and `transition` options](/reference/mobile#engine).
+
+<CardGroup cols={2}>
+  <Card title="Testing iOS and Android" icon="mobile-screen" href="/mobile">
+    Configure your app and devices.
+  </Card>
+  <Card title="Mobile engine reference" icon="book" href="/reference/mobile">
+    Every option, the `device` fixture, and the tool pack.
+  </Card>
+</CardGroup>

package/docs/migrate/maestro.mdx

@@ -0,0 +1,229 @@
+---
+title: From Maestro
+description: Move Maestro flows to TypeScript with locators, assertions, and agent goals.
+---
+
+Translate Maestro commands into awaited TypeScript calls. Keep exact
+interactions as locator calls, or give the agent a goal that covers several
+of them. Both runners can use the same simulator or emulator.
+
+Set up a target with the [mobile guide](/mobile) and a model with the
+[quickstart](/quickstart), then move one flow at a time. This page maps each
+Maestro command to its e2e counterpart and says whether it exists. The
+reference pages hold the details: [screen](/reference/screen),
+[expect](/reference/expect), [test](/reference/test), and the
+[mobile engine](/reference/mobile).
+
+## Config
+
+| Maestro | e2e | Status |
+| --- | --- | --- |
+| `appId` at the top of every flow | `app: { bundleId: 'com.example.app' }` on the target, the app `app.open()` launches | renamed |
+| a different `appId` per flow | `device.openApp(id)` inside the test, or separate app-specific configs and runs; every test runs on every selected target | renamed |
+| `--platform ios` | `mobile({ platform: 'ios' })`, one engine per platform | renamed |
+| `--device` | `mobile({ device: 'iPhone 17' })`; a list is a pool, one worker per device | renamed |
+| `.maestro/config.yaml` `flows` | `tests`, default `tests/**/*.e2e.ts`; Maestro runs one folder level, e2e recurses | renamed |
+| `flows: ['!helper.yaml']` | a `tests` entry with a leading `!`: `tests: ['tests/**/*.e2e.ts', '!tests/helpers/**']` | renamed |
+| `tags` and `--include-tags` | `{ tags: [...] }` on a test or group, `--tag` on the CLI | renamed |
+| `--exclude-tags` | `--exclude-tag` | renamed |
+| `env` and `${VAR}` | module constants, and `params` in a goal, see [Selectors](#selectors) | renamed |
+| `MAESTRO_*` variables | `process.env` in the config; a password or token goes under `credentials` or `secrets` | renamed |
+| `--format junit`, `--output` | `--reporter list,junit`, written to `.e2e/junit.xml` | renamed |
+| `--format html` | no equivalent; `markdown` writes `.e2e/summary.md`, every run writes `.e2e/report.json` | missing |
+| `properties` (JUnit `<property>`) | not yet | missing |
+| `--shards`, `--shard-split` | `device: [...]` plus `workers` splits a target's files across devices on one machine; `--shard <index/total>` splits the suite across machines, see [Sharding](/ci#sharding) | renamed |
+| `maestro record`, `startRecording` | `npx e2e run --video`, one MP4 of the device per attempt, or `video` in the config | renamed |
+| `maestro test -c`, Maestro Studio | not yet; `npx e2e mcp` gives a coding agent a live session on the device, see [Coding agents](/coding-agents) | missing |
+| `maestro hierarchy` | not yet; `device.locator` takes agent-device selectors for nodes `screen` cannot name | missing |
+| Maestro Cloud | your CI, see [Continuous integration](/ci) | by design |
+
+## A flow, before and after
+
+```yaml title="Maestro"
+appId: com.example.app
+---
+- launchApp:
+    clearState: true
+- tapOn: "Get started"
+- tapOn:
+    id: "email"
+- inputText: "ada@example.test"
+- tapOn: "Continue"
+- assertVisible: "Check your inbox"
+- scrollUntilVisible:
+    element: "Resend"
+- assertVisible:
+    id: "resend"
+```
+
+```ts title="e2e"
+import { test } from '@e2e-dev/mobile';
+import { expect } from 'e2e';
+
+test('asks for the email', async ({ app, agent, screen }) => {
+  await app.clearState();
+  await agent.act('get started with the email {email}', { params: { email: 'ada@example.test' } });
+  await expect(screen.getByText('Check your inbox')).toBeVisible();
+  await screen.scrollUntilVisible(screen.getByTestId('resend'));
+  await expect(screen.getByTestId('resend')).toBeVisible();
+});
+```
+
+The agent handles onboarding. Locator assertions check the confirmation and
+the Resend control. The flow could also stay fully deterministic: every
+`tapOn` has a `screen.getBy*(...).tap()` line.
+
+## Command map
+
+Calls on `screen`, `app`, `agent`, and `expect(locator)` run on every
+target, a browser included. Calls on `device` run only on a device: a test that uses one
+declares `requires: ['device']` so other targets skip it. `Status` is `same`,
+`renamed`, `device only`, `by design` (see [Selectors](#selectors) and
+[By design](#by-design)), or `missing`, with what to do today.
+
+### App lifecycle
+
+| Maestro | e2e | Status |
+| --- | --- | --- |
+| `launchApp` | `app.open()`, the fresh launch of the target's `app.bundleId`; nothing launches on its own | renamed |
+| `launchApp: { clearState: true }`, `clearState` | `app.clearState()` | renamed |
+| `launchApp: { stopApp: false }` | `device.openApp(id)` without `relaunch` | device only |
+| `launchApp: { arguments }` | `app.launchArguments` on the target, or `device.openApp(app, { relaunch: true, launchArguments })` for one launch; a list of strings, not a map | renamed |
+| `launchApp: { permissions }` | `app.permissions` on the target, set before every fresh launch, or `device.openApp(app, { relaunch: true, permissions })` for one; `grant`, `deny`, `reset` for `allow`, `deny`, `unset`; no `all`, nothing is granted unless named | renamed |
+| `stopApp`, `killApp` | `device.closeApp()` | device only |
+| `stopApp`, then `launchApp` | `app.restart()` | renamed |
+| `clearKeychain` | `device.clearKeychain()`, the whole simulator's keychain; iOS only | renamed |
+| `openLink` | `device.openLink(url, { app })`; on iOS the link opens into `app`, default the pinned app | renamed |
+| `addMedia` | not yet | missing |
+| `back` | `app.back()`, or `device.back()` | renamed |
+
+### Taps and input
+
+| Maestro | e2e | Status |
+| --- | --- | --- |
+| `tapOn: "Text"` | `screen.getByText('Text').tap()`; exact, see [Selectors](#selectors) | renamed |
+| `tapOn: { id: x }` | `screen.getByTestId('x').tap()` | renamed |
+| `tapOn: { text, index: 2 }` | `.nth(2)` | renamed |
+| `tapOn: { below: "Email" }`, `above`, `leftOf`, `rightOf`, `containsDescendants` | no equivalent, see [Selectors](#selectors) | by design |
+| `tapOn: { point: "x,y" }` | `screen.tapAt({ x, y })`; inside a node, `.tap({ position: { x, y } })` | renamed |
+| `retryTapIfNoChange`, `waitToSettleTimeoutMs` | `mobile({ settle, transition })`, engine-wide; no per-call knob | renamed |
+| `doubleTapOn`, `longPressOn` | `.doubleTap()`, `.longPress({ duration })` | renamed |
+| `inputText` | `screen.getByTestId('field').fill('text')` | renamed |
+| `inputRandomEmail`, `inputRandomText`, `faker` | `unique()` around a value in `act` params so the cache still replays; any npm faker for the rest | renamed |
+| `eraseText` | `.clear()` | renamed |
+| `hideKeyboard` | `device.dismissKeyboard()`, the same dismiss key or center drag Maestro uses; fails only when the keyboard outlives both drags | renamed |
+| `pressKey: Enter` | `.press('Enter')` on the field | renamed |
+| `pressKey: Home`, `back` | `device.home()`, `device.back()` | device only |
+| `pressKey: lock`, `power`, `volume up`, TV remote keys | not yet | missing |
+| `copyTextFrom`, `pasteText` | `await locator.textContent()`, then `.fill(text)` | renamed |
+| `setClipboard` | `device.setClipboard(text)`; `device.clipboard()` reads it | device only |
+| `label: "..."` on a command | not yet; every `screen`, `device`, and `agent` call is a report step named by the call | missing |
+
+### Gestures
+
+| Maestro | e2e | Status |
+| --- | --- | --- |
+| `swipe: { direction: UP }` | `screen.swipe({ direction: 'down' })`, or `locator.swipe(...)` inside one node; Maestro names the finger's direction, e2e the content's | renamed |
+| `swipe: { start, end }` | `screen.swipe({ from: { x, y }, to: { x, y } })` | renamed |
+| `scroll` | `screen.swipe({ direction: 'down' })` | renamed |
+| `scrollUntilVisible: { element }` | `screen.scrollUntilVisible(locator, { direction })` | renamed |
+| `waitForAnimationToEnd` | an assertion on the settled state; `mobile({ settle, transition })` for the engine | renamed |
+
+### Assertions and waits
+
+| Maestro | e2e | Status |
+| --- | --- | --- |
+| `assertVisible`, `assertNotVisible` | `await expect(locator).toBeVisible()`, `.toBeHidden()` | renamed |
+| `assertVisible: { text, enabled: true }` | `.toBeVisible()` and `.toBeEnabled()` | renamed |
+| `assertVisible: { checked, selected, focused }` | `.toBeChecked()`, `.toBeSelected()`, `.toBeFocused()` | renamed |
+| `assertTrue: ${...}` | `expect(value).toBe(true)`, or `expect.poll` for a value that is still changing | renamed |
+| `extendedWaitUntil: { visible, timeout }` | `.toBeVisible({ timeout })` | renamed |
+| `assertScreenshot: { path, thresholdPercentage }` | not yet; `agent.assert('...', { vision: true })` is a judgment, not a pixel diff | missing |
+| `assertDarkMode`, `assertLightMode` | not yet; assert on a themed control | missing |
+| `retry: { maxRetries, commands }` | `expect.poll` for a value, `{ retries }` on the test for the flow | renamed |
+| `takeScreenshot` | `app.screenshot('label')`, redacted, withheld after a secret fill | renamed |
+
+### Device
+
+| Maestro | e2e | Status |
+| --- | --- | --- |
+| `setLocation` | `device.setLocation({ latitude, longitude })` | device only |
+| `travel: { points }` | `device.setLocation` in a loop | device only |
+| `setAirplaneMode`, `toggleAirplaneMode` | `device.setAirplaneMode(true)` or `false`, the state you want | device only |
+| `setDarkMode`, `toggleDarkMode` | `device.setAppearance('dark')` or `'light'` | device only |
+| `setOrientation` | `device.setOrientation('landscape-left')` | device only |
+| `setPermissions` | `device.setPermission(name, 'grant' \| 'deny' \| 'reset')`, one permission per call, on the open app | device only |
+| a second `appId` mid-flow | `device.openApp(id)`; the `open_app` tool lets the agent switch inside a goal, see [Agent tools](/mobile#agent-tools) | device only |
+| platform-specific selectors | `device.locator('role=StaticText label="..."')`, agent-device's selector terms | device only |
+
+### AI commands and flow control
+
+| Maestro | e2e | Status |
+| --- | --- | --- |
+| `assertWithAI`, `assertNoDefectsWithAI` | `agent.assert('...')`, `agent.assert('...', { vision: true })` | renamed |
+| `extractTextWithAI` | `agent.extract('...', { schema })` | renamed |
+| `runFlow: file.yaml` | a function, or a fixture from `test.extend` | renamed |
+| `runFlow: { when: { visible } }` | `if (await locator.isVisible()) { ... }`, see [Selectors](#selectors) | renamed |
+| `optional: true` on a command | the same `isVisible()` check | renamed |
+| `repeat: { times: n }`, `repeat: { while }` | a `for` or `while` loop | renamed |
+| `runScript`, `evalScript`, `${output.x}` | TypeScript in the test | renamed |
+| `http.get`, `http.post`, `json()` | Node `fetch`, see [Testing APIs](/api-testing) | renamed |
+| `onFlowStart`, `onFlowComplete` | `beforeEach`, `afterEach` | renamed |
+| `startRecording`, `stopRecording` | `test('x', { video: 'on' }, ...)` records that test's whole attempts, on a device the mobile engine records; no start and stop inside a test | renamed |
+
+## Selectors
+
+Maestro's selector shorthand does not port one to one. Five differences
+account for most edits.
+
+- Text and id are regular expressions in Maestro, so `tapOn: ".*Save.*"`
+  matches any text with Save in it. `getByText` is exact. Write
+  `getByText(/Save/)` for the pattern, or `{ exact: false }` for a
+  case-insensitive substring. `getByTestId` matches a string as the whole id;
+  write `getByTestId(/^row-/)` for a pattern.
+- `index: 2` is `.nth(2)`. When several nodes match and no index is given,
+  Maestro taps the first one silently; e2e fails with `LOCATOR_AMBIGUOUS`.
+  Write `.first()` when the first match is what you mean.
+- `optional: true` and `runFlow: { when: { visible } }` become
+  `if (await locator.isVisible())`. `isVisible()` is a read: `false` on zero
+  matches, `LOCATOR_AMBIGUOUS` on several. Add `{ visible: true }` to the
+  query or `.first()` to the locator when a hidden twin may exist.
+- `below`, `above`, `leftOf`, `rightOf`, and `containsDescendants` have no
+  port. e2e has `filter({ has, hasText })` and chaining for structure and
+  nothing spatial; a selector anchored on layout breaks on the next redesign.
+  Anchor an unlabeled input with `getByLabel`, give it a test id, or hand the
+  step to a goal: `agent.act('enter {email} in the email field', { params })`
+  reads the screen and finds the field.
+- `env:` and `${VAR}` become module constants, and `params` inside a goal:
+  `agent.act('sign in as {email}', { params: { email } })`. `MAESTRO_*`
+  variables become `process.env` in the config. A password or token goes
+  under `credentials` or `secrets`, so the model never sees the value.
+
+## By design
+
+These differ from Maestro on purpose and will stay that way.
+
+- One match or `LOCATOR_AMBIGUOUS`, see [Selectors](#selectors).
+- A password is a `Secret` the model never sees, see
+  [Signing in](/authentication).
+- Every `device` call is a step. It lands in the report as `device.<method>`,
+  so a failure shows the exact call without a `label`.
+- No agent-device client in tests. `device.locator` covers platform-specific
+  selectors; everything else goes through `screen`, `app`, `device`, and the
+  agent, so it is recorded and redacted.
+- No `test.setup` or `session:` on a device, see
+  [what differs from the web](/mobile#what-differs-from-the-web).
+
+## What to migrate first
+
+Start with a flow whose `optional` steps and `runFlow: { when }` branches
+often need updating.
+
+<CardGroup cols={2}>
+  <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>
+</CardGroup>