e2e 0.21.1 → 0.21.2

package/docs/integrations/testmu.mdx

@@ -0,0 +1,152 @@
+---
+title: TestMu AI
+sidebarTitle: TestMu AI
+description: Run mobile targets on TestMu AI (formerly LambdaTest) Android emulators, iOS simulators, and real devices with the testmu() device provider from @e2e-dev/testmu.
+icon: "/images/icons/testmu.svg"
+"og:image": "https://e2e.tester.army/docs/images/og/integrations/testmu.png?v=6ef69e0285"
+"twitter:image": "https://e2e.tester.army/docs/images/og/integrations/testmu.png?v=6ef69e0285"
+---
+
+`testmu()` from `@e2e-dev/testmu` is a
+[device provider](/mobile#hosted-devices) for
+[TestMu AI](https://www.lambdatest.com) (formerly LambdaTest) Android
+emulators, iOS simulators, and real devices. Each worker slot leases one
+device when the run starts and releases it when the run ends.
+
+<Tip>
+No Mac, Xcode, or Android SDK on the machine that runs e2e.
+</Tip>
+
+## Setup
+
+Install the integration alongside the mobile engine:
+
+<CodeGroup>
+```bash npm
+npm install --save-dev e2e @e2e-dev/mobile @e2e-dev/testmu
+```
+
+```bash pnpm
+pnpm add -D e2e @e2e-dev/mobile @e2e-dev/testmu
+```
+
+```bash bun
+bun add -d e2e @e2e-dev/mobile @e2e-dev/testmu
+```
+</CodeGroup>
+
+```ts title="e2e.config.ts"
+import type { E2EConfig } from 'e2e';
+import { mobile } from '@e2e-dev/mobile';
+import { testmu } from '@e2e-dev/testmu';
+
+const apk = 'https://prod-mobile-artefacts.lambdatest.com/assets/docs/proverbial_android.apk';
+const ipa = 'https://prod-mobile-artefacts.lambdatest.com/assets/docs/proverbial_ios.ipa';
+
+export default {
+  targets: [
+    {
+      name: 'android-emulator',
+      engine: mobile({
+        platform: 'android',
+        device: testmu({ device: 'Galaxy S22 Ultra 5G', osVersion: '14', app: apk }),
+      }),
+      app: { bundleId: 'com.lambdatest.proverbial' },
+    },
+    {
+      name: 'ios-real',
+      engine: mobile({
+        platform: 'ios',
+        device: testmu({ device: 'iPhone 16', osVersion: '18', app: ipa, deviceType: 'real' }),
+      }),
+      app: { bundleId: 'proverbial' },
+    },
+    {
+      name: 'android-real',
+      engine: mobile({
+        platform: 'android',
+        device: testmu({ device: 'Pixel 6', osVersion: '14', app: apk, deviceType: 'real' }),
+      }),
+      app: { bundleId: 'com.lambdatest.proverbial' },
+    },
+  ],
+  workers: 1,
+} satisfies E2EConfig;
+```
+
+`device` and `osVersion` must match TestMu AI's catalog exactly, as the
+[capabilities generator](https://www.lambdatest.com/capabilities-generator)
+lists them: `18.0` for a virtual iOS device, `18` for a real one, `14` for
+Android. Real and virtual devices have separate catalogs.
+
+`app` is the build TestMu AI installs on every session: an `lt://` app id,
+an `https` URL, or a local path, resolved against the directory of
+`e2e.config.ts` and uploaded. Use an `.apk` or `.aab` on Android, a zipped
+`.app` on an iOS simulator, and a signed `.ipa` on a real iOS device. Leave
+the target's `app.appPath` out, and keep `app.bundleId` for `app.open()`.
+
+Tests are the same as on a local device:
+
+```ts title="tests/home.e2e.ts"
+import { test } from '@e2e-dev/mobile';
+import { expect } from 'e2e';
+
+test('Proverbial home screen', async ({ app, screen }) => {
+  await app.open();
+  await expect(screen.getByText('Proverbial')).toBeVisible();
+  // Android labels the button GEOLOCATION, iOS GeoLocation.
+  await expect(screen.getByRole('button', /^geolocation$/i)).toBeVisible();
+});
+```
+
+## Authenticate
+
+Set `LT_USERNAME` and `LT_ACCESS_KEY` in the environment `e2e run` starts
+in, such as CI secrets. Copy them from **Account Settings → Password &
+Security → Username and Access Key**
+([accounts.lambdatest.com/security/username-accesskey](https://accounts.lambdatest.com/security/username-accesskey)).
+Without either, the lease fails before anything starts.
+
+## Options
+
+| Option        | Default         | Meaning |
+| ------------- | --------------- | ------- |
+| `device`      | required        | Device name as TestMu AI's catalog lists it (`'Galaxy S22 Ultra 5G'`, `'iPhone 16'`). |
+| `osVersion`   | required        | OS version as the catalog lists it for that device. |
+| `app`         | required        | The build TestMu AI installs: an `lt://` app id, an `https` URL, or a local path. |
+| `deviceType`  | `'virtual'`     | `'virtual'` for an emulator or simulator, `'real'` for a real device. |
+| `project`     | `'e2e'`         | Dashboard project the sessions are grouped under. |
+| `build`       | the run id      | Dashboard build the sessions are grouped under. |
+| `sessionName` | `e2e-<run id>-<target>-<slot>` | Session name on the dashboard. With more than one worker slot, `-<slot>` is appended. |
+| `orientation` | the device's    | `'portrait'` or `'landscape'`. |
+| `geoLocation` | TestMu AI's     | Country code the device's IP geolocates to (`'US'`). |
+| `timezone`    | the device's    | Time zone (`'UTC+05:30'`). |
+| `language`    | the device's    | Language code (`'fr'`). |
+| `locale`      | the device's    | Locale (`'fr_FR'`). |
+| `appiumVersion` | TestMu AI's   | Appium version for the session (`'2.16.2'`). |
+
+Device features are set when the session starts and hold for the whole
+session. An unknown option or an invalid value fails the config load with
+`INVALID_CONFIG`.
+
+An attempt that records [video](/reference/config#video) links TestMu AI's
+recording of the session, found by its `build` and `sessionName`. The
+recording covers the whole session, so every attempt on a worker slot links
+the same video. Runs that overlap and share a fixed `build` and
+`sessionName` can link each other's videos; the defaults never do.
+
+## Limits
+
+- Each session starts when its slot is leased, which takes about 30 to 75
+  seconds, and is billed until the run releases it, even when no test runs
+  on it. Keep `workers` times the number of TestMu AI targets within your
+  plan's parallel sessions.
+- If the runner is killed before it releases a device, nothing sends the
+  session another command, so TestMu AI's
+  [idle timeout](https://www.lambdatest.com/support/docs/desired-capabilities-in-appium/)
+  (120 seconds by default) ends it, which takes about three minutes after its
+  last command.
+- Device settings (permissions, location, network, appearance), system
+  alerts, recording and device logs through agent-device, and port reverse
+  are not available. Read logs on the TestMu AI dashboard, and use TestMu AI
+  Tunnel to reach a server on your network.

package/docs/mcp.mdx

@@ -0,0 +1,123 @@
+---
+title: MCP server
+description: Let your coding agent use your app and check its own work.
+icon: "plug"
+"og:image": "https://e2e.tester.army/docs/images/og/mcp.png?v=17998906c0"
+"twitter:image": "https://e2e.tester.army/docs/images/og/mcp.png?v=17998906c0"
+---
+
+`e2e mcp` gives a coding agent such as Claude Code, Codex, or Cursor a live
+session on your app, on web, iOS, or Android. The agent sees the screen,
+acts on it, and checks its work.
+
+## Why it matters
+
+| Task | Without `e2e mcp` | With `e2e mcp` |
+| --- | --- | --- |
+| Write a test | Guesses locators, runs, fails, guesses again | Checks each locator before it writes it |
+| Change the UI | Done when it compiles | Opens the page and checks the result |
+| Reproduce a bug | Guesses from the code | Follows the steps in the app |
+| Show a change in a PR | Describes it | Records a video |
+
+The server needs no model.
+
+## Set it up
+
+`e2e init` offers to register the server in `.mcp.json` (Claude Code) and
+`.cursor/mcp.json` (Cursor). By hand:
+
+<Tabs>
+  <Tab title="Claude Code">
+    <CodeGroup>
+    ```bash npm
+    claude mcp add --scope project e2e -- npx e2e mcp
+    ```
+
+    ```bash pnpm
+    claude mcp add --scope project e2e -- pnpm exec e2e mcp
+    ```
+
+    ```bash bun
+    claude mcp add --scope project e2e -- bunx e2e mcp
+    ```
+    </CodeGroup>
+  </Tab>
+  <Tab title="Codex">
+    Add the server to `.codex/config.toml`, trust the project, and start a
+    new session:
+
+    ```toml title=".codex/config.toml"
+    [mcp_servers.e2e]
+    command = "npx"
+    args = ["e2e", "mcp"]
+    ```
+  </Tab>
+  <Tab title="Cursor">
+    Add the server to `.cursor/mcp.json`. Other clients that read an
+    `mcpServers` map take the same block.
+
+    ```json title=".cursor/mcp.json"
+    {
+      "mcpServers": {
+        "e2e": { "command": "npx", "args": ["e2e", "mcp"] }
+      }
+    }
+    ```
+  </Tab>
+</Tabs>
+
+A session starts the target's app command, if it has one.
+
+## Ask the agent
+
+- "Add a Remember me checkbox to the login form. Check it in the app with e2e."
+- "Write a test for checkout. Check every locator in the app first."
+- "Reproduce issue #123 in the app and record a video."
+
+Add "headed" to watch a local browser or simulator.
+
+## How it checks a locator
+
+A locator guessed from the source fails in the session, not in a test run:
+
+```text wrap
+0 nodes match getByLabel("Email").
+A test using this locator would fail with LOCATOR_NOT_FOUND. ...
+
+1 node matches getByRole("button", name: "Sign in").
+Use: screen.getByRole("button", "Sign in")
+```
+
+## Run tests next to a session
+
+A session doesn't run tests and writes no test results or cache
+recordings. The agent runs tests with `e2e run`. On web, set
+[`reuseExisting: true`](/web#starting-your-app) to share the app a session
+started, or close the session first. On mobile, run on a device no session
+uses.
+
+## Run several agents
+
+Each agent, subagents included, opens its own session with its own browser
+or device, up to four by default. On mobile, give each session its own
+target.
+
+## Secrets
+
+`type_secret` fills a secret without showing it to the agent. After a
+secret is filled, the session stops returning screenshots.
+
+<Warning>
+Videos from `start_recording` are not masked.
+</Warning>
+
+## Next
+
+<CardGroup cols={2}>
+  <Card title="MCP server reference" icon="book" href="/reference/mcp">
+    Every tool, flag, session rule, and error code.
+  </Card>
+  <Card title="Coding agents" icon="robot" href="/coding-agents">
+    The skill, running tests, and reading a failure.
+  </Card>
+</CardGroup>

package/docs/migrate/detox.mdx

@@ -11,7 +11,7 @@ import { SetupPrompt } from '../snippets/setup-prompt-card.jsx';
 export const migrationPrompt = `Migrate this project's Detox tests to e2e, one spec at a time. Docs: \`https://e2e.tester.army/docs/migrate/detox.md\` and \`https://e2e.tester.army/docs/mobile.md\`
 
 1. Read the migration guide above. It maps \`.detoxrc.js\` and the Detox API to e2e. The mobile guide covers devices and app builds.
-2. If the project has no e2e config (\`e2e.config.ts\` or \`e2e.config.mts\`), run \`npx e2e init --yes\` (or the pnpm or bun equivalent). It writes a web config and an example test, and installs nothing yet. Replace @e2e-dev/web with @e2e-dev/mobile, and rewrite \`tests/example.e2e.ts\` for the mobile engine or delete it.
+2. If the project has no e2e config (\`e2e.config.ts\` or \`e2e.config.mts\`), run \`npx e2e init --yes --engine mobile\` (or the pnpm or bun equivalent). It writes a mobile config with one target for this machine's platform and an example test against the Settings app, and installs nothing yet. Rewrite \`tests/example.e2e.ts\` for your app or delete it.
 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 \`.detoxrc.js\` into the e2e config: one target per platform with \`mobile({ platform })\`, the app's \`bundleId\` and \`appPath\` on the target, and the device type as \`mobile({ device })\`. e2e uses the normal debug or release build, with no Detox framework.

package/docs/migrate/maestro.mdx

@@ -12,13 +12,13 @@ export const migrationPrompt = `Migrate this project's Maestro flows to e2e, one
 
 1. Read the migration guide above. It maps every Maestro config option and command to e2e and marks what e2e does not have yet. The mobile guide covers devices and app builds.
 2. e2e tests are TypeScript. If the project has no \`package.json\`, as in a native iOS or Android project, create the test project in an \`e2e/\` folder beside the app.
-3. If the test project has no e2e config (\`e2e.config.ts\` or \`e2e.config.mts\`), run \`npx e2e init --yes\` (or the pnpm or bun equivalent) there. It writes a web config and an example test, and installs nothing yet. Replace @e2e-dev/web with @e2e-dev/mobile, and rewrite \`tests/example.e2e.ts\` for the mobile engine or delete it.
+3. If the test project has no e2e config (\`e2e.config.ts\` or \`e2e.config.mts\`), run \`npx e2e init --yes --engine mobile\` (or the pnpm or bun equivalent) there. It writes a mobile config with one target for this machine's platform and an example test against the Settings app, and installs nothing yet. Rewrite \`tests/example.e2e.ts\` for your app or delete it.
 4. Read the e2e skill (\`npx e2e guide\` prints it, \`npx e2e guide <topic>\` prints a topic) and follow it for every step below.
 5. 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.
 6. Port the flows' \`appId\` and \`.maestro/config.yaml\` into the e2e config: one target per platform with \`mobile({ platform })\`, \`app: { bundleId }\` on each target, and tags as \`{ tags }\` on tests. Move passwords and tokens from \`env\` into \`credentials\` or \`secrets\`.
 7. Install dependencies, then run \`npx agent-device doctor\` and fix what it reports.
 8. List the flows and ask me which one to move first. Suggest one whose \`optional\` steps and \`runFlow: { when }\` branches often need updating.
-9. Rewrite that flow as a \`.e2e.ts\` test under \`tests/\` (e2e runs \`tests/**/*.e2e.ts\` by default), with one awaited call per command. Start it with \`app.open()\`, since nothing launches on its own. Follow the guide's "Rewrite selectors" section: e2e matches the whole string and fails on several matches. Where the guide marks a command missing, use the workaround it gives, or leave that flow in Maestro and tell me why.
+9. Rewrite that flow as a \`.e2e.ts\` test under \`tests/\` (e2e runs \`tests/**/*.e2e.ts\` by default), with one awaited call per command. Start it with \`app.open()\`, since nothing launches on its own. Follow the guide's "Rewrite selectors" section: e2e matches the whole string and fails on several matches. Where the guide says "Not yet" or "No equivalent", use the workaround it gives, or leave that flow in Maestro and tell me why.
 10. Keep the launch and the final assertions deterministic, with \`app.open()\` and locator assertions. Where a run of scripted taps breaks often, propose an \`agent.act\` goal for it instead.
 11. Build and install the app, run the new file with \`npx e2e run <file>\` on each platform target, and fix it until it passes. Keep the Maestro flow until I confirm it can go.
 12. Summarize which flows moved, which stayed in Maestro, and why.`;
@@ -43,26 +43,26 @@ The reference pages hold the details: [screen](/reference/screen),
 [expect](/reference/expect), [test](/reference/test), and the
 [mobile engine](/reference/mobile).
 
-| 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: `agent.act('sign in as {email}', { params: { email } })` | renamed |
-| `MAESTRO_*` variables | `process.env` in the config; a password or token goes under `credentials` or `secrets`, which the model never sees, see [Signing in](/authentication) | renamed |
-| `--format junit`, `--output` | `--reporter list,junit`, written to `.e2e/junit.xml` | renamed |
-| `--format html` | no equivalent; `markdown` writes `.e2e/summary.md`, and each failed test gets a `trace.md` page under `.e2e/results/` | missing |
-| `properties` (JUnit `<property>`) | not yet | missing |
-| `--shards`, `--shard-split` | `device: [...]` plus `workers` on one machine; `--shard <index/total>` across machines, see [Sharding](/ci#sharding) | renamed |
-| `maestro record` | `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 |
+| Maestro | e2e |
+| --- | --- |
+| `appId` at the top of every flow | `app: { bundleId: 'com.example.app' }` on the target, the app `app.open()` launches |
+| a different `appId` per flow, or a second one mid-flow | `device.openApp(id)` inside the test, or separate app-specific configs and runs; every test runs on every selected target. With `mobileTools`, the agent's `open_app` tool switches apps inside a goal, see [Agent tools](/mobile#agent-tools) |
+| `--platform ios` | `mobile({ platform: 'ios' })`, one engine per platform |
+| `--device` | `mobile({ device: 'iPhone 17' })`; a list is a pool, one worker per device |
+| `.maestro/config.yaml` `flows` | `tests`, default `tests/**/*.e2e.ts`; Maestro runs one folder level, e2e recurses |
+| `flows: ['!helper.yaml']` | a `tests` entry with a leading `!`: `tests: ['tests/**/*.e2e.ts', '!tests/helpers/**']` |
+| `tags` and `--include-tags` | `{ tags: [...] }` on a test or group, `--tag` on the CLI |
+| `--exclude-tags` | `--exclude-tag` |
+| `env` and `${VAR}` | module constants, and `params` in a goal: `agent.act('sign in as {email}', { params: { email } })` |
+| `MAESTRO_*` variables | `process.env` in the config; a password or token goes under `credentials` or `secrets`, which the model never sees, see [Signing in](/authentication) |
+| `--format junit`, `--output` | `--reporter list,junit`, written to `.e2e/junit.xml` |
+| `--format html` | Not yet. `markdown` writes `.e2e/summary.md`, and each failed test gets a `trace.md` page under `.e2e/results/` |
+| `properties` (JUnit `<property>`) | Not yet |
+| `--shards`, `--shard-split` | `device: [...]` plus `workers` on one machine; `--shard <index/total>` across machines, see [Sharding](/ci#sharding) |
+| `maestro record` | `npx e2e run --video`, one MP4 of the device per attempt, or `video` in the config |
+| `maestro test -c`, Maestro Studio | Not yet. `npx e2e mcp` gives a coding agent a live session on the device, see [MCP server](/mcp) |
+| `maestro hierarchy` | Not yet. `device.locator` takes agent-device selectors for nodes `screen` cannot name |
+| Maestro Cloud | your CI, see [Continuous integration](/ci) |
 
 ## Rewrite one flow
 
@@ -99,111 +99,108 @@ test('asks for the email', async ({ app, agent, screen }) => {
 });
 ```
 
-A flow can also stay fully deterministic, with a `screen.getBy*(...).tap()`
-line for every `tapOn`.
-
 ## Map each command
 
-`Status` is `renamed`, `device only`, `by design`, or `missing` with what to
-do today. Calls on `device` run only on a device, so a test that uses it
-declares `requires: ['device']` and other targets skip it. Calls on `screen`,
-`app`, `agent`, and `expect(locator)` run on every target.
+Calls on `device` run only on a device, so a test that uses it declares
+`requires: ['device']` and other targets skip it. Calls on `screen`, `app`,
+`agent`, and `expect(locator)` run on every target. "Not yet" marks a
+command e2e doesn't have today, and "No equivalent" one it leaves out on
+purpose.
 
 <AccordionGroup>
 <Accordion title="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 |
+| Maestro | e2e |
+| --- | --- |
+| `launchApp` | `app.open()`, the fresh launch of the target's `app.bundleId`; nothing launches on its own |
+| `launchApp: { clearState: true }`, `clearState` | `app.clearState()` |
+| `launchApp: { stopApp: false }` | `device.openApp(id)` without `relaunch` |
+| `launchApp: { arguments }` | `app.launchArguments` on the target, or `device.openApp(app, { relaunch: true, launchArguments })` for one launch; a list of strings, not a map |
+| `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 |
+| `stopApp`, `killApp` | `device.closeApp()` |
+| `stopApp`, then `launchApp` | `app.restart()` |
+| `clearKeychain` | `device.clearKeychain()`, the whole simulator's keychain; iOS only |
+| `openLink` | `device.openLink(url, { app })`; on iOS the link opens into `app`, default the pinned app |
+| `addMedia` | Not yet |
+| `back` | `app.back()`, or `device.back()` |
 
 </Accordion>
 <Accordion title="Taps and input">
 
-| Maestro | e2e | Status |
-| --- | --- | --- |
-| `tapOn: "Text"` | `screen.getByText('Text').tap()`; exact, see [Rewrite selectors](#rewrite-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 [Rewrite selectors](#rewrite-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()` | 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 |
+| Maestro | e2e |
+| --- | --- |
+| `tapOn: "Text"` | `screen.getByText('Text').tap()`; exact, see [Rewrite selectors](#rewrite-selectors) |
+| `tapOn: { id: x }` | `screen.getByTestId('x').tap()` |
+| `tapOn: { text, index: 2 }` | `.nth(2)` |
+| `tapOn: { below: "Email" }`, `above`, `leftOf`, `rightOf`, `containsDescendants` | No equivalent, see [Rewrite selectors](#rewrite-selectors) |
+| `tapOn: { point: "x,y" }` | `screen.tapAt({ x, y })`; inside a node, `.tap({ position: { x, y } })` |
+| `retryTapIfNoChange`, `waitToSettleTimeoutMs` | `mobile({ settle, transition })`, engine-wide; no per-call knob |
+| `doubleTapOn`, `longPressOn` | `.doubleTap()`, `.longPress({ duration })` |
+| `inputText` | `screen.getByTestId('field').fill('text')` |
+| `inputRandomEmail`, `inputRandomText`, `faker` | `unique()` around a value in `act` params so the cache still replays; any npm faker for the rest |
+| `eraseText` | `.clear()` |
+| `hideKeyboard` | `device.dismissKeyboard()` |
+| `pressKey: Enter` | `.press('Enter')` on the field |
+| `pressKey: Home`, `back` | `device.home()`, `device.back()` |
+| `pressKey: lock`, `power`, `volume up`, TV remote keys | Not yet |
+| `copyTextFrom`, `pasteText` | `await locator.textContent()`, then `.fill(text)` |
+| `setClipboard` | `device.setClipboard(text)`; `device.clipboard()` reads it |
+| `label: "..."` on a command | Not yet. Every `screen`, `device`, and `agent` call is a report step named by the call |
 
 </Accordion>
 <Accordion title="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 |
+| Maestro | e2e |
+| --- | --- |
+| `swipe: { direction: UP }` | `screen.swipe({ direction: 'down' })`, or `locator.swipe(...)` inside one node; Maestro names the finger's direction, e2e the content's |
+| `swipe: { start, end }` | `screen.swipe({ from: { x, y }, to: { x, y } })` |
+| `scroll` | `screen.swipe({ direction: 'down' })` |
+| `scrollUntilVisible: { element }` | `screen.scrollUntilVisible(locator, { direction })` |
+| `waitForAnimationToEnd` | an assertion on the settled state; `mobile({ settle, transition })` for the engine |
 
 </Accordion>
 <Accordion title="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 }` | `await expect(screen).toHaveScreenshot(name, { maxDiffPixelRatio })`, see [Visual comparison](/visual-testing) | renamed |
-| `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 |
+| Maestro | e2e |
+| --- | --- |
+| `assertVisible`, `assertNotVisible` | `await expect(locator).toBeVisible()`, `.toBeHidden()` |
+| `assertVisible: { text, enabled: true }` | `.toBeVisible()` and `.toBeEnabled()` |
+| `assertVisible: { checked, selected, focused }` | `.toBeChecked()`, `.toBeSelected()`, `.toBeFocused()` |
+| `assertTrue: ${...}` | `expect(value).toBe(true)`, or `expect.poll` for a value that is still changing |
+| `extendedWaitUntil: { visible, timeout }` | `.toBeVisible({ timeout })` |
+| `assertScreenshot: { path, thresholdPercentage }` | `await expect(screen).toHaveScreenshot(name, { maxDiffPixelRatio })`, see [Visual comparison](/visual-testing) |
+| `assertDarkMode`, `assertLightMode` | Not yet. Assert on a themed control |
+| `retry: { maxRetries, commands }` | `expect.poll` for a value, `{ retries }` on the test for the flow |
+| `takeScreenshot` | `app.screenshot('label')`, redacted, withheld after a secret fill |
 
 </Accordion>
 <Accordion title="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; `true` is Android only | 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=text label="..."')`, agent-device's selector terms | device only |
+| Maestro | e2e |
+| --- | --- |
+| `setLocation` | `device.setLocation({ latitude, longitude })` |
+| `travel: { points }` | `device.setLocation` in a loop |
+| `setAirplaneMode`, `toggleAirplaneMode` | `device.setAirplaneMode(true)` or `false`, the state you want; `true` is Android only |
+| `setDarkMode`, `toggleDarkMode` | `device.setAppearance('dark')` or `'light'` |
+| `setOrientation` | `device.setOrientation('landscape-left')` |
+| `setPermissions` | `device.setPermission(name, 'grant' \| 'deny' \| 'reset')`, one permission per call, on the target's app, which need not be running; call it before `app.open()` |
+| platform-specific selectors | `device.locator('role=text label="..."')`, agent-device's selector terms |
 
 </Accordion>
 <Accordion title="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 [Rewrite selectors](#rewrite-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 [API](/api-testing) | renamed |
-| `onFlowStart`, `onFlowComplete` | `beforeEach`, `afterEach` | renamed |
-| `startRecording`, `stopRecording` | `test('x', { video: 'on' }, ...)` records that test's whole attempts; no start and stop inside a test | renamed |
+| Maestro | e2e |
+| --- | --- |
+| `assertWithAI`, `assertNoDefectsWithAI` | `agent.assert('...')`, `agent.assert('...', { vision: true })` |
+| `extractTextWithAI` | `agent.extract('...', { schema })` |
+| `runFlow: file.yaml` | a function, or a fixture from `test.extend` |
+| `runFlow: { when: { visible } }` | `if (await locator.isVisible()) { ... }`, see [Rewrite selectors](#rewrite-selectors) |
+| `optional: true` on a command | the same `isVisible()` check |
+| `repeat: { times: n }`, `repeat: { while }` | a `for` or `while` loop |
+| `runScript`, `evalScript`, `${output.x}` | TypeScript in the test |
+| `http.get`, `http.post`, `json()` | Node `fetch`, see [API](/api-testing) |
+| `onFlowStart`, `onFlowComplete` | `beforeEach`, `afterEach` |
+| `startRecording`, `stopRecording` | `test('x', { video: 'on' }, ...)` records that test's whole attempts; no start and stop inside a test |
 
 </Accordion>
 </AccordionGroup>
@@ -231,10 +228,9 @@ Four differences from Maestro's selectors cause most edits.
 
 ## What differs on purpose
 
-- 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
+- Tests get no agent-device client. Every call goes through `screen`, `app`,
+  `device`, or the agent, so e2e records and redacts it.
+- A device has no `test.setup` or `{ session }`, see
   [what differs from the web](/mobile#what-differs-from-the-web).
 
 ## Next