e2e 0.21.1 → 0.21.2

package/docs/authentication.mdx

@@ -8,8 +8,9 @@ icon: "key"
 
 A setup test signs in one time and saves a named session. Other tests
 restore that session and start signed in. Passwords and other secrets are
-handles: the runner types the value and redacts it from model input and
-reports, with [some limits](/reference/security#where-redaction-stops).
+handles: the runner types the value and shows `<secret:name>` in its place
+in model input and reports, with
+[some limits](/reference/security#where-redaction-stops).
 
 ## Sign in once in a setup test
 
@@ -89,6 +90,9 @@ memory and deletes it at cleanup. See [Sessions](/reference/security#sessions).
 Declare each account in config. Read the password from the environment:
 
 ```ts title="e2e.config.ts"
+import type { E2EConfig } from 'e2e';
+import { web } from '@e2e-dev/web';
+
 export default {
   targets: [{ engine: web(), app: { url: 'http://127.0.0.1:3000' } }],
   credentials: {
@@ -128,10 +132,9 @@ export default {
 } satisfies E2EConfig;
 ```
 
-The value goes to the field, the redaction ledger, and the encrypted payload
-of a [saved session](/reference/security#sessions). It's redacted only from
-its first fill on. If the app can show the value before a test
-types it, use a string. The same applies to a `secrets` entry.
+The value is redacted only from its first fill on. If the app can show the
+value before a test types it, use a string. The same applies to a `secrets`
+entry.
 
 </Accordion>
 
@@ -139,8 +142,7 @@ types it, use a string. The same applies to a `secrets` entry.
 
 `credentials.user(name)` returns the username as a plain string and the
 password as a `Secret` named `<name>.password`. A `Secret` has no `.value`.
-Pass it to a `fill`, to the `params` of an agent step, or to an engine
-option that declares it, such as [`basicAuth`](/web#protected-previews):
+Pass it to a `fill` or to the `params` of an agent step:
 
 ```ts
 await agent.act('Sign in', {
@@ -148,21 +150,19 @@ await agent.act('Sign in', {
 });
 ```
 
-The model sees only the secret's name and purpose. The runner authorizes the fill,
-requires a password field for a password, and types the value. Known
-values become `<secret:name>` in model input, observations, and reports.
-See the [secret fill rules](/reference/security#secret-fills). The agent
-can't read a secure field, so assert that sign-in succeeded instead.
+The model sees only the secret's name and purpose. When the model fills a
+password, the runner requires a password field and types the value. See the
+[secret fill rules](/reference/security#secret-fills). The agent can't read
+a secure field, so assert that sign-in succeeded instead.
 
 After a secret fill, the runner takes no screenshots for the rest of the
-attempt, or in the tests that restore the session it saved. See
-[screenshots after a secret fill](/reference/security#screenshots-after-a-secret-fill)
-for how to sign in with screenshots kept.
+attempt, or in the tests that restore the session it saved. To keep them, see
+[screenshots after a secret fill](/reference/security#screenshots-after-a-secret-fill).
 
 <Warning>
-Redaction matches full values and their encoded forms. A transformed value,
-such as the last four characters of a key, can still appear. Keep secret
-entry in setup tests, and assert the result of the submit. See
+Redaction matches strings. A transformed value, such as the last four
+characters of a key, can still appear. Keep secret entry in setup tests, and
+assert the result of the submit. See
 [where redaction stops](/reference/security#where-redaction-stops).
 </Warning>
 
@@ -171,6 +171,9 @@ entry in setup tests, and assert the result of the submit. See
 Use `secrets` for API keys, webhook tokens, and other values a test types:
 
 ```ts title="e2e.config.ts"
+import type { E2EConfig } from 'e2e';
+import { web } from '@e2e-dev/web';
+
 export default {
   targets: [{ engine: web(), app: { url: 'http://127.0.0.1:3000' } }],
   secrets: {
@@ -195,10 +198,10 @@ A `secrets` entry can fill any editable input. An unconfigured name throws
 `SECRET_UNAVAILABLE`. `secrets.get()` returns `secrets` entries only, so
 `credentials.admin` and `secrets.admin` can both exist.
 
-In `e2e.config.ts`, `secrets.get()` can pass a secret to an engine option,
-such as a basic-auth password. The config load checks the name. This
-protects text only: screenshots keep the pixels. See
-[Secrets in engine options](/reference/security#secrets-in-engine-options).
+In `e2e.config.ts`, `secrets.get()` can pass a secret to an engine option
+that declares it, such as [`basicAuth`](/web#protected-previews). The config
+load checks the name. Screenshots stay on, so the app's pixels aren't masked.
+See [Secrets in engine options](/reference/security#secrets-in-engine-options).
 
 ## Override a value per run
 

package/docs/browser.mdx

@@ -201,7 +201,9 @@ bunx @e2e-dev/web install webkit --with-deps
 ```
 </CodeGroup>
 
-`connect` attaches to a remote Chromium over CDP instead of launching one.
+`connect` attaches to a remote Chromium over CDP instead of launching one,
+or to another browser that speaks CDP, such as a running
+[Lightpanda](/integrations/lightpanda).
 To set sizes, see [Viewports](/web#viewports).
 
 ## Hosted browsers
@@ -215,14 +217,15 @@ when the run no longer uses it.
 | --- | --- |
 | [Kernel](/integrations/kernel) | `kernel()` from `@e2e-dev/kernel` |
 | [smol machines](/integrations/smol) microVMs on your own computer | `smol()` from `@e2e-dev/smol` |
+| [Lightpanda](/integrations/lightpanda), the open-source headless browser, on your own machine | `lightpanda()` from `@e2e-dev/lightpanda` |
 | Any other service | Your own provider, a few dozen lines in your project |
 
 When the service shows the window in a live view, add `viewport: null` so
 the page [fills the window](/web#fill-the-window).
 
-A provider implies Chromium, the only browser CDP attach works on, and
-can't be combined with `connect`. A target with nothing to run leases
-nothing.
+A provider implies a browser the engine drives as Chromium over CDP,
+Chromium itself or Lightpanda, and can't be combined with `connect`. A
+target with nothing to run leases nothing.
 
 ### Write a provider
 

package/docs/bug-bash.mdx

@@ -78,7 +78,7 @@ Bug bash the checkout and account settings on this branch.
    environment, the intended design, or the seed data.
 6. Writes a repro test that asserts the expected behavior for each
    remaining finding. It can start one subagent per area, each with its own
-   [`e2e mcp` session](/reference/mcp#several-sessions) to check locators.
+   [`e2e mcp` session](/mcp) to check locators.
 7. Runs each repro test. The finding is a bug only when the test fails with
    `ASSERTION_FAILED`.
 8. Reports, in this order: confirmed bugs, production risks that it cannot
@@ -124,7 +124,7 @@ regression test.
   <Card title="Exploring without a test" icon="compass" href="/explore">
     What one `e2e explore` run does, its budgets, and its report.
   </Card>
-  <Card title="MCP server" icon="plug" href="/reference/mcp">
+  <Card title="MCP server" icon="plug" href="/mcp">
     Live sessions for coding agents, several at once.
   </Card>
 </CardGroup>

package/docs/cache.mdx

@@ -62,7 +62,8 @@ a run leaves the cache unchanged.
 An attempt whose only failures are ones where no model answered evicts
 nothing, since these say nothing about the app:
 
-- `MODEL_UNAVAILABLE`: no model is configured.
+- `MODEL_UNAVAILABLE`: no model is configured, or GitHub Copilot doesn't
+  serve it to the account.
 - `MODEL_PROVIDER_FAILED`: the provider returned an error, such as a
   missing or rejected key, a rate limit, or a 5xx, or a request got no
   response within 120 seconds.
@@ -93,6 +94,10 @@ agent. Each of these changes causes a miss:
 Changing the model doesn't cause a miss, and neither does upgrading the
 engine: a node the new version resolves differently misses at replay.
 
+Use `--no-cache` to evaluate a new model. Replays expose
+`step.cache.recordedBy` when the entry has provenance; older or unattributed
+entries omit it.
+
 A timestamp or a fresh email address would miss on every run. Wrap such
 values in `unique()`, and the runner puts in the current value at replay:
 

package/docs/ci/bitrise.mdx

@@ -37,7 +37,7 @@ format_version: '25'
 default_step_lib_source: https://github.com/bitrise-io/bitrise-steplib.git
 
 tools:
-  nodejs: 22:installed
+  nodejs: 24:latest
 
 pipelines:
   e2e:

package/docs/ci/codemagic.mdx

@@ -40,7 +40,7 @@ workflows:
     environment:
       groups:
         - e2e
-      node: 22
+      node: 24
       xcode: latest
     triggering:
       events:
@@ -77,7 +77,7 @@ workflows:
     environment:
       groups:
         - e2e
-      node: 22
+      node: 24
     triggering:
       events:
         - push

package/docs/ci/eas-workflows.mdx

@@ -64,7 +64,7 @@ on:
 
 defaults:
   tools:
-    node: '22'
+    node: '24'
 
 jobs:
   build_ios:

package/docs/coding-agents.mdx

@@ -87,39 +87,10 @@ codex plugin marketplace upgrade e2e
 
 ## Let the agent use the app
 
-`e2e mcp` lets the coding agent open the app and use it. Each agent,
-subagents included, opens its own session, so several can use the app at
-the same time. The `locate` tool checks a `screen.*` locator against the
-current app and returns the test code when exactly one element matches.
-
-`init` registers the server in `.mcp.json` for Claude Code and
-`.cursor/mcp.json` for Cursor. To register it with Claude Code by hand:
-
-<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>
-
-For Codex, add the server to the project's `.codex/config.toml`, trust the
-project, and start a new session:
-
-```toml
-[mcp_servers.e2e]
-command = "npx"
-args = ["e2e", "mcp"]
-```
-
-The server does not run tests. See the [MCP server reference](/reference/mcp)
-for its tools, session rules, and flags.
+`e2e mcp` gives the agent a live session on your app. It checks each
+locator against the screen before it writes the test, and checks its own UI
+changes. `init` registers the server. See [MCP server](/mcp) for setup and
+prompts.
 
 ## How an agent writes and runs a test
 
@@ -251,8 +222,9 @@ bunx skills add tester-army/e2e --skill migrate-to-e2e
 
 Then ask the agent for `/migrate-to-e2e`. It ports the slice you pick and
 runs each ported test three times on every target. A `MIGRATION.md` file
-records progress for the next session. The agent deletes an old test only
-when you confirm. It first reads the migration guide for your runner:
+records progress for the next session. Optionally, the agent plants a temporary bug
+in the app, such as a wrong checkout total, and checks whether both
+suites fail on it. The agent deletes an old test only when you confirm. It first reads the migration guide for your runner:
 [Playwright](/migrate/playwright), [Cypress](/migrate/cypress),
 [Selenium](/migrate/selenium), [Detox](/migrate/detox), or
 [Maestro](/migrate/maestro).

package/docs/debugging.mdx

@@ -6,9 +6,8 @@ icon: "magnifying-glass"
 "twitter:image": "https://e2e.tester.army/docs/images/og/debugging.png?v=38a51086e1"
 ---
 
-A failed test names its [trace page](#traces) in the terminal. The page
-lists every step, links the evidence, and shows the screen at failure. For a
-summary of the whole run, add the `markdown` reporter. It writes
+A failed test prints its error and the path to its [trace page](#traces). For
+a summary of the whole run, add the `markdown` reporter. It writes
 `.e2e/summary.md`.
 
 ## Read the failure
@@ -148,8 +147,8 @@ attempts under each test's `rerun-<n>/`.
 | Artifact | When |
 | --- | --- |
 | Screenshots | A failed attempt captures one when the engine can and pixels are allowed. The built-in `agent.assert` captures one after either verdict, unless `screenshot: false`. `app.screenshot('label')` captures one on request. After a secret fill, the runner takes [none](/reference/security#screenshots-after-a-secret-fill) for the rest of the attempt. |
-| Downloads | Files saved through `browser.waitForDownload`, kind `download`. They are the app's bytes, marked `redaction: "incomplete"`. When the session knows a secret value and the file is text, the runner rewrites it and marks it `complete`. |
-| Videos | When you [record them](#watch-it-happen). Videos mask nothing and are marked `redaction: "incomplete"`. See [where redaction stops](/reference/security#where-redaction-stops). |
+| Downloads | Files saved through `browser.waitForDownload`, kind `download`, as the app served them. [Downloads](/reference/security#downloads) says when the runner masks secrets in them. |
+| Videos | When you [record them](#watch-it-happen). Videos mask nothing. See [where redaction stops](/reference/security#where-redaction-stops). |
 | Agent transcripts | With [`--debug`](#agent-steps). |
 
 ## For scripts: report.json
@@ -176,6 +175,14 @@ result holds:
 | `appLog` | What the app logged. Each line's `step` is the `index` of its step, absent before the first step. |
 | `artifacts` | The captured files |
 
+A serial group's tests have no `attempts` of their own. Their results are in
+`run.serialGroups`, one member for each test in each attempt:
+
+```bash
+jq '.run.serialGroups[] | .attempts[-1].members[]? | select(.status != "passed")
+    | {testId, status, error, failure}' .e2e/report.json
+```
+
 ## Watch it happen
 
 <CodeGroup>
@@ -199,8 +206,7 @@ bunx e2e run --video=retain-on-failure     # record every attempt, keep the fail
 </CodeGroup>
 
 `--video` takes an optional mode. Put test files before it, or write
-`--video=<mode>`. The flag and the config's `video` apply to the targets
-whose engine can record, and one notice names the others.
+`--video=<mode>`.
 
 Each recording goes into its attempt's directory: WebM per page on web, MP4
 on a device. The failure recap prints the path, or the URL when a hosted
@@ -211,32 +217,14 @@ In CI, set `video: 'on-first-retry'` in the config. A test that passes the
 first time records nothing, and a flaky test leaves a recording of its
 retry.
 
-<Accordion title="Set video in the config, on a target, or on a test">
-
-```ts
-export default {
-  video: 'on-first-retry',
-  retries: 1,
-  targets: [
-    { name: 'chromium', engine: web(), app: { url } },
-    { name: 'firefox', engine: web({ browser: 'firefox' }), app: { url }, video: 'retain-on-failure' },
-  ],
-} satisfies E2EConfig;
-```
-
 A target's `video` wins over the config's, and `--video` wins over both. A
-test's own option wins over all of them:
-
-```ts
-test('checkout', { video: 'on' }, async ({ agent }) => {
-  await agent.act('Buy the first product in the catalog');
-});
-```
+test's own option, such as `test('checkout', { video: 'on' }, ...)`, wins
+over all of them.
 
-A mode on a target or a test is a requirement. When the engine can't record
-it, the run fails with `UNSUPPORTED_ARTIFACT` before any test starts.
-
-</Accordion>
+The config's `video` and `--video` apply only to targets whose engine can
+record, and one notice names the others. When a target or a test asks for a
+recording its engine can't make, the run fails with `UNSUPPORTED_ARTIFACT`
+before any test starts.
 
 [Recording](/reference/config#recording) has every mode and file.
 
@@ -246,7 +234,7 @@ it, the run fails with `UNSUPPORTED_ARTIFACT` before any test starts.
 heading that names the stream, target, file, and test:
 
 ```text
-stdout | web tests/todos.e2e.ts > adds a todo
+stdout | |web| tests/todos.e2e.ts > adds a todo
 hello from the test
 ```
 
@@ -304,17 +292,17 @@ prompts, tool calls, and token usage:
 <CodeGroup>
 ```bash npm
 npx unbox-ai runs .e2e/ai-trace.json
-npx unbox-ai summary .e2e/ai-trace.json --run 1
+npx unbox-ai summary .e2e/ai-trace.json --run 0
 ```
 
 ```bash pnpm
 pnpm dlx unbox-ai runs .e2e/ai-trace.json
-pnpm dlx unbox-ai summary .e2e/ai-trace.json --run 1
+pnpm dlx unbox-ai summary .e2e/ai-trace.json --run 0
 ```
 
 ```bash bun
 bunx unbox-ai runs .e2e/ai-trace.json
-bunx unbox-ai summary .e2e/ai-trace.json --run 1
+bunx unbox-ai summary .e2e/ai-trace.json --run 0
 ```
 </CodeGroup>
 
@@ -333,7 +321,7 @@ to trace the whole flow or rule out a stale [recording](/cache).
 | `ASSERTION_INCONCLUSIVE` | `agent.assert` or `agent.extract` asked about something the screen doesn't show: on another page, still loading, or only in pixels | Open or wait for the right screen first; add `vision: true` when the answer is in pixels (the message says so) |
 | `ACTION_FAILED` | Element covered, disabled, or detached, or an operation timed out | Wait on the right condition with `expect` first; close overlays |
 | `STEP_BUDGET_EXHAUSTED`, `STEP_TIMEOUT` | The agent ran out of actions, model calls, or time | Scope the goal to one step. Raise the agent entry's `maxSteps` or `maxModelCalls` for the budget, the config `timeout` for an `act` step, or the agent's `judgmentTimeout` for `assert`, `waitFor`, and `extract` |
-| `MODEL_UNAVAILABLE` | No model constructed in the config | See [Models](/models) |
+| `MODEL_UNAVAILABLE` | No model constructed in the config, or GitHub Copilot doesn't serve the configured model to your account | See [Models](/models); for Copilot, [Pick a model](/subscriptions#pick-a-model) |
 | `MODEL_PROVIDER_FAILED` | Bad key, rate limit, no credits, or every try of one request went 120 s without an answer | Check the key the provider reads and the quota; for a slow local model, a smaller screen (`agents.<name>.maxObservationBytes`) or a faster model |
 
 The [errors reference](/reference/errors) lists every code, its class, and

package/docs/executors.mdx

@@ -124,7 +124,7 @@ export default {
 | `ctx.step` | The `kind`, instruction, params, and `index` in the attempt's timeline. A configured secret's value in the instruction or a param reads `<secret:name>`. A `secrets.get()` handle arrives as a name-only placeholder that `typeSecret` fills |
 | `ctx.observe({ tree, pixels })` | Redacted screen text, with an optional node tree and masked screenshot |
 | `ctx.actions` | Checked and recorded actions: `tap`, `doubleTap`, `longPress`, `secondaryTap`, `hover`, `type`, `typeSecret`, `press`, `select`, `check`, `drag`, `scrollTo`, `scrollUntil`, `upload`, `scroll`, `navigate`, `back`, and the point and keyboard actions below |
-| `ctx.target` | The target's `name`, `platform`, and `verbs`, the actions its engine supports. Offer only these to the model |
+| `ctx.target` | The target's `name`, `platform`, and `verbs`, the actions its engine supports. Offer only these to the model. `tapModifiers` is true when `tap`, `doubleTap`, and `secondaryTap` take `{ modifiers }` |
 | `ctx.pixelsTainted` | True after a [secret fill](/reference/security#screenshots-after-a-secret-fill). Then no screenshots are available |
 | `ctx.signal` | Aborts on cancellation, at the step deadline, or on any other hard stop. The deadline can't stop work that ignores it |
 | `ctx.replayedPrefix` | Set when a cache replay ran part of the step first. See [Replay cache](#replay-cache) |

package/docs/github.mdx

@@ -182,6 +182,7 @@ post, one row under the summary gives the reason:
 | A `pull_request` event from a fork | The token is read-only, so posting fails. The row says why. |
 | An `issue_comment` event | On a pull request's thread, the comment has no source links, because the checked-out commit is on the default branch. |
 | Missing `pull-requests: write` | Posting fails, and the reporter names the permission. |
+| GitHub API rate limit | Posting stops and reports throttling. Wait for the reset or `Retry-After` before rerunning the job. |
 
 The reporter reads the token when the run finishes, and the report doesn't
 include it. On GitHub Enterprise Server, the reporter uses
@@ -190,7 +191,7 @@ include it. On GitHub Enterprise Server, the reporter uses
 ## Next
 
 <CardGroup cols={2}>
-  <Card title="GitHub Actions" icon="github" href="/ci/github-actions">
+  <Card title="GitHub Actions" icon="/images/integrations/github-actions.svg" href="/ci/github-actions">
     The full workflow: install, browsers, cache, and artifacts.
   </Card>
   <Card title="Debugging a run" icon="magnifying-glass" href="/debugging">

package/docs/integrations/eas.mdx

@@ -127,7 +127,7 @@ The simulator boots with no apps. Choose one way to put yours on it:
 An unknown option, `buildId` with `applicationArchiveUrl`, or a
 `maxIdleTimeMinutes` not below a `maxDurationMinutes` passed with it fails
 the config load
-with `INVALID_CONFIG`.
+with `INVALID_CONFIG`. Both minute limits must be non-negative integers.
 
 ## Sessions
 

package/docs/integrations/index.mdx

@@ -15,6 +15,9 @@ Only the target's `browser` or `device` in the config changes.
   <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="Lightpanda" icon="/images/integrations/lightpanda.svg" href="/integrations/lightpanda">
+    `@e2e-dev/lightpanda`: the open-source headless browser, started per worker slot on your own machine, no Chromium.
+  </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>
@@ -24,6 +27,9 @@ Only the target's `browser` or `device` in the config changes.
   <Card title="Limrun" icon="/images/integrations/limrun.svg" href="/integrations/limrun">
     `@e2e-dev/limrun`: hosted iOS simulators and Android emulators, with app installation and device cleanup.
   </Card>
+  <Card title="TestMu AI" icon="/images/integrations/testmu.svg" href="/integrations/testmu">
+    `@e2e-dev/testmu`: hosted Android emulators, iOS simulators, and real devices for mobile targets.
+  </Card>
 </CardGroup>
 
 ## Use a service with no integration

package/docs/integrations/lightpanda.mdx

@@ -0,0 +1,192 @@
+---
+title: Lightpanda
+sidebarTitle: Lightpanda
+description: Run web targets in Lightpanda, the open-source headless browser, with the lightpanda() browser provider from @e2e-dev/lightpanda.
+icon: "/images/icons/lightpanda.svg"
+"og:image": "https://e2e.tester.army/docs/images/og/integrations/lightpanda.png?v=b97a3ebae4"
+"twitter:image": "https://e2e.tester.army/docs/images/og/integrations/lightpanda.png?v=b97a3ebae4"
+---
+
+[Lightpanda](https://lightpanda.io) is an open-source headless browser
+written from scratch, without Chromium. It starts in milliseconds, holds a
+fraction of Chrome's memory, and speaks the Chrome DevTools Protocol.
+`lightpanda()` from `@e2e-dev/lightpanda` is a
+[browser provider](/browser#hosted-browsers) for it: each worker slot gets
+its own `lightpanda serve`, started on a free port when the run starts and
+stopped when it ends. Tests and CI stay the same; the config changes only
+in the target's `browser`.
+
+Lightpanda has no layout engine. It builds the DOM, runs JavaScript, and
+exposes the accessibility tree the engine reads, which is what locators,
+assertions, and [agent steps](/agent-steps) use. Anything that depends on
+where a node is painted behaves differently; see
+[What does not work](#what-does-not-work) before moving a suite over.
+
+## Setup
+
+Install the package:
+
+<CodeGroup>
+```bash npm
+npm install --save-dev @e2e-dev/lightpanda
+```
+
+```bash pnpm
+pnpm add -D @e2e-dev/lightpanda
+```
+
+```bash bun
+bun add -d @e2e-dev/lightpanda
+```
+</CodeGroup>
+
+And the Lightpanda nightly binary, which the provider starts:
+
+<CodeGroup>
+```bash macOS
+brew install lightpanda-io/browser/lightpanda
+```
+
+```bash Linux
+curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux
+install -D -m 755 lightpanda ~/.local/bin/lightpanda
+```
+</CodeGroup>
+
+```ts title="e2e.config.ts"
+import type { E2EConfig } from 'e2e';
+import { web } from '@e2e-dev/web';
+import { lightpanda } from '@e2e-dev/lightpanda';
+
+export default {
+  targets: [
+    {
+      name: 'lightpanda',
+      engine: web({ browser: lightpanda() }),
+      app: { url: 'http://localhost:3000' },
+    },
+  ],
+} satisfies E2EConfig;
+```
+
+The provider runs `lightpanda` from `PATH`, `~/.lightpanda/lightpanda`, or
+`~/.local/bin/lightpanda`, the places
+[agent-browser](https://agent-browser.dev/engines/lightpanda) looks too, or
+the binary `LIGHTPANDA_PATH` names in the environment `e2e run` starts in,
+or `binary` in the options. None found fails the run before any test,
+naming the install page.
+Each worker gets its own server, so `workers` sets how many run at once,
+and the run's log names each one:
+
+```text
+ℹ lightpanda (1 of 2): lightpanda 1.1.0-nightly at ws://127.0.0.1:51165/
+```
+
+## Attach to a running server
+
+A Lightpanda already running, such as the Docker image in CI, is a
+[`connect`](/reference/web#options) target rather than a provider: the
+engine attaches to its CDP endpoint and leaves it running.
+
+```ts title="e2e.config.ts"
+web({ connect: { cdpEndpoint: () => process.env.LIGHTPANDA_URL ?? 'ws://127.0.0.1:9222/' } })
+```
+
+```bash
+docker run -d --name lightpanda -p 127.0.0.1:9222:9222 lightpanda/browser:nightly
+```
+
+Every worker then shares that server. One `lightpanda serve` takes 16
+connections by default; raise its `--cdp-max-connections` above `workers`
+when you run more.
+
+## Options
+
+| Option          | Default                         | Meaning |
+| --------------- | ------------------------------- | ------- |
+| `binary`        | `LIGHTPANDA_PATH`, else found   | The binary to start: a path, or a name on `PATH`. |
+| `loadResources` | `[]`                            | Sub-resources the server fetches: `iframe`, `image`, `stylesheet`. See [Fetch more of the page](#fetch-more-of-the-page). |
+| `args`          | `[]`                            | Further `lightpanda serve` flags, after the ones the provider sets. |
+
+The provider leases one server per worker slot for the run; it has no
+`scope: 'attempt'`, since Lightpanda does not expose the default context
+identity a per-attempt lease reattaches by. A server that does not answer
+on its port within ten seconds fails the lease, and so does a binary that
+exits first, with its stderr in the message.
+
+## Fetch more of the page
+
+`lightpanda serve` requests no sub-resources by default: no images, no
+external stylesheets, no iframes. `loadResources` opts into each, as
+`--load-resources` on the server:
+
+```ts
+web({ browser: lightpanda({ loadResources: ['stylesheet', 'iframe'] }) })
+```
+
+Inline styles, `<style>` blocks, and the `hidden` attribute already decide
+visibility; `stylesheet` makes an external file's rules count too, so a
+node a linked stylesheet hides is hidden to a query. `image` fetches image
+headers so `load` and `error` reflect the real status.
+
+## What works
+
+Against the e2e testbed's local suite on a Lightpanda nightly from mid-October
+2026, these pass unchanged:
+
+- `app.open`, `app.back`, and `expect(browser).toHaveURL` and `toHaveTitle`.
+- Every `screen` query (`getByRole`, `getByLabel`, `getByText`,
+  `getByTestId`, filters, `nth`) and the actions on them: `tap`, `fill`,
+  `check`, `select`, `press`, and keyboard input.
+- Polling assertions on text, value, count, and state.
+- `browser.route` mocks and request waits.
+- `browser.setCookies` from a test, after a page is open.
+- `app.screenshot` and the screenshot of a failure. Lightpanda paints a plain
+  render of the DOM, not the page as Chrome would show it.
+- Agent steps: `agent.act`, `agent.assert`, `agent.extract`, and
+  `agent.waitFor` read the screen tree, which Lightpanda provides in full.
+  The testbed's agent suite passes its tree-driven flows (todos, wizard,
+  sign-in, hover, context menu, long press, upload); what fails is drawn on a
+  canvas, dragged, or below the fold. A judgment on pixels sees the plain
+  render, so keep the agent on the tree.
+
+A test that asserts on what the user sees, not where it is drawn, moves
+over as is.
+
+## What does not work
+
+Each of these fails the test with the engine's usual error, not a hang. The
+reasons are Lightpanda's, and its
+[Playwright compatibility issue](https://github.com/lightpanda-io/browser/issues/3076)
+tracks most of them.
+
+| Feature | What happens | Why |
+| ------- | ------------ | --- |
+| [Sessions](/authentication) (`test.setup` with `session.save`, `session:` on a test) | The setup passes and the session is saved, but a test that restores it opens signed out. | Cookies set on a context before its first page exists are dropped. Set them from the test with `browser.setCookies` after `app.open` instead. |
+| [Dialogs](/browser#handle-a-dialog) | `browser.onDialog` runs, then fails the test with `ENGINE_FAILURE`: `Page.handleJavaScriptDialog` reports no dialog. | Lightpanda answers `alert`, `confirm` (`false`), and `prompt` (`null`) itself before a client can. |
+| [Downloads](/browser#download-a-file) | `browser.waitForDownload` times out. | No download events over CDP. |
+| [Iframes](/browser#reach-into-an-iframe) | `frameLocator` finds nothing. | Iframes are not loaded by default. `loadResources: ['iframe']` loads them; queries and fills then work, but a listener in the host page on an element the frame created does not fire. |
+| Drags: `screen.swipe`, `locator.swipeTo`, and `browser.mouse` moves with a button down | `ENGINE_FAILURE` naming `Input.setInterceptDrags`. | Playwright needs that command for a drag and Lightpanda has not implemented it. |
+| `browser.setViewport` | The page measures the new size, but a `resize` listener never runs. | No `resize` event is dispatched. |
+| [Media emulation](/reference/web#media-emulation): `colorScheme`, `reducedMotion`, `browser.emulateMedia` | The page keeps reporting `light` and full motion. | `Emulation.setEmulatedMedia` does not change what `matchMedia` answers. |
+| Scrolling: `scrollIntoView`, `scrollUntilVisible`, and an action on a node "outside of the viewport" | The scroll is a no-op, and an actionability wait can time out. | Without layout there is no scroll position to move. The plain render stacks every block in one column, so more of a page sits below the fold than in Chrome, and nothing below it can be reached. |
+| `<canvas>` content: a pin, keypad, or chart drawn with the 2D context | A screenshot shows no drawing, and the canvas takes no space. The agent's pixel tier (`tap_at`, `type_at`, a vision judgment) has nothing to see. | `getContext('2d')` returns a context that records nothing the painter draws. |
+
+A Lightpanda release that closes one of these makes the row above go away
+with no change on the e2e side; the engine sends the same CDP commands it
+sends Chrome.
+
+## Where it fits
+
+Lightpanda suits a suite that is heavy on the agent's reading of the screen
+and light on geometry: smoke flows, forms, navigation, API-backed pages, and
+`agent.act` steps whose checks are text and state. It runs that suite in a
+fraction of Chrome's time and memory, on a box with no Chrome installed.
+
+Keep a Chromium target for the rest, and select by target when both are in
+one config:
+
+```bash
+e2e run --target lightpanda
+e2e run --target chromium
+```