Skip to main content
e2e explore is a run with no test file. You give the agent a goal, it decides what to exercise one step at a time, and it reports every defect it has evidence of. The run ends with an assessment, a list of findings, and the same .e2e/report.json a test run writes.
Use it before there are tests, to see what the agent can do with your app. Use it on a feature branch, to hunt for regressions a scripted suite would not know to look for. Use it to find out what is worth turning into a test. It runs the same agent agent.act() runs, with the same model, tools, and safety rules, so what it finds is what a test would find.

​
What a run does

  1. Opens the app on the target’s URL, as app.open() does. A device target with no URL is already showing its app.
  2. Plans a step. One model call reads the goal, the steps so far, the findings so far, and the current screen, and answers with the next charter: a title and one concrete instruction. It prefers breadth over depth and follows up on anything odd a previous step reported.
  3. Runs the step as an ordinary agent.act() step. The agent has the whole action grammar, your project tools, and one more: report_finding.
  4. Records findings the moment the agent calls the tool: title, kind, severity 1 to 5, what it expected, what it saw, and how to get there. The current path is included when the engine exposes one. A redacted screenshot is attached when pixels are allowed and the artifact can be saved.
  5. Repeats until the planner decides the goal is covered or a budget ends the run, then asks the model for a closing assessment.
A step that finishes its charter passes. A step the app would not let it complete fails, and the run keeps going. A step that runs out of its own budget mid-charter is a time box, not a failure. Three failed or blocked steps in a row that reported nothing end the run.

​
Budgets

Exploration hits diminishing returns fast, which is why the ceilings are low. A first look at an app fits in four steps; a thorough pass over one flow fits in twelve.

​
The verdict

An issue is a defect a user would hit. A warning is cosmetic and never fails the run. A run that explored nothing is blocked rather than passed, because a zero-coverage pass would say the app is fine when nothing was checked.

​
What you get

.e2e/report.json carries the exploration under run.explore: the goal, the budgets, why the run ended, the assessment, every step, and every finding. A finding with a saved screenshot includes its artifact id. After a secret fill, screenshot evidence is withheld for the rest of the attempt. --reporter, --video, --ai-trace, and --debug work as they do for e2e run. In both commands, --video requires a selected engine that records video; otherwise the run fails with UNSUPPORTED_ARTIFACT.

​
Your config applies

Explore reads e2e.config.ts. The target’s engine, app command, allowed origins, and the agent’s context, vision, and provider options all apply. --agent <name> explores as another configured agent, so a UX-review agent and a functional one can explore the same app in turn. An agent built with createAgent({ tools, system }) lends its tools and guidance to the explorer; a hand-rolled executor has no vocabulary to reuse and is replaced by the built-in agent for the run, with a notice. Configured credentials reach the explorer as step secrets. The planner is told each account’s name and username, never its password. The type_secret tool is offered when credentials are configured and the selected engine declares perform. Each fill still needs the runner’s authorization and an engine that can handle a sensitive fill; unsupported fills can fail when called. There is no separate capability flag that hides the tool for those engines. Without configured credentials or perform, the tool is absent and the explorer is instructed to skip password sign-in. The password never enters a prompt, a transcript, or a finding. With several targets, pass --target; otherwise the first configured target is explored and the CLI says so. The trace cache is off and retries are zero for the run.

​
Writing a good goal

Name the area and the posture. “Explore the checkout flow like a first-time buyer and report anything off” beats “test checkout”: it tells the planner where to start, how deep to go, and what counts. Say what not to touch when it matters (“do not place a real order”). The default goal, Explore the app and find bugs, is a fair first look at a small app.

CLI reference

Every flag of e2e explore.

Agents and personas

The agents explore can run as.