Workspace configuration

The directory where all your Maestro-related configuration lives is a Maestro workspace (or just workspace for short).

Maestro configuration

The following properties can be configured on the workspace as a whole as part of the workspace configuration. All settings are optional.

• flows: inclusion patterns regarding what Flows to include (docs).

• includeTags: list of tags to include on each run (docs).

• excludeTags: list of tags to exclude on each run (docs).

• executionOrder: the order to run sequential tests before running remaining tests (docs).

• baselineBranch: Which branch is your baseline. Useful when integrating with Pull Requests (docs). Cloud only.

• notifications: Who to notify after an Upload finishes processing (docs). Cloud only. You might prefer the Slack integration.

• testOutputDir: directory where test artifacts (screenshots, logs, AI reports) are stored (docs).

Platform Configuration

iOS

Following properties can be configured as platform configuration for iOS:

• disableAnimations: Disables system animations on iOS simulator by enabling Reduce Motion. Use this to avoid flakiness due to animations.

⚠️ Note: This only affects system-level animations. Custom animations like those powered by Lottie won't be disabled.

• snapshotKeyHonorModalViews : By default, Maestro shows elements visible within the current modal view context. However, in some apps, especially those using custom presentation styles or certain UI frameworks, elements may appear on modal but still hidden in hierarchy. Try setting this flag to false . It allows Maestro to include those background elements as well, depending on how they’re rendered by the app.

Android

Following properties can be configured as platform configuration for Android:

• disableAnimations: Disables system animations on android emulator by disabling animations from animators, window animations and transitions. Use this to avoid flakiness due to animations.

⚠️ Note: This won't disable custom animations like those from Lottie or other animation libraries.

Example

Below is an example Maestro workspace configuration file. Typically it's named config.yaml and placed in the .maestro directory in your project's root:

flows:
  - 'subFolder/*'
includeTags:
  - tagNameToInclude
excludeTags:
  - tagNameToExclude
executionOrder:
  continueOnFailure: false # default is true
  flowsOrder:
    - flowA
    - flowB

# Customised test output directory
testOutputDir: test_output_directory

# Cloud only config options
baselineBranch: main
notifications:
  email:
    enabled: true
    recipients:
      - [email protected]

# Platform Configuration
platform:
  ios:
    snapshotKeyHonorModalViews: false
    disableAnimations: true
  android:
    disableAnimations: true

Multiple Configs

It's possible to have multiple config files in a repository and specify them at execution time. For example, the default config.yaml could cover the tests typically run on the main branch, but an additional pr-config.yaml might cover the flows and tags used when running tests on each Pull Request.

maestro cloud --config ./pr-config.yaml ./flows

Environment variables

Variable name

MAESTRO_API_URL

Description

The URL of the Maestro API to use. Probably only useful to Mobile Inc developers.

Type

String

Default

https://api.copilot.mobile.dev

Further reading

-

Variable name

MAESTRO_CLI_AI_KEY

Description

Key for external AI service used in AI operations

Type

String

Default

-

Further reading

Docs

Variable name

MAESTRO_CLI_AI_MODEL

Description

Model for external AI service used in AI operations. The prefix of the model decides which service to use. If none is specified, OpenAI will be used.

Type

String

Default

gpt-4o for OpenAI, claude-3-5-sonnet-20240620 for Claude

Further reading

-

Variable name

MAESTRO_CLI_ANALYSIS_NOTIFICATION_DISABLED

Description

Disables the notification displayed on each run about AI analysis

Type

Boolean

Default

false

Further reading

-

Variable name

MAESTRO_CLI_LOG_PATTERN_CONSOLE

Description

Sets the logback layout for logging in the console

Type

String

Default

%highlight([%5level]) %msg%n

Further reading

-

Variable name

MAESTRO_CLI_LOG_PATTERN_FILE

Description

Sets the logback layout for logging in the log file

Type

String

Default

%d{HH:mm:ss.SSS} [%5level] %logger.%method: %msg%n

Further reading

Docs

Variable name

MAESTRO_CLI_NO_ANALYTICS

Description

Disables Maestro analytics collection

Type

Boolean

Default

false

Further reading

-

Variable name

MAESTRO_CLOUD_API_KEY

Description

The API key to use when communicating with the Maestro cloud platform

Type

String

Default

-

Further reading

Docs

Variable name

MAESTRO_CLOUD_API_URL

Description

Like MAESTRO_API_URLbut used for AI API requests

Type

String

Default

https://api.copilot.mobile.dev

Further reading

-

Variable name

MAESTRO_DISABLE_UPDATE_CHECK

Description

Disable the check for newer Maestro versions when running the CLI

Type

Boolean

Default

false

Further reading

-

Variable name

MAESTRO_DRIVER_STARTUP_TIMEOUT

Description

The maximum time to wait for a driver to start

Type

Number

Default

15000

Further reading

Docs

Variable name

MAESTRO_USE_GRAALJS

Description

Use GraalJS instead of RhinoJS for JavaScript execution

Type

Boolean

Default

false

Further reading

Docs

There are also some variables set by default - see Built-in Parameters.

Any other environment variables prefixed with MAESTRO_ will be available in your Flows as JavaScript variables. See Accessing variables from the shell for more information.