e2e 0.15.1 → 0.16.0

package/docs/explore.mdx

@@ -0,0 +1,174 @@
+---
+title: Exploring without a test
+description: Give the agent a goal instead of a test file. It plans its own steps, drives the app, and reports what it finds.
+---
+
+Use `e2e explore` to investigate a flow without writing a test. Give the
+agent a goal; it chooses the steps and records findings in
+`.e2e/report.json`.
+
+<CodeGroup>
+```bash npm
+npx e2e explore 'Explore the checkout flow like a first-time buyer and report anything off'
+```
+
+```bash pnpm
+pnpm exec e2e explore 'Explore the checkout flow like a first-time buyer and report anything off'
+```
+
+```bash bun
+bunx e2e explore 'Explore the checkout flow like a first-time buyer and report anything off'
+```
+</CodeGroup>
+
+Explore can help you investigate a feature or choose flows to turn into
+regression tests. It uses the same model, tools, and action rules as
+`agent.act()`. Review the findings against their evidence.
+
+## What a run does
+
+The runner opens the target app, plans one step, and carries it out with
+`agent.act`. The agent records findings as it goes, including what it
+expected, what it saw, and how to reproduce it. A screenshot is attached
+when capture is allowed and succeeds.
+
+The process repeats until the planner considers the goal covered or a
+budget expires, then produces a closing assessment. A failed step does not
+stop exploration. Three consecutive failed or blocked steps with no new
+findings end the run.
+
+## Budgets
+
+| Budget | Default | Range | Flag |
+| --- | --- | --- | --- |
+| Exploration steps | 8 | 1 to 12 | `--max-steps <n>` |
+| Wall clock | 10 minutes | 3 to 15 minutes | `--timeout <ms>` |
+| Actions and model calls per step | 40 each, unless the agent sets `maxSteps` or `maxModelCalls` | 1 to 100 | config |
+
+Start with the defaults. Increase the step or time budget when the report
+shows that the run stopped before reaching the part of the flow you need.
+
+## The verdict
+
+| Outcome | Run status | Exit code |
+| --- | --- | --- |
+| Steps ran, no `issue` finding, and not every step was blocked | passed | 0 |
+| At least one `issue` finding | failed | 1 |
+| No step ran and nothing was found | blocked | 1 |
+| Every step was blocked, with no `issue` finding | blocked | 1, 2, or 3, from the first blocker |
+| Config, engine, or model provider error | error | 2 or 3 |
+
+An `issue` is a functional defect and fails the run. A `warning` is cosmetic
+and does not. If every step was blocked, the run stays blocked and reports
+the first blocker's error. A step that reaches its action or time budget
+is recorded as time-boxed; findings still determine the verdict.
+
+## What you get
+
+The terminal follows the exploration as it happens: each finding the moment
+the agent reports it, and each step as it finishes, by title.
+
+```text
+ ❯  web  Exploring  Explore this bookshop like a careful first-time buyer: browse the catalog, ...
+   ⚑ medium issue  Home greeting exposes an unresolved userName template (/)
+   ⚑ high issue  Neuromancer shows an impossible negative stock availability (/catalog)
+   ✓ 1  Catalog browsing 31.46s · 7 actions · 4 findings
+   ⚑ high issue  Cart total does not update when Hyperion quantity increases (/cart)
+   ⚑ trivial warning  Checkout newsletter label misspells Receive (/checkout)
+   ✓ 2  Cart quantities and removal 19.47s · 4 actions · 3 findings
+   ended: the agent covered the goal
+```
+
+The final report lists issues before warnings, with the most severe first.
+Each finding includes its location, expected and observed behavior,
+reproduction steps, and any screenshot evidence. Severity runs from
+`trivial` at 1 to `critical` at 5.
+
+The JSON report stores these details under `run.explore`, along with the
+goal, budgets, steps, assessment, and reason the run ended. Findings carry no
+screenshots once a secret is filled; see
+[screenshots after a secret fill](/security#screenshots-after-a-secret-fill).
+
+Its artifacts land in a directory named after the goal, such as
+`.e2e/artifacts/web/explore-check-the-cart-totals-1a2b3c4d5e6f7a8b/`. A rerun
+of the same goal writes to the same directory.
+
+`--reporter list,markdown` also writes the findings to `.e2e/summary.md`.
+`--debug`, `--ai-trace`, `--trace`, and `--video` work as they do for
+`e2e run`: they apply when the engine can record, with a notice otherwise.
+The exploration is one attempt, so a retry mode (`on-first-retry`,
+`on-all-retries`, and the CI trace default) records nothing, and the run
+prints a notice saying to pass `--trace on` (or `--video on`); put the goal
+before a bare `--trace` or `--video`.
+
+## Your config applies
+
+Explore reads `e2e.config.ts`, including the target, app command, model, and
+agent context. It starts the target's app command. Use `--agent <name>` to select a configured agent.
+The agent's `tools` and `system` instructions also apply. Custom executors
+are replaced by the built-in agent for exploration, with a notice naming the
+agent. The built-in agent needs a model: an entry with none, a custom
+executor that brought none included, fails with `MODEL_UNAVAILABLE` before
+anything starts.
+
+Every configured credential is available to the explorer. It receives
+account names and usernames; passwords remain secret handles and require
+an engine that supports sensitive fills. Configure only the accounts needed
+for the exploration. Without credentials, it skips password sign-in.
+
+Use `--target <name>` to choose among several targets. Otherwise, explore
+uses the first and prints a notice. Exploration disables the replay cache
+and retries.
+
+## Start signed in
+
+Pass `--session <name>` to explore as a signed-in user. The name is a session
+a [setup test](/authentication) in your test files saves:
+
+<CodeGroup>
+```bash npm
+npx e2e explore --session admin 'Explore the admin settings and find bugs'
+```
+
+```bash pnpm
+pnpm exec e2e explore --session admin 'Explore the admin settings and find bugs'
+```
+
+```bash bun
+bunx e2e explore --session admin 'Explore the admin settings and find bugs'
+```
+</CodeGroup>
+
+Explore runs the one setup test that declares the session, restores the
+session, and opens the app when the target declares a URL, as for a test
+that declares `{ session: 'admin' }`. No other test runs. The setup test
+runs as it does for `e2e run`, with your configured agents, replay cache,
+and retries. The explorer is told the app starts signed in, so it does not
+plan a sign-in step.
+
+If no setup test declares the name, the run stops with `COLLECTION_ERROR`
+before any app process starts. The message lists the sessions your setup
+tests declare.
+
+A setup that fills a password leaves the exploration without screenshots. To
+keep them, sign in without filling a secret; see
+[screenshots after a secret fill](/security#screenshots-after-a-secret-fill).
+
+## Writing a good goal
+
+Name the flow and the user's goal, for example, "Explore checkout as a
+first-time buyer and check that totals match the cart." Include boundaries
+when needed, such as "stop before placing the order." Without a goal,
+explore uses `Explore the app and find bugs`.
+
+To cover a whole app or branch, run several explorations at once and verify
+what they find: see [Bug bashes](/bug-bash).
+
+<CardGroup cols={2}>
+  <Card title="CLI reference" icon="terminal" href="/reference/cli#e2e-explore">
+    Every flag of `e2e explore`.
+  </Card>
+  <Card title="Agents and personas" icon="users" href="/agents">
+    The agents explore can run as.
+  </Card>
+</CardGroup>

package/docs/github.mdx

@@ -0,0 +1,184 @@
+---
+title: Pull request comments
+description: The @e2e-dev/github reporter posts one comment per run from GitHub Actions and keeps it current.
+---
+
+`@e2e-dev/github` posts test results as a pull request comment, including
+failures, source links, and links to workflow artifacts. Reruns update the
+same comment, and a `--last-failed` rerun updates it as one run. The reporter
+also writes the results to the job summary.
+
+## Setup
+
+<CodeGroup>
+```bash npm
+npm install --save-dev @e2e-dev/github
+```
+
+```bash pnpm
+pnpm add -D @e2e-dev/github
+```
+
+```bash bun
+bun add -d @e2e-dev/github
+```
+</CodeGroup>
+
+```ts title="e2e.config.ts"
+import type { E2EConfig } from 'e2e';
+import { web } from '@e2e-dev/web';
+import { github } from '@e2e-dev/github';
+
+export default {
+  targets: [{ engine: web(), app: { url: 'http://localhost:3000' } }],
+  reporters: ['list', github()],
+} satisfies E2EConfig;
+```
+
+Give the workflow permission to write pull request comments and pass
+`GITHUB_TOKEN` to the test step:
+
+```yaml title=".github/workflows/e2e.yml"
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  e2e:
+    steps:
+      # ...checkout, install, browsers
+      - name: Run e2e
+        run: npx e2e run --reporter list,junit
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+      - name: Upload artifacts
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: e2e-artifacts
+          path: .e2e/artifacts
+```
+
+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
+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.
+
+## The comment
+
+```markdown
+### 🔴 e2e: 1 failed, 1 flaky, 3 passed, 1 skipped
+9 agent steps · 4 replayed from cache · 31 model calls · 128k tokens (62% cached) · $0.31
+
+**🔴 billing › upgrades to Pro**  
+[tests/billing.e2e.ts:12](https://github.com/acme/shop/blob/1a2b3c/tests/billing.e2e.ts#L12)
+
+**ASSERTION_FAILED** at step 4 of 6: `agent.act` "Pick the Pro plan and pay", after 38.0s and 12 model calls
+
+> expected heading "Your cart" to be visible
+> The Pay button opened a page that still shows the Free plan.
+
+- Failed the same way on both attempts: **ASSERTION_FAILED** at step 4.
+- Turn 9: `tap({"target":"n41"})` → Screen changed: /checkout/plan. New: #n50 heading "Free plan"
+- Screen: `/checkout/plan`
+
+Evidence: [screenshot](https://github.com/acme/shop/actions/runs/123#artifacts), [video](https://github.com/acme/shop/actions/runs/123#artifacts), [trace](https://github.com/acme/shop/actions/runs/123#artifacts)
+
+<details>
+<summary>⚠️ 1 flaky test passed on a retry</summary>
+
+**⚠️ invite a member by email**  
+[tests/team.e2e.ts:21](https://github.com/acme/shop/blob/1a2b3c/tests/team.e2e.ts#L21)
+
+**STEP_TIMEOUT** at step 3 of 3: `agent.waitFor` "the invitation email", after 30.0s
+
+> the invitation email took too long
+
+Evidence: [screenshot](https://github.com/acme/shop/actions/runs/123#artifacts), [trace](https://github.com/acme/shop/actions/runs/123#artifacts)
+</details>
+
+<details>
+<summary>All 6 tests in 5 files</summary>
+
+| | Test | Agent | Time |
+| --- | --- | --- | --- |
+| 🔴 | **tests/billing.e2e.ts** · 1 failed | 3 steps · 19 calls | 41.2s |
+| 🔴 | billing › upgrades to Pro | 3 steps · 19 calls | 41.2s |
+| ⚠️ | **tests/team.e2e.ts** · 1 flaky | 1 step | 6.4s |
+| ⚠️ | invite a member by email (1 failed attempt first) | 1 step | 6.4s |
+...
+</details>
+
+<sub>e2e 0.13.0 · 2m 15s · web · [run artifacts](https://github.com/acme/shop/actions/runs/123#artifacts)</sub>
+```
+
+The comment shows test counts and agent usage, followed by each failure's
+error, source line, and evidence links. Flaky tests and the full test list
+are collapsed; the list is one table with a row per file above its tests,
+and its agent column appears only when the run used the agent. Run-level
+errors appear above the test failures. Large
+reports are shortened to fit GitHub's comment limit. Text from the app under
+test that GitHub would turn into a mention, an issue link, or a URL is shown
+as code, so a screen reading `@someone` or `https://...` notifies no one and
+links nowhere.
+
+The built-in `markdown` reporter writes the same summary to
+`.e2e/summary.md`.
+
+## Rerunning the failed tests
+
+A step that gives failed tests a second chance keeps one comment for both
+passes:
+
+```yaml
+      - name: Run e2e
+        run: npx e2e run || npx e2e run --last-failed
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+```
+
+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.
+
+## Matrix jobs
+
+The reporter identifies a comment by project, workflow, and job. Matrix
+jobs share those identifiers, so give each matrix entry a distinct `key`:
+
+```ts
+reporters: ['list', github({ key: process.env.MATRIX_BROWSER })],
+```
+
+Set `MATRIX_BROWSER: ${{ matrix.browser }}` in the step's `env`. The key also
+appears in the headline, such as `e2e chromium: 77 passed`. Keep it stable
+across runs so reruns update the existing comment.
+
+## When nothing is posted
+
+The reporter never changes the run's status or exit code. When it cannot
+post, it says why in one row under the summary:
+
+```
+       Report  .e2e/report.json
+
+       GitHub  not posted: set GITHUB_TOKEN in the step's env (GITHUB_TOKEN: ${{ github.token }}); written to the job summary
+```
+
+| Situation | What happens |
+| --- | --- |
+| Not on GitHub Actions | Nothing is written; the row says so. |
+| A `push`, `schedule`, or `workflow_dispatch` run | The job summary is written; there is no pull request to comment on. |
+| No `GITHUB_TOKEN` in the step's `env` | The job summary is written; the row shows the line to add. `GH_TOKEN` is read too. |
+| A `pull_request` event from a fork | Its token is read-only, so posting fails and the reporter explains why. |
+| An `issue_comment` event | On a pull request's thread, the comment is posted without source links, since the checked-out commit is the default branch. |
+| Missing `pull-requests: write` | The same failure, with the permission named. |
+
+The token is read when the run finishes and is excluded from the report.
+GitHub Enterprise Server uses `GITHUB_SERVER_URL` and `GITHUB_API_URL`.

package/docs/index.mdx

@@ -0,0 +1,82 @@
+---
+title: Introduction
+description: Open source AI testing for web and mobile apps. Spend less time on tests and more time building.
+---
+
+import { VideoCard } from './snippets/video-card.jsx';
+
+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
+[assertions](/reference/expect#locator-matchers), fully driven by an agent
+from [goals](/writing-tests#goals-agent-act) in natural language, or a mix of
+both in the same test.
+
+<VideoCard
+  id="NEawZb6Hssw"
+  title="Watch e2e explained in 2 minutes"
+  subtitle="Learn how to chain agent goals with deterministic locator checks, run the same tests on web, iOS, and Android, and set up a project in a minute."
+/>
+
+```ts title="tests/checkout.e2e.ts"
+import { test, expect } from 'e2e';
+
+test('a member upgrades to Pro', async ({ app, agent, screen }) => {
+  await app.open('/settings/billing');
+
+  await agent.act('upgrade the workspace to the Pro plan');
+  await agent.assert('the invoice preview shows a prorated amount');
+
+  await expect(screen.getByRole('status')).toContainText('Pro');
+});
+```
+
+## Why e2e
+
+Testing should not slow down how fast you ship or how sure you are of what
+you shipped.
+
+- **Time back.** Write a goal instead of a script of selectors and waits.
+  When the UI changes, the agent adapts, so you spend less time writing and
+  fixing tests and more time building.
+- **Less risk.** Cover more of the flows your users depend on, on web and
+  mobile, and catch regressions before they reach production.
+- **Cheap runs.** Verified `agent.act` steps [replay from a cache](/cache)
+  with no model calls. Test more flows without the token bill or a slow CI.
+
+## How it works
+
+- **Targets.** Each test runs once per target, such as Chromium or an iPhone
+  simulator. The [web engine](/starting-your-app) drives browsers through
+  Playwright, the [mobile engine](/mobile) drives iOS simulators and Android
+  emulators through agent-device, and you can
+  [write your own](/writing-an-engine).
+- **Agent steps.** `agent.act` completes a goal. `agent.assert`,
+  `agent.waitFor`, and `agent.extract` judge the screen. Use your own
+  [subscription](/subscriptions), [API key, or local model](/models). Tests
+  without agent steps need no model.
+- **Cache.** An `act` step that a later check verifies is recorded. The next
+  run replays it and hands back to the agent when the app changed. `assert`,
+  `waitFor`, and `extract` always call the model.
+- **Reports.** The runner [redacts registered secrets](/security) from model
+  input and records steps, failures, and artifacts in a
+  [report](/debugging) you or your coding agent can read.
+
+## Get started
+
+<CardGroup cols={2}>
+  <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>
+  <Card title="Coding agents" icon="robot" href="/coding-agents">
+    Let your coding agent write, run, and debug tests.
+  </Card>
+  <Card title="Mobile" icon="mobile-screen" href="/mobile">
+    Run tests on iOS simulators and Android emulators.
+  </Card>
+</CardGroup>

package/docs/integrations/eas.mdx

@@ -0,0 +1,216 @@
+---
+title: EAS Simulators
+sidebarTitle: EAS Simulators
+description: Run mobile targets on EAS Simulators' hosted iOS simulators and Android emulators with the easSimulators() device provider from @e2e-dev/eas.
+---
+
+`easSimulators()` from `@e2e-dev/eas` is a
+[device provider](/mobile#hosted-devices) for
+[EAS Simulators](https://expo.dev/services/simulators). The run gets hosted
+iOS simulators or Android emulators, started when it starts and stopped when
+it ends, and the engine drives them through the agent-device daemon EAS runs
+beside each one. Tests, config, and CI stay the same.
+
+<Tip>
+No Mac, Xcode, or Android SDK on the machine that runs e2e.
+</Tip>
+
+## Setup
+
+<CodeGroup>
+```bash npm
+npm install --save-dev @e2e-dev/eas
+```
+
+```bash pnpm
+pnpm add -D @e2e-dev/eas
+```
+
+```bash bun
+bun add -d @e2e-dev/eas
+```
+</CodeGroup>
+
+EAS Simulators is in limited access; check yours with
+`npx eas-cli@latest simulator:availability`.
+
+```ts title="e2e.config.ts"
+import type { E2EConfig } from 'e2e';
+import { mobile } from '@e2e-dev/mobile';
+import { easSimulators } from '@e2e-dev/eas';
+
+export default {
+  targets: [
+    {
+      name: 'ios',
+      engine: mobile({
+        platform: 'ios',
+        device: easSimulators({ buildId: process.env.EAS_BUILD_ID }),
+        videoTouches: false,
+      }),
+      app: { bundleId: 'com.example.app' },
+    },
+  ],
+  workers: 2,
+} satisfies E2EConfig;
+```
+
+The sessions belong to the Expo project the app config links:
+`extra.eas.projectId`, the id `eas init` writes. The provider reads it from
+the app config beside `e2e.config.ts`:
+
+- **`app.json` or `app.config.json`**: read as JSON, from under `expo` when
+  the file has that key.
+- **A dynamic config** (`app.config.ts`, `.js`, `.mjs`, `.cjs`, `.mts`, or
+  `.cts`): evaluated with the project's own `expo config --type public`,
+  in the run's environment, since the config can compute the id. As with
+  eas-cli, `.env` files are not loaded (`EXPO_NO_DOTENV=1`), so a variable
+  the config reads must be in the environment `e2e run` starts in. It needs
+  `expo` installed in the project.
+
+It reads the config once per run, before the first session starts, and it
+needs an `@e2e-dev/mobile` that passes `projectRoot` to device providers; an
+older one fails the lease and asks for an upgrade or `projectId`. When
+`e2e.config.ts` is not in the app's directory, or the app config links no
+project, pass the id as `projectId` (the project's id, not its slug).
+
+The package calls Expo's API with `fetch`, so there is no SDK to install.
+
+## Authenticate
+
+The provider authenticates the way eas-cli does:
+
+* **`EXPO_TOKEN`**, an [access token](https://expo.dev/settings/access-tokens)
+  of an account or robot with access to the project, in the environment
+  `e2e run` starts in. Use it in CI, as a secret.
+* **The eas-cli login**, when `EXPO_TOKEN` is not set. On a machine where you
+  ran `eas login`, the provider reads the session eas-cli keeps in
+  `~/.expo/state.json` and needs no token. The home is the run's `HOME`, or
+  `USERPROFILE` on Windows.
+
+`EXPO_TOKEN` wins when both are there. Its account is the one that starts the
+sessions, so set it to run as a robot on a machine signed in as yourself.
+Sessions always go to production `api.expo.dev`: eas-cli's staging and local
+logins (`EXPO_STAGING`, `EXPO_LOCAL`) are not read.
+
+On a CI runner or shared machine, set `EXPO_TOKEN`. Without it, a login someone
+left in the runner's home starts billed sessions as their account.
+
+## Install the app
+
+The simulator boots with no apps. Pick one way to put yours on it:
+
+- **An EAS Build**: `buildId` names a simulator build (`"ios": { "simulator": true }`
+  in `eas.json`) or an APK, and EAS installs and launches it before the
+  session is ready. Leave the target's `app.appPath` out, and keep
+  `app.bundleId` so `app.open()` knows what to launch. The build never
+  leaves EAS.
+- **A URL**: `applicationArchiveUrl` names an app archive EAS downloads and
+  installs the same way.
+- **A local build**: the target's `app.appPath` and a fixture that calls
+  `device.installApp()`, as with a [local simulator](/mobile). The build
+  uploads through the session's daemon to each simulator. Leave `buildId`
+  and `applicationArchiveUrl` out.
+
+```ts
+// EAS installs the build.
+{ engine: mobile({ platform: 'ios', device: easSimulators({ buildId }) }), app: { bundleId: 'com.example.app' } }
+
+// A fixture uploads the build with device.installApp().
+{ engine: mobile({ platform: 'ios', device: easSimulators() }), app: { bundleId: 'com.example.app', appPath: 'build/App.app' } }
+```
+
+## Options
+
+| Option                  | Default     | Meaning |
+| ----------------------- | ----------- | ------- |
+| `projectId`             | the app config's | The Expo project the sessions belong to. Absent, `extra.eas.projectId` of the app config. See [Setup](#setup). |
+| `buildId`               | none        | EAS Build EAS installs and launches on every simulator. |
+| `applicationArchiveUrl` | none        | App archive URL EAS installs in place of a build. Excludes `buildId`. |
+| `device`                | EAS's pick  | iOS device name or UDID (`'iPhone 17 Pro'`), or an Android AVD hardware profile (`'pixel_9'`). |
+| `maxIdleTimeMinutes`    | `10`        | Minutes without an agent-device command after which EAS stops the session. EAS wants it below `maxDurationMinutes`, so a shorter duration lowers the default to one less. See [What the provider does](#what-the-provider-does). |
+| `maxDurationMinutes`    | account cap | Minutes a session may run once ready. EAS caps it at 40, or 115 on a high-priority plan. |
+| `agentDeviceVersion`    | the engine's | The agent-device version EAS starts the session's daemon at. Defaults to the one `@e2e-dev/mobile` pins, so the remote daemon answers as the engine's client expects; without it EAS starts the latest. |
+| `tags`                  | `[]`        | Tags on every session, beside the run's own. |
+
+An option not in this table, `buildId` and `applicationArchiveUrl` together, or
+a `maxIdleTimeMinutes` not below a `maxDurationMinutes` passed with it fails the
+config load with `INVALID_CONFIG`.
+
+## Sessions
+
+Each target starts up to `workers` sessions (`--workers` overrides it),
+fewer when it has fewer test files, and tests start once all are ready.
+A session takes about three minutes from request to ready (queue, boot,
+build install), all in parallel, before the run's clock starts.
+
+A run must fit in one session's lifetime: EAS stops a session
+`maxDurationMinutes` after it is ready, 40 minutes by default on a
+normal-priority plan and 115 on a high-priority one. Split a longer suite
+across more workers or across CI jobs.
+
+EAS runs as many sessions at once as the Expo account allows, and queues
+the rest until one ends. None ends before the run does, so keep `workers`
+times the number of EAS targets within that number. Every session queues
+for a few seconds; one still queued after two minutes logs `still queued at
+EAS after two minutes`. Targets prepare one after another, so the sessions of a target
+that is ready wait idle while the next target's queue and boot. A session
+still queued once another session of the run has been ready for
+`maxIdleTimeMinutes` fails the lease, and the run stops every session: EAS
+is stopping the idle one.
+
+## Watch a run
+
+The provider logs each session's expo.dev page as it is created:
+
+```text
+ℹ leasing 2 ios device(s) from eas-simulators
+ℹ eas-simulators (1 of 2): simulator session 01a0…, https://expo.dev/accounts/acme/projects/shop/simulator-sessions/01a0…
+ℹ eas-simulators: leased 01a0…
+```
+
+A browser preview that opens without a token is logged too, as
+`watch at <url>`. A preview that needs one is not: the token would give
+anyone who reads the CI log control of the simulator.
+
+Sessions are named `e2e <target> <n> of <total>` and tagged `e2e`,
+`e2e-run:<run id>`, and `e2e-target:<target>`, so
+`eas simulator:list --tag e2e-run:<run id>` finds a run's sessions.
+
+## Recordings
+
+An attempt that records [video](/reference/config#video) records through
+agent-device on the simulator, as it does locally, and saves
+`video/video.mp4` under the attempt's artifact directory.
+
+Set the mobile engine's `videoTouches: false`, as the setup above does.
+agent-device draws its touch indicator into a recording when the recording
+stops, and on an EAS iOS simulator that takes minutes, so every attempt that
+records video runs out its `cleanupTimeout` stopping it and keeps no file.
+Without the indicator, stopping takes about two seconds.
+
+## What the provider does
+
+- Reads the project id from the app config once, before the first session,
+  when `projectId` is absent. A config that links no project fails the
+  lease before any session starts, naming the file.
+- Starts each `agent-device` session and waits until its daemon is
+  reachable, then hands the engine the daemon's URL and token.
+- Defaults `maxIdleTimeMinutes` to 10. A run that dies before the engine
+  stops its sessions leaves them idle, and EAS stops them after that long.
+- Starts each daemon at the agent-device version `@e2e-dev/mobile` pins.
+- Stops a session that errors, is cancelled, stays queued while another
+  session of the run idles to `maxIdleTimeMinutes`, or is still booting 15
+  minutes after leaving the queue, and treats one EAS no longer knows as
+  already stopped.
+- Cancels the job of a session it stops while the job is still queued:
+  EAS would otherwise start it later and count it against the account's
+  concurrent sessions.
+- Rides out up to three failed status polls in a row, a blip at
+  api.expo.dev, before giving a session up.
+
+No `EXPO_TOKEN` and no eas-cli login fails the lease before any request to
+EAS, with a message to run `eas login` or set `EXPO_TOKEN`. An account without
+EAS Simulators, or a session that fails to start, fails the lease with EAS's
+message. Either ends the run before any test, and the run's other sessions,
+started or queued, are still stopped.

package/docs/integrations/index.mdx

@@ -0,0 +1,24 @@
+---
+title: Integrations
+sidebarTitle: Overview
+description: Official integrations with hosted services, one package per service.
+---
+
+Official integrations connect e2e to hosted services through the engines'
+provider seams, one package per service. Tests and CI stay the same, and the
+config changes only where a target names its `browser` or `device`: the
+integration decides where it comes from.
+
+<CardGroup cols={2}>
+  <Card title="Kernel" icon="/images/integrations/kernel.svg" href="/integrations/kernel">
+    `@e2e-dev/kernel`: hosted Chromium for web targets, one browser per worker or per test.
+  </Card>
+  <Card title="EAS Simulators" icon="/images/integrations/expo.svg" href="/integrations/eas">
+    `@e2e-dev/eas`: hosted iOS simulators and Android emulators for mobile targets.
+  </Card>
+</CardGroup>
+
+A service without an integration is one small provider in your project:
+see [Hosted browsers](/browser#hosted-browsers) for the web engine's
+`BrowserProvider` and [Hosted devices](/mobile#hosted-devices) for the mobile engine's
+`DeviceProvider`.