JavaScript overview
Extend flows with JavaScript for complex logic and data manipulation.
While the YAML syntax handles most UI interactions declaratively, some scenarios need logic that goes beyond linear steps. JavaScript lets you run a scripting engine directly from your flows, so you can handle dynamic data, complex assertions, and calls to external services.
Why use JavaScript in your flows?
- Handle dynamic data: generate unique identifiers, format dates, or manipulate strings for input fields.
- Complex control flow: implement logic that YAML cannot express easily, such as calculations or multi-step branching.
- External connectivity: sync your UI tests with your backend by calling an API to fetch test data or verify state.
- Enhanced assertions: write custom logic to verify UI states that need calculation or parsing.
How it works
Scripts run in an embedded engine inside the runner, not in Node.js and not in a browser. They have no direct access to the DOM or to Node.js libraries such as fs.
JavaScript engine
Astra Scout runs flows with maestro-runner, which uses goja, a JavaScript engine written in Go. It supports ECMAScript 5.1 plus most ES6 and later features (let, const, arrow functions, template literals, classes). Maestro itself uses GraalJS (and optionally Rhino), so rare language features can differ between the two. Test a script in Astra Scout before you rely on an unusual feature.
The runner adds a few globals to the engine:
| Global | What it is |
|---|---|
output | A shared object that persists across the whole flow. See Manage data and states. |
maestro | Information about the run: maestro.platform and maestro.copiedText. |
http | A small HTTP client. See Make HTTP requests. |
json() | Parses a JSON string into an object. |
console | console.log, console.warn, and console.error. |
require() | Loads another script as a CommonJS module, for example require('./helpers.js'). A relative path resolves against the flow's folder. ES import is not available. |
Not available in Astra Scout
Maestro's faker object (DataFaker) does not exist in maestro-runner. See Generate synthetic data for alternatives.
Explore JavaScript capabilities
- Run and debug JavaScript: three ways to run JavaScript, and how to log from your scripts.
- Manage data and states: the global
outputobject shares data across your entire flow. - Make HTTP requests: perform
GET,POST,PUT, andDELETErequests directly from your scripts. - Generate synthetic data: create random values for your tests.
The related commands are runScript and evalScript.