e2e 0.17.0 → 0.18.0

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>

package/docs/debugging.mdx

@@ -1,6 +1,7 @@
 ---
 title: Debugging a run
 description: Read the report, open the evidence, watch the browser, and see what the model was sent.
+icon: "magnifying-glass"
 ---
 
 Start with the failure in the terminal. Every run also writes
@@ -63,7 +64,9 @@ URL: `http://127.0.0.1:3000/todos`
 
 `Look at` points to the failing call. Assertion failures include expected
 and observed values; locator failures include the requested locator and
-nearby matches. Repeated failure details help you compare attempts.
+nearby matches. Repeated failure details help you compare attempts. The
+runner spends at most 5 s capturing the screen and screenshot once per failed
+attempt; an app that does not answer in time gets no screen section.
 
 ## The report
 
@@ -105,9 +108,9 @@ reruns names, and writes its own under `rerun-<n>/`:
   `--trace off` skips the cost for one run, `--trace` records every attempt
   of a CI run.
 - **Downloads** saved through `browser.waitForDownload`, recorded with kind
-  `download`. They are the app's bytes: `redaction: "incomplete"` unless a
-  secret reached the session (filled, or held by the engine for basic auth)
-  and the file is text, which the runner rewrites and marks `complete`.
+  `download`. They are the app's bytes: `redaction: "incomplete"` unless the
+  session knows a secret value and the file is text, which the runner rewrites and
+  marks `complete`.
 - **Videos** and **agent transcripts** when you ask for them; see below.
 
 After a secret fill, no screenshots are taken for the rest of the attempt; see
@@ -196,9 +199,16 @@ stdout | web tests/todos.e2e.ts > adds a todo
 hello from the test
 ```
 
-Nothing is buffered or dropped: every line appears when it is written, in a
-pipe or a CI log as much as in a terminal. The output is not part of the
-report; use `expect` or an artifact for anything a later reader needs.
+Output from outside a test, such as a test file's top level or a reporter,
+prints under `stdout | runner` or `stderr | runner`. Both streams print on
+stdout, in a pipe or a CI log too. Without the `list` reporter, output
+goes to its own stream as written.
+
+Secret values are [redacted](/security#redaction). Output printed while the
+config loads appears once it has loaded, before the run header, and is
+dropped for a warning if the load fails. Every other line appears when it
+is written. The output is not part of the report; use `expect` or an
+artifact for anything a later reader needs.
 
 ## Agent steps
 
@@ -264,13 +274,13 @@ large raw JSON file.
 
 Replayed steps make no model call and leave no AI trace. Add `--no-cache`
 when you need to inspect the whole flow or rule out a stale recording. See
-[Caching agent steps](/cache).
+[Caching](/cache).
 
 ## Common errors
 
 | Code | Usual cause | Fix |
 | --- | --- | --- |
-| `APP_UNREACHABLE` | Nothing answers at `app.url`, or `app.command` never became ready; on a device, the message may name the iOS automation runner instead (busy, wedged, or a snapshot it could not present) | Set `app.command.log` and read it; check the port; raise `app.command.startupTimeout`. For the runner, follow the recovery in the message: `npx agent-device daemon stop`, reboot the simulator (see [Testing iOS and Android](/mobile#troubleshooting)) |
+| `APP_UNREACHABLE` | Nothing answers at `app.url`, or `app.command` never became ready; on a device, the message may name the iOS automation runner instead (busy, wedged, or a snapshot it could not present) | Set `app.command.log` and read it; check the port; raise `app.command.startupTimeout`. For the runner, follow the recovery in the message: `npx agent-device daemon stop`, reboot the simulator (see [Mobile](/mobile#troubleshooting)) |
 | `APP_ALREADY_RUNNING` | Something already serves `app.url` when the runner wanted to start `app.command` | Stop it, or set `reuseExisting: true` for local runs |
 | `LOCATOR_NOT_FOUND` | Wrong role or name, text not exact, element inside an iframe, page not open | Read the markup for the accessible name; try `exact: false`; `browser.frameLocator` for iframes; `--headed` to look |
 | `LOCATOR_AMBIGUOUS` | Two matches: a hidden duplicate, a repeated label | Add `{ name }`, scope under a container, `filter`, `first()`, or `{ visible: true }` |

package/docs/decision-models.mdx

@@ -0,0 +1,142 @@
+---
+title: Decision models
+description: Run bounded actions with a decision model and a small text model instead of a full LLM agent.
+icon: "scale-balanced"
+---
+
+`@e2e-dev/decision` runs `agent.act` and `agent.assert` through a decision
+model instead of an LLM. For each action the decision model answers one
+request: which operation, and which element for each operation that has
+more than one, chosen from what the executor builds out of the latest
+semantic tree. It never generates free text: when the choice is `type`, a
+small language model writes the field value. Both models are
+plain AI SDK models, so any decision model provider that answers `choice`
+questions with probability distributions (Jev) and any language-model
+provider works; the runner still authorizes every dispatched action.
+
+## Install and configure
+
+<CodeGroup>
+```bash npm
+npm install -D @e2e-dev/decision
+```
+
+```bash pnpm
+pnpm add -D @e2e-dev/decision
+```
+
+```bash bun
+bun add -d @e2e-dev/decision
+```
+</CodeGroup>
+
+The decision model answers `choice` questions with probability
+distributions; the text model writes field values. Each installs as its
+own package. Decision models need `ai` 7, version 7.0.128 or later:
+
+<CodeGroup>
+```bash npm
+npm install -D @ai-sdk/typesafe-ai @openrouter/ai-sdk-provider
+```
+
+```bash pnpm
+pnpm add -D @ai-sdk/typesafe-ai @openrouter/ai-sdk-provider
+```
+
+```bash bun
+bun add -d @ai-sdk/typesafe-ai @openrouter/ai-sdk-provider
+```
+</CodeGroup>
+
+```ts title="e2e.config.ts"
+import type { E2EConfig } from 'e2e';
+import { web } from '@e2e-dev/web';
+import { decisionExecutor } from '@e2e-dev/decision';
+import { typeSafeAi } from '@ai-sdk/typesafe-ai';
+import { openrouter } from '@openrouter/ai-sdk-provider';
+
+export default {
+  targets: [{ engine: web(), app: { url: 'http://localhost:3000' } }],
+  agents: {
+    default: {
+      executor: decisionExecutor({
+        model: typeSafeAi.decisionModel('jev-latest'),
+        textModel: openrouter('inception/mercury-2.5'),
+      }),
+    },
+  },
+} satisfies E2EConfig;
+```
+
+`evaluationModel()` instances still work. A model id string or a language
+model in `model` fails config load with `INVALID_CONFIG`.
+
+Tests stay plain natural language, with no params needed:
+
+```ts title="tests/todos.e2e.ts"
+import { test, expect } from 'e2e';
+
+test('adds a todo', async ({ app, screen, agent }) => {
+  await app.open('/todos');
+  await agent.act('Add a todo named Buy coffee, and verify it is listed.');
+  await expect(screen.getByTestId('todo')).toContainText('Buy coffee');
+  await agent.assert('The todo list contains Buy coffee.');
+});
+```
+
+## How text gets typed
+
+The decision model only ever names an element index. When it picks `type`,
+the text model writes the value from the goal, the field's label, and the
+page text, and the executor types exactly that string. Model output never
+becomes a selector, a URL, or a key. When the goal supplies no value,
+nothing is typed and the decision model picks another action. Password
+fields never reach the text model; secrets stay declared handles that only
+`typeSecret` fills.
+
+The text model is also the agent's judgment tier: it is exposed as the
+executor's `model`, so `waitFor` and `extract` use it too. It can come
+from the agents entry's `model` instead. Without either, `type` is never
+offered.
+
+## Finishing a step
+
+When the decision model answers `done` or `failed`, the executor checks
+the claim on a fresh screen with one question: is the step's task complete?
+It sees the step's non-secret params, the actions taken with the non-secret
+values typed, and the page, including the text of named status regions, but
+no model reasoning or secret. A confirmed `done` passes the
+step and a confirmed `failed` fails it with `ACTION_FAILED`. An
+unconfirmed claim goes back to the decision model as history; the second one
+ends the step, as `ACTION_FAILED` when the screen contradicts the goal and
+as `blocked` (`AUTOMATION_UNSUPPORTED`) otherwise.
+
+## Gates
+
+Both gates are off by default: the executor follows the most probable
+choice. Set `minProbability` or `minConfidence` to block weaker actions,
+reject weaker completion checks, and fail weaker assertions as
+inconclusive instead:
+
+```ts title="Executor setup"
+const executor = decisionExecutor({ model, minProbability: 0.9, minConfidence: 0.8 });
+```
+
+Probability and confidence are different provider fields: probability is the
+selected option's share of the answer distribution, confidence is the
+provider's separate statistic. A threshold is a policy choice; measure
+accuracy on your own tests before changing it.
+
+## Limits
+
+- No vision: screenshots never reach the model; canvas-only controls and
+  image-based targets are not implemented.
+- No `navigate`: in-app navigation is a `tap` on a link. URLs belong in
+  test code (`browser.goto`, `app.open`).
+- No multi-select `listbox` in v1.
+- The choice cap is 255 options per question (TypeSafe's limit). Larger
+  screens list viewport nodes first and count the rest as omitted, so the
+  model can scroll; the step never blocks just for being large.
+- Drag, upload, and hover are not offered in v1.
+- `waitFor` and `extract` use the text model through the runner's
+  built-in judgment tier.

package/docs/example-projects.mdx

@@ -0,0 +1,32 @@
+---
+title: Example projects
+description: Run standalone e2e examples with Vite, Next.js, Expo, and SwiftUI.
+icon: "folder-open"
+---
+
+Each example is a standalone greeting app with three locator tests and two
+agent tests. Enter a name, press Greet, and check the result. The projects
+install published e2e packages from npm and work outside this repository.
+
+<CardGroup cols={2}>
+  <Card title="Vite" icon="/images/examples/vite.svg" href="https://github.com/tester-army/e2e/tree/main/examples/with-vite" cta="View example" arrow>
+    React with Vite. Run locator and agent tests in Chromium.
+  </Card>
+  <Card title="Next.js" icon="/images/examples/nextjs.svg" href="https://github.com/tester-army/e2e/tree/main/examples/with-next" cta="View example" arrow>
+    Next.js App Router. The runner starts the app and tests it in Chromium.
+  </Card>
+  <Card title="Expo" icon="/images/integrations/expo.svg" href="https://github.com/tester-army/e2e/tree/main/examples/with-expo" cta="View example" arrow>
+    React Native with Expo. Run the same tests on web, an iOS simulator, or an Android emulator.
+  </Card>
+  <Card title="SwiftUI" icon="/images/examples/swiftui.png" href="https://github.com/tester-army/e2e/tree/main/examples/with-swiftui" cta="View example" arrow>
+    A native iOS app with an Xcode project. Run tests on an iPhone simulator.
+  </Card>
+</CardGroup>
+
+Follow each project's README for installation, builds, and run commands.
+The config and tests live beside the app. The SwiftUI project keeps them
+in its `e2e/` folder.
+
+Locator tests need no model. Set `AI_GATEWAY_API_KEY` to run the agent
+tests; without it, those tests skip. See [Models](/models) for model setup
+and the [Quickstart](/quickstart) to add e2e to your own app.

package/docs/executors.mdx

@@ -1,6 +1,7 @@
 ---
 title: Custom executors
 description: Customize the agent loop or implement your own step executor.
+icon: "microchip"
 ---
 
 Use a custom executor when a `system` prompt and [project tools](/tools) are
@@ -14,6 +15,8 @@ not enough. There are two options:
    `ai` package installed.
 
 Both receive a deadline, redacted observations, and checked action methods.
+For a provider that returns bounded choices instead of generated text, see
+the [Clef and Jev decision executor](/decision-models).
 The runner records their verdicts. Either goes under `executor` in an agents
 entry, beside the options that still apply: `model`, `judge`, `context`, and
 the budgets. An entry with `executor` rejects `system` and `tools`; pass

package/docs/explore.mdx

@@ -1,6 +1,7 @@
 ---
 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.
+icon: "compass"
 ---
 
 Use `e2e explore` to investigate a flow without writing a test. Give the

package/docs/github.mdx

@@ -1,6 +1,7 @@
 ---
 title: Pull request comments
 description: The @e2e-dev/github reporter posts one comment per run from GitHub Actions and keeps it current.
+icon: "code-pull-request"
 ---
 
 `@e2e-dev/github` posts test results as a pull request comment, including
@@ -73,7 +74,7 @@ that path. The checkout root is the nearest directory holding `.git` inside
 
 ## The comment
 
-```markdown
+```markdown expandable
 ### 🔴 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
 

package/docs/index.mdx

@@ -1,6 +1,7 @@
 ---
 title: Introduction
 description: Open source AI testing for web and mobile apps. Spend less time on tests and more time building.
+icon: "house"
 ---
 
 import { VideoCard } from './snippets/video-card.jsx';
@@ -9,9 +10,9 @@ 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](/locators) and
+[locators](/core-concepts#locators) and
 [assertions](/reference/expect#locator-matchers), fully driven by an agent
-from [goals](/goals) in natural language, or a mix of
+from [goals](/core-concepts#goals) in natural language, or a mix of
 both in the same test.
 
 <VideoCard
@@ -49,7 +50,7 @@ you shipped.
 ## 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
+  simulator. The [web engine](/web) 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).
@@ -70,8 +71,11 @@ you shipped.
   <Card title="Quickstart" icon="rocket" href="/quickstart">
     One prompt for your coding agent, or set up by hand.
   </Card>
-  <Card title="Goals" icon="pen-to-square" href="/goals">
-    Write test steps as goals in natural language.
+  <Card title="Example projects" icon="folder-open" href="/example-projects">
+    Run a standalone app with Vite, Next.js, Expo, or SwiftUI.
+  </Card>
+  <Card title="Core concepts" icon="pen-to-square" href="/core-concepts">
+    Goals, assertions, and locators.
   </Card>
   <Card title="Coding agents" icon="robot" href="/coding-agents">
     Let your coding agent write, run, and debug tests.

package/docs/integrations/eas.mdx

@@ -2,6 +2,7 @@
 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.
+icon: "/images/icons/expo.svg"
 ---
 
 `easSimulators()` from `@e2e-dev/eas` is a

package/docs/integrations/index.mdx

@@ -2,6 +2,7 @@
 title: Integrations
 sidebarTitle: Overview
 description: Official integrations with hosted services, one package per service.
+icon: "plug"
 ---
 
 Official integrations connect e2e to hosted services through the engines'

package/docs/integrations/kernel.mdx

@@ -2,6 +2,7 @@
 title: Kernel browsers
 sidebarTitle: Kernel
 description: Run web targets in Kernel's hosted Chromium with the kernel() browser provider from @e2e-dev/kernel.
+icon: "/images/icons/kernel.svg"
 ---
 
 `kernel()` from `@e2e-dev/kernel` is a
@@ -60,7 +61,7 @@ web({
 ```
 
 Each attempt's window then opens maximized, and the page
-[fills it](/viewports#fill-the-window): 1920 by 993 on a 1920 by 1080 screen,
+[fills it](/web#fill-the-window): 1920 by 993 on a 1920 by 1080 screen,
 after the tab strip and address bar. With a fixed web `viewport`, the page is
 emulated at that size inside a smaller window, so Kernel's live view shows it
 cut off or in part of the window.

package/docs/migrate/cypress.mdx

@@ -1,8 +1,31 @@
 ---
 title: From Cypress
 description: Replace Cypress command chains with async tests and keep your data-cy attributes.
+icon: "/images/icons/cypress.svg"
 ---
 
+import { SetupPrompt } from '../snippets/setup-prompt-card.jsx';
+
+export const migrationPrompt = `Migrate this project's Cypress tests to e2e, one spec at a time. Docs: \`https://e2e.tester.army/docs/migrate/cypress.md\`
+
+1. Read the migration guide above. It maps Cypress config, commands, and assertions to e2e.
+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 config and an example test, and installs nothing yet.
+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 \`cypress.config.*\` into the e2e config: \`baseUrl\` and the dev server command become the target's \`app\`, and if the specs select by \`data-cy\`, set \`web({ testIdAttribute: 'data-cy' })\` so \`screen.getByTestId\` reads it. Keep Cypress installed while both suites run.
+6. Install dependencies.
+7. List the Cypress end-to-end specs and ask me which one to move first. Suggest one that breaks often or waits with \`cy.wait(ms)\`. Component tests have no e2e equivalent; leave them in Cypress.
+8. Rewrite that spec as a \`.e2e.ts\` file under \`tests/\` (e2e runs \`tests/**/*.e2e.ts\` by default), with one awaited call per line and no chains. \`cy.contains\` matches a substring and e2e queries match the whole text, so pass \`{ exact: false }\` where the spec relied on a fragment. Replace each \`cy.wait(ms)\` with an assertion on the state the test waits for. Move \`cy.task\`, \`cy.exec\`, and \`cy.request\` into plain Node code, and custom commands into functions or fixtures.
+9. Keep navigation and the final assertions deterministic, with \`app.open()\` and locator assertions. Where a run of scripted interactions breaks often, propose an \`agent.act\` goal for it instead.
+10. Run the new file with \`npx e2e run <file>\` and fix it until it passes. Keep the Cypress spec until I confirm it can go.
+11. Summarize which tests moved, which stayed in Cypress, and why.`;
+
+<SetupPrompt>
+
+<Prompt description={migrationPrompt} children={migrationPrompt} actions={["copy", "cursor"]} />
+
+</SetupPrompt>
+
 e2e tests run in Node. Use `await` for UI actions and call Node functions
 directly for work previously handled by `cy.task`. Both suites can stay in
 the project while you migrate one spec at a time.
@@ -15,7 +38,7 @@ for the agent calls shown below.
 | Cypress | e2e |
 | --- | --- |
 | `baseUrl` | `app: { url }` on the target |
-| `start-server-and-test` | `app: { url, command }`, see [Starting your app](/starting-your-app) |
+| `start-server-and-test` | `app: { url, command }`, see [Starting your app](/web#starting-your-app) |
 | `viewportWidth`, `viewportHeight` | `web({ viewport })` |
 | `data-cy` selectors | `web({ testIdAttribute: 'data-cy' })`, then `screen.getByTestId` |
 | `retries` | `retries` |
@@ -115,8 +138,8 @@ Start with a spec that often breaks and whose fixed `cy.wait` calls can
 become assertions on the condition the test needs.
 
 <CardGroup cols={2}>
-  <Card title="Goals" icon="pen-to-square" href="/goals">
-    Write test steps as goals instead of scripted selectors.
+  <Card title="Core concepts" icon="pen-to-square" href="/core-concepts">
+    Goals, assertions, and locators instead of scripted selectors.
   </Card>
   <Card title="Working with the browser" icon="globe" href="/browser">
     Routes, dialogs, downloads, iframes, and page evaluation.