- "Step N passed" log entry carries the step's return value as data
- context.assert accepts an optional details argument; on failure the
assertion:fail entry stores { details, error } as data
- assertion failures throw AssertionFailedError so "Step N failed" and
"Snippet X failed" entries name only the assertion, without repeating
the details; the step run description keeps the full message
- exported e2e runtime accepts and prints assert details
- log output shows elapsed time in whole seconds, matching the stored
timestamp resolution
- run artifact and scenario file names link to the inline file content
in a new tab
8.2 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
orderis absolute:1is the first step. - A negative
orderis relative:-1is 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, details?) → Promise<void>
Runs fn (sync or async) and requires it to return exactly true.
- On success, it logs
description(taggedassertion:pass). - If
fnreturns anything else or throws, it logsAssertion failed: <description>as an error (taggedassertion:fail) and throws, which fails the step. The entry's data holdsdetails(if given) and the exception message aserror(iffnthrew).
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",
);
Pass large diagnostics (e.g. a response body) as details rather than in description, so the message stays short:
await context.assert(() => response.ok(), "Validation must pass", {
status: response.status(),
body: await response.json(),
});
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.
nameis 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) andfilename. Withoutfilename, 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.
urlmay be adata:URI (data:<type>;base64,<data>ordata:<type>,<percent-encoded>), which saves content generated in the script without a network request. Passfilenamein this case.- Only works during a real scenario run. It throws in ad-hoc execution such as the
exec_codeMCP tool. - This is a server-side request: it does not send the browser's cookies. Pass them in
headersif 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.