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.