skip to content

[ agent view ]

raw .md[ view as human ]

Documentation Index

Fetch the complete documentation index at: https://e2e.com/docs/llms.txt Use this file to discover all available pages before exploring further.

Exploring without a test

Give the agent a goal, not a test file. It plans its steps, operates the app, and reports what it finds.

e2e explore runs the agent against your app with a goal instead of a test file. The agent plans a step, does it, and records findings until the goal is covered or a budget ends, then writes an assessment. It uses the same model, tools, and action rules as agent.act().

<Video>
<video src="/images/explore.mp4" aria-label="e2e explore drives the app in a headed browser and reports findings in the terminal." muted loop playsInline controls />

e2e explore --headed drives the app and reports findings as it goes.

</Video>

Start an exploration

Name the flow and the user goal, and add limits if necessary:

<CodeGroup>
npx e2e explore 'Explore the checkout flow like a first-time buyer and report anything off'
pnpm exec e2e explore 'Explore the checkout flow like a first-time buyer and report anything off'
bunx e2e explore 'Explore the checkout flow like a first-time buyer and report anything off'
</CodeGroup>

A limit can be "stop before placing the order." With no goal, explore uses Explore the app and find bugs. A failed step does not stop the run.

With no e2e.config.ts, explore runs the e2e init wizard first. The exploration starts right after when nothing is left to do by hand. Otherwise init lists the steps left, such as npm install or setting the model key. Without a terminal, as in CI, explore fails with CONFIG_NOT_FOUND.

Read the results

The terminal shows each finding and each finished step as they happen:

 ❯  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

An issue fails the run with exit code 1. A warning does not. The final report puts the most severe issues first. Each finding has the steps to reproduce it and, when possible, a screenshot. Compare each finding with its evidence before you act on it. For the other exit codes, the JSON report, and artifact paths, see the CLI reference.

Check other screen sizes

When the target's engine can resize the viewport (the web engine can), a goal can ask for layouts at other widths:

<CodeGroup>
npx e2e explore 'Check the pricing page at desktop, tablet, and phone widths for broken layouts'
pnpm exec e2e explore 'Check the pricing page at desktop, tablet, and phone widths for broken layouts'
bunx e2e explore 'Check the pricing page at desktop, tablet, and phone widths for broken layouts'
</CodeGroup>

Start signed in

Add --session <name>, the name of a session that a setup test saves:

<CodeGroup>
npx e2e explore --session admin 'Explore the admin settings and find bugs'
pnpm exec e2e explore --session admin 'Explore the admin settings and find bugs'
bunx e2e explore --session admin 'Explore the admin settings and find bugs'
</CodeGroup>

Explore runs only that setup test and restores the session. The explorer knows the app starts signed in and plans no sign-in step.

Screenshots mask the password field. A value the app shows anywhere else reaches the model. See screenshots after a secret fill.

If the run stops too early

A run stops after 8 steps or 10 minutes. To reach further into the flow, raise --max-steps <n> (up to 100) or --timeout <ms> (up to 7200000, 2 hours).

A run with time left after the main flows returns to them with edge-case inputs, combined filters, reloads, and, with more than one account configured and no --session, another account. It finishes early only when nothing new is reachable.

Choose the target and agent

Explore uses the targets, app command, models, and agents from e2e.config.ts. Select them with --target <name> and --agent <name>. Without --target, explore uses the first target.

Explore from code

To start an exploration from your own code, with a config value, cancellation, and progress events, call explore from e2e/runner.

Next

<CardGroup cols={2}>
<Card title="Bug bashes" icon="bug" href="/bug-bash">

Explore a whole app or branch with many explorations, and prove each bug with a test.

</Card>
<Card title="Agents and personas" icon="users" href="/agents">

The agents explore can run as.

</Card>
</CardGroup>