Skip to main content
agents in your config is a record of agents by name. default is the one tests run with. Other entries are other brains for the same suite: a model that reads screens more carefully, a playbook for a UX review, a persona who has never seen the app.
e2e.config.ts
An entry takes one of three shapes:
  • An options block. model, context, vision, maxSteps, maxModelCalls, providerOptions. This runs the built-in agent with those settings.
  • createAgent(...). The built-in agent with a system prompt and your own tools.
  • An options block with executor. Any custom executor, composed with the model and budget options.
context is a sentence or two of project vocabulary that reaches every agent.* call. system on createAgent shapes how the agent works. One model serves every call, screenshots included, so it has to accept images. The config reference lists every key.

Pick an agent per run

Without a flag, tests run as default. --agent re-points them:
Several names run every unpinned test once per agent, a whole-suite sweep without touching a file:

Pin an agent in the suite

A test, a describe block, or a single call can name its agent. Innermost wins: a call’s agent beats the test’s, which beats its groups, which beat the run. The test bodies below are abbreviated to show agent selection; replace the placeholder bodies with your app’s checkout and refund steps.
tests/checkout.e2e.ts
--agent never overrides a pin it does not name. A persona stays itself while you benchmark a model across everything that has no opinion. A pin that names nothing in agents fails at collection; a call’s unknown name is INVALID_ARGUMENT. Every agent step in the report records the agent it ran with.

One flow, several personas

A pin can be a list. The test then runs once per agent named, as one result each, in one run:
tests/checkout.e2e.ts
Every result carries the agent it ran as: agent in the report, [admin] after the title in the terminal and in JUnit case names, its own result id, and its own artifact directory. With a list pin, --agent admin narrows the block to the admin alone, while --agent thorough leaves it running as both personas. A serial group runs as one unit per agent, so its members share the group’s pin. A setup test pins at most one agent. A persona that must be signed in pairs its pin with a session. A session is one name per block, so a sweep over signed-in personas is a loop over describe blocks; Signing in shows the setup test and the loop.

Next

Project tools

Give the agent a test API or a device toolkit.

Custom executors

Keep the loop with your own prompt, or replace it.