Project configuration

Configure your Maestro workspace with config.yaml for test suite settings.

The config.yaml file acts as the central "brain" of your Maestro workspace. While it is optional, it becomes essential when your project grows, allowing you to define global rules for your test suite, manage environment variables, and configure platform-specific behaviors.

Maestro Studio

Unlike the Maestro CLI, Maestro Studio does not currently support config.yaml. However, Studio will include your configuration file in uploads to Maestro Cloud when you run an entire workspace.

When do I need a config file?

If you are just running a single Flow file locally, you don't need a configuration. You should create a config.yaml if:

• You have a deep directory structure and need to define test discovery.

• You need to handle environment variables across multiple Flows.

• You want to configure cloud-specific behaviors like disabling system animations.

Setting up your configuration

Default behavior and hierarchy

When you point Maestro at a directory, it looks for a file named config.yaml in the root of that directory. If no --config flag is provided and the file is missing, Maestro runs with default settings.

1

Create the configuration file

You can place your configuration file anywhere in your repository, but for simplicity, it should be at the root of the Maestro workspace (commonly within a .maestro/ folder).

Ensure the file is named exactly config.yaml.

2

Set the global environment variables

Use the env block to define data that changes across environments (staging vs. production, for example). This allows you to reference them in any Flow using the ${VARIABLE_NAME} syntax without hardcoding secrets.

# config.yaml
env:
    USERNAME: "test_user_01"
    API_URL: "https://staging.api.com"

If you are using Maestro Studio, it provides an interface for managing environment variables.

appId in configuration

The appId is defined at the top of individual Flow files, not within the config.yaml. While Maestro Studio may prompt for an ID, it does not currently read this value from configuration files.

3

Configure the platform behavior

To ensure your tests are stable and flake-free, you can configure platform-specific behaviors.

# config.yaml
platform:
  ios:
    snapshotKeyHonorModalViews: false # iOS: Includes background elements in the hierarchy

Cloud-only flags

Some flags, like disableAnimations, are a cloud-only feature and does not affect local emulators or simulators.

If you need a list of all configurations available to configure your test suite, access the Workspace configuration reference.

Working with multiple configs

While config.yaml is the default, you can create multiple configuration files for different scenarios (e.g., smoke-config.yaml or ci-config.yaml). To run a test suite with a specific configuration, use the --config flag when running the tests with the Maestro CLI:

maestro test --config .maestro/ci-config.yaml tests/

Next steps

If you need a full list of every available key and configuration available, access the Workspace configuration reference page.

To plan your test architecture access Design your test architecture. On the other hand, if you need to organize your tests, learn how to use the flows key in your config to manage Test discovery and tags.