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
andfetch
- Heal: an object containing the Heal context
- faker: the faker object as exported by
'@faker-js/faker';
. Heal runsimport { faker } from '@faker-js/faker';
andimport * as FakerModule from '@faker-js/faker';
to import the package. - OTPAuth: the OTPAuth object as exported by
otpauth
. Heal runsimport * 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 toPASS
if no exception is thrown,CRASH
otherwise.errorMessage
string (optional). An optional error message. By default, it's set toerror
if the js step throws.
setCookies
Usage
await Heal.setCookies([cookieObject1, cookieObject2. ...])
Arguments
cookies
Array<Cookies> where Cookies implement the playwright Cookies object spec.
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:
- Calling an API to create test data (eg. call the backend to create a user account )
- Calling an API to cleanup after a test (remove artifacts created by the test such as user accounts)
- Interacting with variables,
- (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.