e2e 0.16.0 → 0.18.0

package/docs/browser.mdx

@@ -1,6 +1,7 @@
 ---
 title: Working with the browser
 description: Mock an API, handle a dialog, download a file, reach into an iframe, and pick a browser.
+icon: "window-maximize"
 ---
 
 `@e2e-dev/web` runs tests in Chromium, Firefox, and WebKit. It is built on
@@ -39,7 +40,9 @@ await app.open('/checkout');
 await expect(screen.getByText('$42.00')).toBeVisible();
 ```
 
-Each handler must call exactly one of `fulfill`, `continue`, or `abort`. An
+Each handler must call exactly one of `fulfill`, `continue`, `fallback`, or
+`abort`. The newest route runs first; `continue` sends the request straight to
+the network, while `fallback` passes it to the route registered before. An
 `expect` that fails inside the handler fails the test, at the next step or at
 the end of the test when nothing follows. To inspect a real response, start
 waiting before the action that sends it:
@@ -114,16 +117,35 @@ const flag = await browser.evaluate((name: string) => window.localStorage.getIte
 Use `evaluate` for state that `screen` cannot read. Prefer locators and
 assertions for visible UI so tests depend less on the DOM structure.
 
+## Run a script before the page
+
+An init script runs in every document before the page's own scripts: mock a
+browser API, seed `Math.random`, or set a flag the app reads at boot. For every
+test:
+
+```ts
+web({ initScripts: [{ path: 'tests/init.js' }] })
+```
+
+For one test, before the page opens:
+
+```ts
+await browser.addInitScript((value) => { Math.random = () => value; }, 0.5);
+await app.open('/raffle');
+```
+
+See [init scripts](/reference/web#init-scripts).
+
 ## Cookies
 
 ```ts
 await browser.setCookies([{ url: 'http://localhost:3000', name: 'tz', value: 'UTC' }]);
 ```
 
-A cookie URL that does not parse, or uses `file:`, `data:`, or
-`javascript:`, is `POLICY_DENIED`; a domain cookie is checked as the origin
+A cookie URL that does not parse, or uses a scheme other than `http:` or
+`https:` (`about:blank` included), is `POLICY_DENIED`; a domain cookie is checked as the origin
 it would be sent to. If any entry is refused, no cookies are set. To resize
-the page, see [Testing viewports](/viewports).
+the page, see [Viewports](/web#viewports).
 
 ## Pick a browser
 
@@ -144,10 +166,25 @@ export default {
 } satisfies E2EConfig;
 ```
 
-`npx playwright install webkit --with-deps` provisions the extra browser in
-CI. `connect` attaches to a remote Chromium over CDP instead of launching
+In CI, provision the extra browser with the [install command](/reference/web#installing-browsers):
+
+<CodeGroup>
+```bash npm
+npx @e2e-dev/web install webkit --with-deps
+```
+
+```bash pnpm
+pnpm exec e2e-web install webkit --with-deps
+```
+
+```bash bun
+bunx @e2e-dev/web install webkit --with-deps
+```
+</CodeGroup>
+
+`connect` attaches to a remote Chromium over CDP instead of launching
 one; a [browser provider](#hosted-browsers) does the same and also leases
-and releases the browser. [Testing viewports](/viewports) covers sizes.
+and releases the browser. [Viewports](/web#viewports) covers sizes.
 
 ## Hosted browsers
 
@@ -161,7 +198,7 @@ when the run no longer uses it. The engine knows no vendor: for
 provider, and for any other service a provider is a few dozen lines in your
 project. Add `viewport: null` when
 the service shows the window in a live view: the page then
-[fills the window](/viewports#fill-the-window) instead of a fixed 1280 by
+[fills the window](/web#fill-the-window) instead of a fixed 1280 by
 720 area of it.
 
 ```ts
@@ -237,7 +274,7 @@ The attempt runs in the browser's persistent default context, on the
 browser's own first tab, so the remote must contain only that context, and
 the limits of
 [`connect.reconnectEndpoint`](/reference/web#recovering-a-cdp-transport)
-apply: no `headers`, `basicAuth`, or `userAgent` (each is `INVALID_CONFIG`), no
+apply: no `headers`, `basicAuth`, `userAgent`, `locale`, or `timezoneId` (each is `INVALID_CONFIG`), no
 `app.clearState()` (`UNSUPPORTED_CAPABILITY` naming the scope), and no session
 state capture or restore, so a run whose tests consume a
 [session](/authentication) on the target fails with `COLLECTION_ERROR`
@@ -249,7 +286,7 @@ same browser.
 A provider against a typical session API has three requests: create a
 session, poll it until it exposes a DevTools endpoint, stop it.
 
-```ts title="browser-provider.ts"
+```ts title="browser-provider.ts" expandable
 import type { BrowserProvider } from '@e2e-dev/web';
 
 /**
@@ -434,7 +471,7 @@ root declared in HTML (`<template shadowrootmode="closed">`) is out of reach.
   <Card title="Web engine reference" icon="masks-theater" href="/reference/web">
     Every `browser` method, its timeout, and what it throws.
   </Card>
-  <Card title="Starting your app" icon="play" href="/starting-your-app">
-    Let the runner start the dev server and reach protected previews.
+  <Card title="Web" icon="play" href="/web">
+    Let the runner start the dev server, reach protected previews, and test viewports.
   </Card>
 </CardGroup>

package/docs/bug-bash.mdx

@@ -1,6 +1,7 @@
 ---
 title: Bug bashes
 description: Run many explorations at once, then prove each bug with a failing test before anyone reads about it.
+icon: "bug"
 ---
 
 A bug bash runs several `e2e explore` sessions at once, each on one area
@@ -50,7 +51,7 @@ itself: `npx e2e guide bug-bash`.
   `reuseExisting: true` on the target's `command`, or declare the URL with
   port `0` so each run starts its own copy. `reuseExisting` does not apply
   when `CI` is set; use port `0` there. See
-  [Starting your app](/starting-your-app).
+  [Starting your app](/web#starting-your-app).
 - When the target's `app.command` brings up a stack of its own, such as a
   database from `docker compose` that it removes on exit, start the stack once
   and explore with a config that points at the running app and declares no

package/docs/cache.mdx

@@ -1,6 +1,7 @@
 ---
-title: Caching agent steps
+title: Caching
 description: Replay verified agent actions without model calls, and let the agent take over when the app changes.
+icon: "box-archive"
 ---
 
 The replay cache records the actions in an `agent.act()` step after a later
@@ -45,27 +46,60 @@ bunx e2e run --no-cache
 
 ## How a replay works
 
-1. Check the starting screen: the same route, whatever the record id, the
-   query, or the fragment. Retries always run live.
+1. Check the starting screen: the same route, whatever the record id or the
+   fragment. Retries always run live.
 2. Find each recorded control and repeat its action. The runner matches
    controls by their role, name, test id, and surrounding context. It waits
    for missing controls and stops if a match is ambiguous. A control with no
-   name is found by its place among the unnamed controls of its kind.
-3. Check the final path and controls that appeared during the original step.
-   Text that changes with the data, a count, a date, an id, is not used.
+   name is found by its place among the unnamed controls of its kind inside
+   the same named row, list item, or group; with no such container to tell
+   it from its twins, the agent takes the step.
+3. Check the final route and what the original step changed: the controls
+   that appeared, with their checked, selected, expanded, or pressed state,
+   and the ones that went away. At least one of those changes must happen
+   during the replay, counted from the first screen the replay saw on the
+   route it ended on, so an outcome already on screen before the actions
+   that should produce it proves nothing; a step whose last action moved to
+   another route has that move as its evidence. An alert the replay raised
+   that the recording never saw stops it too. Text that reads differently on
+   every run, a date, a time, a duration, an id, is not used, except in an
+   alert, where it is read as a placeholder.
 4. Finish without a model call, or let the agent continue with a record of
    what ran and why replay stopped.
 
+A route is the origin, the path, and the query. Ids, tokens, timestamps,
+and cache busters in either the path or the query are read as an id
+placeholder, so `/orders/42?t=1727780000` and `/orders/7?t=1727780999` are
+one route. Every other query value is part of it: `?mode=safe` and
+`?mode=unsafe`, or `/companies` and `/companies?tab=notes`, are different
+screens, and so is a tracking parameter that was not there when the step
+was recorded. Two routes that differ in one word, `/products/summer-sneaker`
+and `/products/winter-boot`, are different screens too, even when they look
+alike. A location on the app's own origin is compared by its path, so a
+recording follows the app to a preview deployment that shares its
+`app.identity`; a page on any other origin is another route.
+
+A count that names what it counts, `3 records imported` or `Showing 1 to 9
+of 9 results`, is part of the effect when the step made it appear on the
+screen it acted on, and must read the same on replay. A count that was
+already on screen and only moved, `41 items` to `42 items`, or one on a
+screen the step navigated to, is not used, since leftover data from earlier
+runs moves it again. A bare number such as a badge is never used.
+
 Typed values replay as recorded, even when an earlier run left the same
 value on screen. Secret fills resolve the current value by name and run
 through authorization again.
 
 ## What must match
 
-A cache entry belongs to a specific test, target, instruction, and set of
-params. Renaming the test or target, changing the instruction or an ordinary
-param, or upgrading the engine's major or minor version causes a miss.
-Changing the model does not.
+A cache entry belongs to a specific test, target, instruction, set of
+params, and agent. Renaming the test or target, changing the instruction or
+an ordinary param, running with another configured agent, changing the
+agent's `context` or the test's `agentContext`, or upgrading the engine's
+major or minor version causes a miss. A test that runs once per agent
+(`agent: ['buyer', 'admin']`) records once per agent. Changing the model
+does not. The agent context enters the key as a hash of its redacted text,
+so a secret in it contributes only its name.
 
 A timestamp or a fresh email address would cause a miss on every run. Wrap
 values like these in `unique()` so the runner substitutes the current value
@@ -96,7 +130,9 @@ identity. On devices, replay uses the
 
 In `read-write` mode, the runner saves a recording at the end of the
 attempt when a later verification step passed. A step that took no action
-records nothing.
+records nothing, and neither does one that changed nothing the replay could
+check: no control appeared, went away, or changed state, and the route
+stayed the same.
 
 | Counts as verification | Does not count |
 | --- | --- |
@@ -145,14 +181,14 @@ such as an `afterEach` assertion.
 | `retry` | Retries never replay. | Nothing. |
 | `invalid-entry` | The file is unreadable, over 1 MiB, or from another schema version. | `npx e2e cache clear`. |
 | `truncated` | The recording hit a limit, see [below](#limits-and-gaps). | Split the step, or pass the secret as a `Secret`. |
-| `wrong-context` | The app was on another screen than when the step was recorded: a different route, not a different record, query, or fragment. | Open the same screen before the step. |
-| `target-not-found` | A recorded control did not appear within 15 seconds. | The UI changed. The next passing run re-records. |
+| `wrong-context` | The app was on another screen than when the step was recorded: a different origin, path, or query, not a different record id or fragment. | Open the same screen before the step. |
+| `target-not-found` | A recorded control did not appear within 15 seconds, or it has no name and no named container to tell it from its twins. | The UI changed: the next passing run re-records. For an unnamed control, give it a label or put it in a named row or group. |
 | `target-ambiguous` | The number of matching controls changed. | Give repeated controls distinct names or use unique test data. |
 | `gap` | An action cannot be replayed, see [below](#limits-and-gaps). | The agent continues this part live. Put stable values in `params`. |
 | `action-failed` | The app rejected a replayed action. | Check the app. |
 | `action-uncertain` | A replayed action failed with an unknown commit state. The agent is told to check before acting again. | Check the app. |
 | `viewport-changed` | A bare-point tap or hover was recorded on a viewport of another size. | Keep the viewport fixed. |
-| `end-mismatch` | Every action ran, but the recorded path or a control that should have appeared did not come back. | Leftover data from an earlier run, a banner that comes and goes, or a regression. |
+| `end-mismatch` | Every action ran, but the recorded route, a control that should have appeared or gone away, or a recorded state did not come back; the outcome was already on screen before the replay; or the replay raised an alert the recording never saw. | Leftover data from an earlier run, a banner that comes and goes, or a regression. |
 
 A stop before any action ran is a miss. After replay starts, it is a
 hand-off. Unique test data and cleanup in `afterEach` help avoid stale
@@ -176,8 +212,9 @@ the instruction or `params`, or ones the agent composed itself, replay.
 
 Each entry is a JSON file under `.e2e/cache/`, named by a hash of its key.
 It contains actions, target descriptions, typed text, a step summary, and
-checks for the final state. Those checks include the path and up to eight
-controls that appeared during the step.
+checks for the final state. Those checks include the route, up to eight
+controls that appeared during the step, alerts and status messages first,
+and up to eight that went away.
 
 Entries contain no prompts, conversations, screenshots, observed trees, or
 secret values. A secret fill stores only the secret's name. Other typed
@@ -220,12 +257,16 @@ Local runs leave a committed directory clean unless something changed. A
 replayed step never rewrites its entry, and a live re-recording with the same
 actions, paths, and anchors is not written: the summary, the measured end
 wait, and the rule that flagged a typed run-time value differ between two
-live runs of the same flow and do not count. A file changes when:
+live runs of the same flow and do not count. Upgrading `e2e` to a version
+that changes how entries are matched re-keys every entry, so the first run
+after it records them again. A file changes when:
 
 - a step records for the first time,
 - the agent finishes a step after a hand-off, re-recording what it saw,
 - a step fails after replaying, or ends in an `end-mismatch` the agent had
   to repair, which deletes the entry,
+- a step with an entry passes without leaving anything to record, which
+  deletes the entry,
 - no verification step confirmed the entry by the end of the attempt, which
   deletes it.
 
@@ -257,8 +298,14 @@ CI=1 bunx e2e run --strict-cache
 The reasons that fail are the ones that mean the app or the entry changed:
 `invalid-entry`, `wrong-context`, `target-not-found`, `target-ambiguous`,
 `viewport-changed`, `action-failed`, `action-uncertain`, and `end-mismatch`.
-A step with no recording (`no-entry`), a retry, a `gap`, and a `truncated`
-recording still run live. `REPLAY_STALE` exits 2 and is not retried, since a
+A `no-entry` miss fails too when the cache directory holds a recording of the
+same step under another key, from before an `e2e` or engine upgrade or a
+change to the project id, the app's identity, or the agent's context. The
+message names that file; delete it once nothing replays it. A custom
+`cache.store` is not checked this way. Entries recorded before this check
+existed are covered once a `read-write` run replays or re-records them. A
+step never recorded (a new or edited instruction or params), a retry, a
+`gap`, and a `truncated` recording still run live. `REPLAY_STALE` exits 2 and is not retried, since a
 retry never replays and would pass live. The entry stays where it is, even
 in `read-write` mode, so every strict run fails on it until it is re-recorded:
 run the test in `read-write` mode without the flag, and with `cache.strict`

package/docs/ci.mdx

@@ -1,13 +1,14 @@
 ---
 title: Continuous integration
 description: Run tests on pull requests, upload reports, and configure model credentials in CI.
+icon: "rotate"
 ---
 
 Run deterministic and agent tests in the same CI job. This workflow assumes
-your config includes a [command](/starting-your-app) to start the app and
+your config includes a [command](/web#starting-your-app) to start the app and
 uses AI Gateway for model calls:
 
-```yaml title=".github/workflows/e2e.yml"
+```yaml title=".github/workflows/e2e.yml" expandable
 name: e2e
 
 on:
@@ -35,7 +36,7 @@ jobs:
       - run: pnpm install --frozen-lockfile
 
       - name: Install browsers
-        run: npx playwright install chromium --with-deps
+        run: pnpm exec e2e-web install chromium --with-deps
 
       - name: Run e2e
         run: npx e2e run --reporter list,junit
@@ -66,7 +67,9 @@ jobs:
 ```
 
 The workflow pins actions to commit SHAs and installs dependencies from the
-lockfile. `npx e2e` runs the installed version.
+lockfile. `npx e2e` runs the installed version. The
+[install command](/reference/web#installing-browsers) downloads the browsers
+for the Playwright version the engine pins, with their system libraries.
 
 Artifacts upload on every run that is not cancelled, so a test that failed
 and then passed on retry still has its evidence.
@@ -139,10 +142,12 @@ implemented yet.
 
 `--last-failed` runs only the tests the previous run did not pass, read from
 `report.json` in the [`output`](/reference/config#output) directory (`.e2e`
-by default). The rerun empties `artifacts/` there when it starts, so
-upload the first run's artifacts before rerunning in the same job if you want
-both. The [CLI reference](/reference/cli#flags) lists what counts as not
-passed. Locally it is the loop after a red run:
+by default). The rerun keeps the artifacts the first run's report names and
+writes its own under `artifacts/rerun-1/`, so one upload after both steps
+holds the evidence of each. A test another filter keeps out of the rerun
+stays owed: the next `--last-failed` runs it. The
+[CLI reference](/reference/cli#flags) lists what counts as not passed.
+Locally it is the loop after a red run:
 
 <CodeGroup>
 ```bash npm
@@ -193,7 +198,7 @@ flaky, so you can identify flows that need investigation.
 `--max-failures <n>` stops the run once that many tests have failed, so a
 broken deploy does not spend a model call on every remaining agent step. The
 tests not started are skipped with cause `failure-limit`, the ones running
-end as `interrupted`, and the job exits 1.
+end as `interrupted`, counted apart from the failures, and the job exits 1.
 
 ## Exit codes
 

package/docs/coding-agents.mdx

@@ -1,6 +1,7 @@
 ---
 title: Coding agents
 description: Give a coding agent the skill, a live app session, and reports it can use to write and debug tests.
+icon: "robot"
 ---
 
 `e2e init` installs a skill for writing and running tests, plus MCP
@@ -168,7 +169,7 @@ model call in the flow.
 Do not edit recordings by hand. A failed read-write run removes implicated
 entries so a later verified run can replace them. A failure where no model
 answered implicates nothing and removes none. See
-[Caching agent steps](/cache).
+[Caching](/cache).
 
 <CardGroup cols={2}>
   <Card title="CLI reference" icon="terminal" href="/reference/cli">

package/docs/core-concepts.mdx

@@ -0,0 +1,208 @@
+---
+title: Core concepts
+description: Goals, assertions, and locators, and how to structure and run tests with them.
+icon: "lightbulb"
+---
+
+A test has three types of step:
+
+| Step | API | Model call |
+| --- | --- | --- |
+| [Goal](#goals) | `agent.act` | Yes, unless the [cache](/cache) replays it |
+| [Assertion](#assertions) | `agent.assert`, `agent.waitFor`, `agent.extract` | Yes |
+| [Locator](#locators) | `screen` and `expect` | No |
+
+The model column is for the built-in agent. A
+[custom executor](/executors) can run `act` and `assert` without a model.
+
+You can use all three in one test:
+
+```ts title="tests/todos.e2e.ts"
+import { test, expect } from 'e2e';
+
+test('todos survive a filter round-trip', async ({ app, agent, screen }) => {
+  await app.open('/todos');
+
+  await agent.act('add todos "Buy milk" and "Walk the dog", complete the first');
+  await agent.assert('only one todo remains open');
+
+  await screen.getByRole('tab', 'Done').tap();
+  await expect(screen.getByTestId('todo')).toHaveCount(1);
+});
+```
+
+Await each agent call, screen call, and `expect.poll`. If a test returns
+while a step still runs, the test fails with `STEP_NOT_AWAITED`.
+
+## Goals
+
+`agent.act` takes one goal. The agent selects and does the actions. It
+returns when the goal is complete. It throws when the goal fails.
+
+```ts
+await agent.act('complete checkout with the test card');
+await agent.act('invite {email} as an editor', { params: { email: 'ada@example.test' } });
+```
+
+- Write one goal for each call. The agent controls the flow in a goal. You
+  control the order of the goals.
+- Use the words that the screen shows.
+- Give test data in `params`. For a password, give a `Secret`. The model
+  does not see a secret. See [Signing in](/authentication).
+- For a value that changes on each run, use `unique()`. Then the
+  [replay cache](/cache#what-must-match) can replay the step:
+
+```ts
+import { unique } from 'e2e';
+
+const email = `ada+${Date.now()}@example.test`;
+await agent.act('sign up with email {email}', { params: { email: unique(email) } });
+```
+
+If a goal fails, read the report. Then make the instruction more specific.
+Put words that many goals use in the agent's `context`; see
+[Agents and personas](/agents). For verdicts and exit codes, see
+[How agent steps work](/agent-steps#how-a-step-ends).
+
+`act` gets screenshots when it needs them. On some engines, it can tap and
+type at points in the image.
+
+## Assertions
+
+An assertion examines the screen. The judging model sees the statement, the
+current screen, and the agent's context. It does not see the earlier steps
+or the summaries of `act`.
+
+- `agent.assert` examines the screen now. A false statement fails with
+  `ASSERTION_FAILED`. Not sufficient evidence fails with
+  `ASSERTION_INCONCLUSIVE`.
+- `agent.waitFor` waits until a condition is true. It calls the model only
+  when the screen changes.
+- `agent.extract` reads data from the screen into a
+  [Standard Schema](https://standardschema.dev) type, for example Zod.
+
+```ts
+import { expect } from 'e2e';
+import { z } from 'zod';
+
+await agent.assert('the dashboard shows a trial badge');
+await agent.waitFor('a download link appears', { timeout: 120_000 });
+
+const data = await agent.extract('every todo title', {
+  schema: z.object({ titles: z.array(z.string()) }),
+});
+expect(data.titles).toContain('Buy milk');
+```
+
+For text that the model wrote, examine the meaning, not the full sentence.
+When the exact text is important, use a [locator](#locators).
+
+### Judging pixels
+
+Judgments read a redacted text snapshot of the screen. For a visual check,
+such as a chart or a layout, add `vision: true`. To judge only the
+screenshot, use `vision: 'only'`.
+
+```ts
+await agent.assert('the chart trends upward', { vision: true });
+```
+
+Images add input tokens. After a secret fill, the attempt sends no more
+screenshots. See the [agent reference](/reference/agent#vision).
+
+## Locators
+
+A locator finds a known control. Locator steps do not call a model. Use them
+when you know the exact action or the exact value.
+
+```ts
+// Role and name first, label second, test ID last.
+await screen.getByRole('button', 'Sign in').tap();
+await screen.getByLabel('Email').fill('ada@example.test');
+
+// Scope into a row.
+const row = screen.getByRole('listitem').filter({ hasText: 'Design review' });
+await row.getByRole('button', 'Archive').tap();
+
+// Gestures and coordinates.
+await screen.swipe({ direction: 'up' });
+await screen.getByRole('image', 'Seat map').tap({ position: { x: 120, y: 48 } });
+
+// Assertions retry until they pass or time out.
+await expect(screen.getByRole('status')).toHaveText('2 remaining');
+```
+
+- An action, a read, or a single-node assertion fails when its query finds
+  more than one node. Use `.filter()`, `.first()`, or `.nth()` to find one
+  node.
+- A direct read, such as `textContent()`, does not retry.
+- Put an `expect` after an `agent.act` goal. It examines the exact result.
+  The [replay cache](/cache) records a goal only after a later check passes.
+
+See the [screen reference](/reference/screen) and the
+[expect reference](/reference/expect#locator-matchers). For routes, cookies,
+dialogs, and downloads, see [Working with the browser](/browser).
+
+## Structure
+
+```ts
+import { beforeEach, describe, test } from 'e2e';
+
+describe('billing', { tags: ['billing'] }, () => {
+  beforeEach(async ({ app }) => { await app.open('/billing'); });
+
+  test('upgrades', { retries: 2, timeout: 60_000 }, async ({ agent }) => {
+    await agent.act('upgrade to Pro');
+  });
+});
+
+test('needs two organizations', async ({ app }) => {
+  test.skip((await countOrganizations()) < 2, 'nothing to switch to');
+  await app.open('/organizations');
+});
+```
+
+- Each test runs in its own attempt. Prepare its data in fixtures or hooks.
+- `test.skip(condition, reason)` stops the test when the condition is true.
+  The report shows the test as `skipped`.
+- For a flow across many tests, set `{ serial: true }` on the group. The
+  tests run in sequence on one worker, and retry together.
+- For setup and cleanup, use `test.extend`. See
+  [Your own fixtures](/reference/test#your-own-fixtures).
+- Import `test` from `@e2e-dev/web` or `@e2e-dev/mobile` to have the
+  `browser` or `device` fixture typed.
+
+The [test reference](/reference/test) shows all options.
+
+## Run one test
+
+<CodeGroup>
+```bash npm
+npx e2e run tests/signup.e2e.ts:12   # the test at line 12
+npx e2e run --grep checkout          # tests with a matching title
+npx e2e run --target web             # one target
+```
+
+```bash pnpm
+pnpm exec e2e run tests/signup.e2e.ts:12   # the test at line 12
+pnpm exec e2e run --grep checkout          # tests with a matching title
+pnpm exec e2e run --target web             # one target
+```
+
+```bash bun
+bunx e2e run tests/signup.e2e.ts:12   # the test at line 12
+bunx e2e run --grep checkout          # tests with a matching title
+bunx e2e run --target web             # one target
+```
+</CodeGroup>
+
+The [CLI reference](/reference/cli#e2e-run) shows all flags.
+
+<CardGroup cols={2}>
+  <Card title="Caching" icon="box-archive" href="/cache">
+    Replay passed goals with no model calls.
+  </Card>
+  <Card title="How agent steps work" icon="list-check" href="/agent-steps">
+    Verdicts, exit codes, and what the model sees.
+  </Card>
+</CardGroup>