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().
e2e explore --headed drives the app and reports findings as it goes.
Start an exploration
Name the flow and the user goal, and add limits if necessary:
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'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 goalAn 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:
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'Start signed in
Add --session <name>, the name of a session that a
setup test saves:
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'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.
