Helpers — flows & mocks

For the complete documentation index, see llms.txt

View Markdown Open in ChatGPT Open in Claude

Helpers are ordinary JS functions in unotest/e2e/_helpers/. There are three kinds, and keeping them separate keeps scenarios clean.

Flows — replay a UI journey

flow_* functions wrap a repeated user journey: sign-in, checkout, onboarding. Write once, call from any scenario.

function flow_signin(email, password) {
  goto("/login");
  fill(getByLabel("Email"), email);
  fill(getByLabel("Password"), password);
  click(getByRole("button", { name: "Sign in" }));
}

An agent can also replay a flow live (explore_run_flow) to seed state, then record a new test on top of it.

Mocks — seed & reset data

Use the sandbox helpers to put the app into a known state before a test and clean up after. Connection details are pinned in config — a scenario can’t redirect them.

function seed_cart(userId) {
  dbExec("INSERT INTO carts (uid) VALUES ($1)", userId);
  apiCall("POST", "/test/checkout/reset");
}

Helper	Use
`dbQuery` / `dbExec`	parameterized SQL (postgres / mysql / sqlite)
`apiCall`	relative-path HTTP against `apiBaseUrl`
`shell`	run a binary (execFile, no shell interpretation); returns `{stdout, stderr, code}`; cwd is `sandbox.shellCwd` from the config, else the directory the command runs in; a non-zero exit fails the step unless `{allowNonZero: true}`; a configured cwd that does not exist is its own error, not a mystery `ENOENT`

Value helpers — read state

A plain snake_case function may return — a value, a locator, the result of evaluate — and a scenario uses what it returns:

function order_row(marker) {
  return getByRole("row").filter({ hasText: marker });
}

function header_width() {
  return evaluate('(() => document.querySelector("header").getBoundingClientRect().width)()');
}

Only test_* entries may not return (the validator rejects it). A flow_* that returns a value gets lint:flow-returns-value: a flow is an executable journey the agent may replay, so a helper that only reads state belongs under a snake_case name.