Skip to main content

Run Playwright code

This step allows to run JavaScript code in the context of our testing environment: Playwright. This allows to interact with the page under test, and to make server-side HTTP calls. Top-level await statements are allowed but import statements are disabled. The following global objects are exposed:

  • JavaScript globals, e.g. setTimeout
  • Node.js globals, e.g. fetch (cf API documentation)
  • page: the current Playwright Page instance (cf API documentation)
  • Heal: an object containing the Heal SDK
  • faker: the faker object as exported by '@faker-js/faker';. Heal runs import { faker } from '@faker-js/faker'; and import * as FakerModule from '@faker-js/faker'; to import the package.
  • OTPAuth: the OTPAuth object as exported by otpauth. Heal runs import * as OTPAuth from "otpauth" to import the package.

Playwright steps have a 5 minutes timeout by default.

warning

Playwright steps might make testing sessions less robust if they rely on unstable page elements. Make sure that the step behaves robustly.

Heal​

The Heal object contains the Heal SDK, in particular:

  • variables: Map<string, string>: the variables available to the story
  • constants: Map<string, any>: the constants (a.k.a. system variables) available to the story at run time
  • setResult: a method to set the step result, defaulting to 'PASS' if the js executes successfully and 'CRASH' if it throws or timeouts.
  • readLastEmail: a method to fetch the last email received by a given email address

variables​

A Map<string, string> object containing the variables available to the story.

Setting a variable​

To set a variable, use:

Heal.variables.set(key, value) // key:string, value:string

Getting a variable​

To get a variable, use:

Heal.variables.get(key) // key:string

constants​

A Map<string, any> object containing the constants available during the story execution:

  • runId number the id of the run
  • attempt number the id of the attempt
  • email string the catchall email address of the run, see for example email verification

Getting a constant​

To get the value of a constant, use:

Heal.constants.get(key) // key:string

setResult​

Usage​

Heal.setResult('PASS')
Heal.setResult('FAIL', 'The page contains an error')

Arguments​

  • result: 'PASS'|'FAIL'|'CRASH', the result to set for the javascript step. If not set explicitly, will default to PASS if no exception is thrown, CRASH otherwise.
  • errorMessage string (optional). An optional error message. By default, it's set to error if the js step throws.

readLastEmail​

Arguments​

  • recipient: string: the email address to which the message was sent
  • options: object:
    • deleteAfterRead: boolean: to delete the email after it's read. Default: false.
    • since: Date: to return an email which was received after a certain date. Defaults to the start time of the previous step.
    • subject: boolean: Fetch and return the email's subject, in subject. Default: true.
    • fromEmail: boolean: Fetch and return the email's sender, in fromEmail. Default: false.
    • receivedDate: boolean: Fetch and return the email's received date, in receivedDate. Default: false.
    • textBody: boolean: Fetch and return a sample of email's text content, in textBody. Default: false.
    • htmlBody: boolean: Fetch and return the email's full HTML content, in htmlBody. Default: false.
    • attachmentsFileNames: boolean: Fetch and return the filename of each attachment, in attachmentsFileNames. Default: false.
    • timeout: number: Stop waiting for emails after a certain time expressed in milliseconds. Default: 2 * 60_000.

Return value​

Returns a stringified JSON object with properties selected in the options parameter documented above.

Throws an exception if no email was found within the provided timeout period, or if the email address is invalid.

Example​

const email = await Heal.readLastEmail('heal-customer-1@tester-heal.dev', {
    deleteAfterRead: false,
    subject: true,
    htmlBody: true,
});
const { subject, htmlBody } = JSON.parse(email);
Heal.variables.set('emailSubject', subject);
Heal.variables.set('emailBody', htmlBody);

Other javascript step examples​

Interact with the DOM and return a result​

await page.evaluate(() => {
    Array.from(document.querySelectorAll('[data-testid]')).map((a) => {
        a.removeAttribute("data-testid")
    })
})
Heal.setResult("FAIL", "you won't need data-testid with heal")

Call an API​

const fetchResult = await fetch('https://my-api/create-user')

Common use cases​

Common use cases include:

  1. Calling an API to create test data (eg. call the backend to create a user account )
  2. Calling an API to cleanup after a test (remove artifacts created by the test such as user accounts)
  3. Interacting with variables,
  4. (Unstable) Interacting with the DOM using javascript. In some rare cases, testing requires browser interaction not supported by heal (for example, drawing). Javascript steps may be used to handle those corner cases.