Files
liqa/client/src/components/modals/code-help.md
T
ars9 daecf3d539
CI / changes (pull_request) Successful in 7s
CI / version (pull_request) Skipped
CI / server (pull_request) Skipped
CI / client (pull_request) Successful in 1m13s
CI / image (pull_request) Skipped
feat(client): add code reference modal to step and snippet editors
- a (?) button next to the Code label on the step and snippet
  create/edit pages opens a reference of the script runtime: globals,
  every context member with examples, and pitfalls such as awaiting
  getStepOutput and assert
- the reference lives in components/modals/code-help.md and is
  rendered as markdown
- Modal takes size="lg" for document-like content; the dialog is
  capped to the viewport and its body scrolls, focusable when lg so
  the keyboard can scroll it
- docs/scenario.md notes that getStepOutput is async and points to
  the in-app reference to keep in sync
2026-10-01 14:45:03 +03:00

7.9 KiB

Step code and snippet code are the body of an async function. Use await freely; whatever you return becomes the step (or snippet) output.

async (context) => {
  // your code here
}

All steps of a run share one browser, one browser context and one page, so state carries over from step to step: the current URL, cookies, local storage, open dialogs.

A step passes when its code returns, and fails when it throws or exceeds its timeout. When a step fails, the remaining steps are cancelled, and a screenshot and the page HTML are saved to the run's files.

Globals

Name Description
context The run context, described below.
expect Playwright's expect, with auto-retrying web assertions.
console Writes to the run log: log/info → log, plus warn, error and debug.
args Snippets only. The extra arguments passed to context.runSnippet(name, ...args).

Code runs in the server process with Node.js. It is trusted code, not sandboxed.

Browser

context.page

The Playwright Page of the run.

await context.page.goto(context.getEnv("base_url"));
await context.page.getByRole("button", { name: "Sign in" }).click();
await expect(context.page.locator("h1")).toHaveText("Dashboard");

context.browser

The Playwright BrowserContext the page belongs to. Use it for cookies, storage state, extra pages and HTTP requests that share the browser's cookies.

const cookies = await context.browser.cookies();
const res = await context.browser.request.get(context.getEnv("api_url") + "/me");

context.dumpDom(selector?) → Promise<DomNode>

Returns a simplified tree of the live DOM, starting at selector (default "body"). Decorative and layout elements are filtered out. The tree keeps landmarks, interactive elements, and elements with role, data-testid, data-qa, data-action or data-element-id. Each node has tag and children, plus role, testid, id, name, type, text, href, checked, disabled, etc. when they are present. This is useful for finding selectors without a screenshot.

If nothing matches selector, it returns a node with tag: "ERROR" instead of throwing.

context.log("Login form:", await context.dumpDom("form"));

Environment

context.env

A copy of the selected environment's key/value map, {} when there is none. A missing key reads as undefined.

context.getEnv(key) → string

Returns the environment value for key, and throws if it is not defined. Prefer it over context.env[key] for required settings: the step then fails with a clear message.

const baseUrl = context.getEnv("base_url");
const locale = context.env.locale ?? "en";

Credentials

context.getCredential(alias) → unknown

Returns the payload of the credential assigned to this scenario under alias (see Credentials on the scenario page). JSON data is returned parsed, anything else as a string. Throws if no credential has that alias.

const { username, password } = context.getCredential("admin");
await context.page.getByLabel("Username").fill(username);
await context.page.getByLabel("Password").fill(password);

Step outputs

context.getStepOutput(order) → Promise<unknown>

Returns the output (the return value) of another step in the same run. It is async, so await it.

  • A positive order is absolute: 1 is the first step.
  • A negative order is relative: -1 is the previous step.

Returns null if that step does not exist, has not run, or returned nothing. A step's output is stored as JSON, so only JSON-serializable values come back as they were returned (no functions, Date becomes a string, Playwright objects are not usable).

// step 2
return { orderId: await context.page.locator("#order-id").textContent() };

// step 3
const { orderId } = await context.getStepOutput(-1);

Logging

context.log(...args), context.warn(...args), context.error(...args), context.debug(...args)

Write an entry with that level to the run log. console.* does the same. Strings, numbers and booleans are joined with spaces into the message. Objects and arrays are kept separate as structured data, shown pretty-printed under the message: one object is stored as is, several are stored as an array.

context.log("Created user", user.id, user); // message "Created user 42", data = user

Every entry is tagged with where it came from: step:<N>, or snippet:<alias> while a snippet runs.

Assertions

context.assert(fn, description) → Promise<void>

Runs fn (sync or async) and requires it to return exactly true.

  • On success, it logs description (tagged assertion:pass).
  • If fn returns anything else or throws, it logs Assertion failed: <description> as an error (tagged assertion:fail) and throws, which fails the step.

Await it, or a failure will not stop the step.

await context.assert(
  async () => (await context.page.locator(".cart-item").count()) === 3,
  "Cart contains 3 items",
);

Use expect instead for assertions that wait and retry until the page matches, e.g. await expect(locator).toBeVisible().

Snippets

context.runSnippet(name, ...args) → Promise<unknown>

Runs a stored snippet with the same context (same page, environment and credentials) and returns the snippet's return value. Extra arguments are available inside the snippet as args.

  • name is the snippet alias, which runs its latest version.
  • alias@<version> (e.g. login@3) pins a specific version.

Start, finish and failure are logged. If the snippet throws, the error propagates and fails the calling step unless you catch it. Snippets can call other snippets.

// step code
const user = await context.runSnippet("login", "admin", { remember: true });

// snippet "login"
const [alias, opts] = args;
const { username, password } = context.getCredential(alias);
// ...
return { username };

Files

context.getScenarioFiles(opts?) → Promise<{ items, total }>

Lists the files uploaded to this scenario (see Files on the scenario page). opts takes limit and offset for paging. Each item has id, name, mimeType, size, sha256 and path, the absolute path on the server's disk, which you can pass to Playwright:

const { items } = await context.getScenarioFiles();
const doc = items.find((f) => f.name === "contract.pdf");
await context.page.locator("input[type=file]").setInputFiles(doc.path);

context.downloadFile(url, opts?) → Promise<FileInfo>

Fetches url on the server and saves the response as a file of the current run. It returns the same fields as a scenario file (id, name, mimeType, size, sha256, path).

  • opts: method, headers, body (a string) and filename. Without filename, the last segment of the URL path is used, and the MIME type is derived from the file extension.
  • Redirects are followed. Any final status other than 200 throws. The limits are 100 MB and a 30 s timeout.
  • url may be a data: URI (data:<type>;base64,<data> or data:<type>,<percent-encoded>), which saves content generated in the script without a network request. Pass filename in this case.
  • Only works during a real scenario run. It throws in ad-hoc execution such as the exec_code MCP tool.
  • This is a server-side request: it does not send the browser's cookies. Pass them in headers if the URL needs a session.
await context.downloadFile(
  "data:application/json;base64," + btoa(JSON.stringify(report)),
  { filename: "report.json" },
);

Timeouts

Each step has its own timeout, or else the scenario's timeout, or else 60 s. The whole run fails once it exceeds the scenario's timeout (600 s by default). That check happens between steps.