- "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
196 lines
8.2 KiB
Markdown
196 lines
8.2 KiB
Markdown
Step code and snippet code are the **body of an async function**. Use `await` freely; whatever you `return` becomes the step (or snippet) output.
|
|
|
|
```js
|
|
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`](https://playwright.dev/docs/test-assertions), 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`](https://playwright.dev/docs/api/class-page) of the run.
|
|
|
|
```js
|
|
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`](https://playwright.dev/docs/api/class-browsercontext) the page belongs to. Use it for cookies, storage state, extra pages and HTTP requests that share the browser's cookies.
|
|
|
|
```js
|
|
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.
|
|
|
|
```js
|
|
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.
|
|
|
|
```js
|
|
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.
|
|
|
|
```js
|
|
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).
|
|
|
|
```js
|
|
// 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.
|
|
|
|
```js
|
|
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` (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. The entry's data holds `details` (if given) and the exception message as `error` (if `fn` threw).
|
|
|
|
Await it, or a failure will not stop the step.
|
|
|
|
```js
|
|
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:
|
|
|
|
```js
|
|
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`.
|
|
|
|
- `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.
|
|
|
|
```js
|
|
// 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:
|
|
|
|
```js
|
|
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.
|
|
|
|
```js
|
|
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.
|