Skip to main content

Run javascript

This step allows to run any javascript code in the browser running the test. This behaves just like running code in the console of the test browser. Top-level await statements are allowed but import statements are disabled. The following global objects are exposed:

  • all browser APIs, including document and fetch
  • Heal: an object containing the Heal context
  • 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.

Javscript steps have a 30 seconds timeout.

warning

Javascript 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 context, in particular:

  • variables: Map<string, any>: the variables available to the story
  • setResult: a method to set the step result, defaulting to 'PASS' if the js executes successfully and 'CRASH' if it throws or timeouts.
  • setCookies: a method to set cookies in the test browser
  • setLocalStorage: a method to set the local storage in the test browser

variables

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

The following variables are system variables and cannot be changed:

  • 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

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

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.

setCookies

Usage

await Heal.setCookies([cookieObject1, cookieObject2. ...])

Arguments

Example

await Heal.setCookies([ {
"name": "hello",
"value": "you",
"domain": "test.com",
"path": "/main/path",
"expires": 1764266741.124436,
"httpOnly": true,
"secure": true,
"sameSite": "Strict"
}])

setLocalStorage

Usage

const localStorageObject: {[k:string]:string} = {key:"value"}
await Heal.setLocalStorage(localStorageObject)

Arguments

  • localStorageObject [k:string]:string a dictionary of key-value pairs

Example

await Heal.setLocalStorage({
"version": "13",
"userSettings": "{\"language\":\"en-GB\",\"numberLocalFormat\":\"en\"}"
}

)

Other javascript step examples

Interact with the DOM and return a result

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. (Untsable) 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.