A journey is a short Playwright script that does what a visitor does: open the home page, search, open a product, add it to the cart. Load tests, monitors and accessibility checks can run a journey where plain link-following would never get, such as a cart or a signed-in page. The examples use the made-up site example.com, and the values in them are invented to show the shape of an answer.

What a journey script can do

Your agent writes the script. These are the rules it works within.

  • The script is one JavaScript module that exports a function. It gets page (the Playwright page), step, user and base (the start address’s origin).
  • step(name, fn) is a named, timed step. Reports show each step’s time and failures. A step times out after 60 seconds, and a journey has at most 50 step names.
  • user.think(min, max) waits like a person would, in seconds.
  • pick, chance, between and explore make random choices, so users do not all click the same product.
  • Each round is a new visitor: cookies are cleared before it. A journey that signs in exports a setup that signs in once per user, and then the user stays signed in.
  • Not available: other domains, new tabs and popups, downloads, file uploads, request interception, and importing modules or files.
  • A script can be up to 100 KB. Scripts are not secret, so passwords never go in the script. They go in test accounts.
export default async ({ page, user, step, base }) => {
  await step('Home', async () => {
    await page.goto(base + '/');
  });
  await user.think(1, 3);
  await step('Search', async () => {
    await page.fill('input[name=q]', 'shoes');
    await page.press('input[name=q]', 'Enter');
    await page.waitForLoadState('load');
  });
};

create_journey

Saves a new journey. An agent writes one when the flows that matter on your site are not plain pages: search, add to cart, checkout without paying, signing up.

  • Inputs: name (up to 80 characters, unique in your organization), start_url (the page the journey starts from; its domain is the site that gets tested) and script are required. accounts names a set of test accounts the journey signs in with.
  • Returns: the journey: its journey_id, name, start address, version, domain, whether the domain is verified, the script’s size and what to do next.
  • Cost and effect: free. It stores the journey and sends no traffic. An organization can have at most 50 journeys. The next step is always dry_run_journey.

Example

“Write a journey that searches for shoes and adds the first result to the cart.”

{
  "journey_id": "44444444-5555-4666-8777-888888888888",
  "name": "search and add to cart",
  "start_url": "https://example.com/",
  "version": 1,
  "domain": "example.com",
  "domain_verified": true,
  "next": "Call dry_run_journey to check every step in one browser."
}

update_journey

Changes a journey. Only the values you give change. An agent uses it to fix a step that failed in a dry run, or to keep the script working after the site has changed.

  • Inputs: journey_id is required. Then any of name, start_url, script and accounts. An empty accounts value stops the journey from signing in.
  • Returns: the journey after the change.
  • Cost and effect: free. A new script gets a new version number, and every run records which version it ran.

Example

“The search field has a new name. Fix the journey.”

{
  "journey_id": "44444444-5555-4666-8777-888888888888",
  "name": "search and add to cart",
  "version": 2,
  "next": "Call dry_run_journey to check every step in one browser."
}

get_journey

Reads one journey with its script. An agent calls it before changing a journey someone else wrote, or to see how its latest runs went.

  • Inputs: journey_id.
  • Returns: the journey, its script, and recent_runs: the five latest dry runs and load tests, with the version each ran and how it went.
  • Cost and effect: free. It only reads.

Example

“Show me what the cart journey does.”

{
  "journey_id": "44444444-5555-4666-8777-888888888888",
  "name": "search and add to cart",
  "version": 2,
  "script": "export default async ({ page, user, step, base }) => { ... }",
  "recent_runs": [
    { "run_id": "55555555-6666-4777-8888-999999999999", "kind": "dry_run", "version": 2, "passed": true }
  ]
}

list_journeys

Lists your organization’s journeys without their scripts. An agent calls it to find a journey’s id, or to see whether a journey for a flow already exists before writing a new one.

  • Inputs: url, to list only one site’s journeys. It can be left out.
  • Returns: journeys, each with its id, name, start address, version, test account set and latest dry run, and limit, the most journeys an organization can have.
  • Cost and effect: free. It only reads.

Example

“Which journeys do we have for example.com?”

{
  "journeys": [
    {
      "journey_id": "44444444-5555-4666-8777-888888888888",
      "name": "search and add to cart",
      "start_url": "https://example.com/",
      "version": 2,
      "last_dry_run": { "version": 2, "passed": true }
    }
  ],
  "limit": 50
}

delete_journey

Deletes a journey. An agent uses it when a flow no longer exists on the site, or to make room for a new journey.

  • Inputs: journey_id.
  • Returns: the id of the deleted journey.
  • Cost and effect: free. Runs that used the journey keep their results.

Example

“The old checkout is gone. Delete its journey.”

{ "deleted": "44444444-5555-4666-8777-888888888888", "note": "Runs of this journey keep their results." }

dry_run_journey

Runs a journey once, in one real browser, to check that every step works. An agent calls it after every create_journey and update_journey, and repeats until all steps pass. Only then is the journey worth a load test or a monitor.

  • Inputs: journey_id is required. seed repeats the random choices of an earlier run, which helps when a failure depends on which product was picked.
  • Returns: a run_id at once. The agent follows the run with get_run_status and reads it with get_run_result. The result says whether the journey passed, lists each step with its time, and for a failed step gives the error and a screenshot.
  • Cost and effect: free, up to 30 dry runs per organization a day. It takes at most 3 minutes and sends a little real traffic. The domain does not need to be verified.

Example

“Try the journey once and tell me if it works.”

The result of a dry run in which the second step fails:

{
  "run_id": "55555555-6666-4777-8888-999999999999",
  "kind": "dry_run",
  "finished": true,
  "passed": false,
  "summary": "Step \"Search\" failed: ...",
  "steps": [
    { "name": "Home", "ms": 640, "ok": true },
    { "name": "Search", "ms": 60000, "ok": false, "url": "https://example.com/", "screenshot_url": "https://..." }
  ],
  "next": "Fix the script with update_journey, then dry_run_journey again."
}

set_test_accounts

Saves a named set of test logins for a site, for journeys that sign in. An agent uses it when the flows that matter happen signed in. If it can create users on your site it creates them itself. Otherwise it tells you exactly how many accounts to create.

  • Inputs: url (the site), name (letters, digits, _ or -) and accounts are required. A set has 1 to 1,000 accounts, each with a username, a password and optional extra values such as a customer number. assign is unique (every user of a test gets its own account, the default) or shared (accounts are handed out in turn, for sites that let one account sign in many times at once).
  • Returns: the set’s name, site, number of accounts, masked usernames, the journeys that use it and the date after which it is deleted if unused.
  • Cost and effect: free. The accounts are stored encrypted and can only be written: passwords are never shown again, to you or to an agent. Saving a set under an existing name replaces all its accounts. A set that no test has used for 90 days is deleted. Use accounts made for testing, never real customers’ accounts.

Example

“Here are 50 test users for the shop. Save them as customers.”

{
  "name": "customers",
  "domain": "example.com",
  "accounts": 50,
  "assign": "unique",
  "used_by_journeys": ["sign in and reorder"]
}

list_test_accounts

Lists the sets of test accounts your organization has stored. An agent calls it to check that a set exists and has enough accounts for the users of a test.

  • Inputs: url, to list only one site’s sets. It can be left out.
  • Returns: account_sets, each with its name, site, number of accounts, masked usernames, how accounts are assigned and when it was last used. Never passwords.
  • Cost and effect: free. It only reads.

Example

“Do we have enough test accounts for 100 signed-in users?”

{
  "account_sets": [
    { "name": "customers", "domain": "example.com", "accounts": 50, "assign": "unique", "last_used_at": "2026-11-10T09:12:00Z" }
  ],
  "limit": 20
}

delete_test_accounts

Deletes a set of test accounts. An agent uses it when the accounts have been removed from the site or are no longer needed.

  • Inputs: url and name.
  • Returns: the name of the deleted set, and a note that names the journeys still pointing at it.
  • Cost and effect: free. Journeys that sign in with the set cannot run until a set with that name is saved again.

Example

“We removed the test users from the shop. Delete the saved set too.”

{
  "deleted": "customers",
  "note": "Journeys that still name it can't run until they get accounts again: sign in and reorder."
}