runScript

Run an external JavaScript file and capture its output.

The runScript command executes a specified JavaScript file. The script can access environment variables and set output values for subsequent commands in the flow.

Parameters

The runScript command accepts either a string that specifies the file path or a map that contains the file path and environment variables.

Key	Description
file	The path to the JavaScript file to execute. Paths can be absolute or relative to the flow file.
env	(Optional) A map of key-value pairs to pass as environment variables to the script.

Usage examples

The following examples demonstrate how to use the runScript command.

Basic execution

Use runScript with a file path to execute a script. The script can access predefined env variables from the flow and set output values for later use.

Flow file

appId: com.example
env:
    MY_NAME: John
---
- launchApp
- runScript: myScript.js
- inputText: ${output.uppercaseName}

JavaScript file (myScript.js)

In this example, the flow launches the app and then executes an external JavaScript file using runScript. The script reads the MY_NAME environment variable defined in the flow, converts it to uppercase, and stores the result in output.uppercaseName. That output value is then used in the next step to input the text "JOHN" into the app.

File paths

Paths can be relative or absolute.

When running in the cloud, relative paths are required. Relative paths are resolved from the calling flow’s location, not from the directory where the command is executed.

Given the following directory structure:

├── flows
│   └── test.yaml
└── scripts
    └── uppercase.js

The test.yaml flow must use a relative path to reference uppercase.js:

appId: com.example
env:
    MY_NAME: John
---
- launchApp
- runScript: ../scripts/uppercase.js

Passing parameters

To pass parameters directly to a script, use the expanded map syntax with the env key.

- runScript:
    file: script.js
    env:
       myParameter: 'Parameter'

Console logging

runScript redirects any console.log() output from the JavaScript file to the Maestro CLI console.

Cloud execution

When you run flows in Maestro Cloud, you must upload the directory that contains your flows and scripts, not just a single flow file. For example, use maestro cloud --app-file myApp.apk --flows ./myTestsFolder.

If you do not include the script files in the upload, the execution fails with a Failed to parse file error.

Related content

• JavaScript overview: Start exploring how to use JavaScript in your tests.

• JavaScript outputs: Learn how to store and consume JavaScript outputs in Maestro flows.

• Parameters: Learn how to define and use parameters in flows to make them reusable.

• Constants: Learn how to define constant values and reuse them across your flows.

• Nested flows: Learn how to compose flows by calling one flow from another.

• Conditional execution: Learn how to control flow execution using conditions and branching logic.