Prepare your Maestro test suite

Learn how to correctly structure, zip, and upload your Maestro test suite for seamless execution on BrowserStack.

Getting your test suite’s folder structure right is the most critical step in running Maestro tests on BrowserStack. A common reason for test failures is an incorrectly structured or zipped test suite.

This guide walks you through the correct way to structure your files and how to use the execute parameter to run specific tests.

The golden rule: use a parent folder

All your test files, sub-folders, and any related assets must be inside a single parent folder. You then zip this parent folder for upload.

Even if you only have a single Flow file to test, it must be placed inside a parent folder before zipping.

If you upload a .zip file without a single root folder, your test run will fail.

Example test suite structure

When you upload your test suite, it should be a single .zip file. After unzipping on our servers, it should look something like this:

Here’s a text representation of a correct folder structure:

sample_parent_folder/
├── common/
│   ├── functions/
│   │   ├── function1.yaml
│   │   └── function2.yaml
│   ├── commonflow1.yaml
│   └── commonflow2.yaml
├── sample_apps/
│   ├── AWS.ipa
│   └── WikipediaSample.apk
├── subflows/
│   ├── subflow1.yaml
│   └── subflow2.yaml
├── flow1.yaml
├── flow2.yaml
└── flow3.yaml

Running your tests: the execute parameter

Once you’ve uploaded your app and your correctly structured test suite, you can specify exactly which tests to run using the execute parameter in your build execution REST API call.

All paths provided in the execute array are relative to your parent folder.

Case 1: Running the entire suite (default behavior)

If you do not include the execute key in your API request, BrowserStack runs only the flow files located at the root of your parent folder by default.

• Using the example structure, this would run flow1.yaml, flow2.yaml, and flow3.yaml.
• Flows inside common/, subflows/, or any other directory will be ignored.

Case 2: Running specific flow files

To run one or more specific flow files, list their paths in the execute array. For example, to run flow2.yaml and the nested function1.yaml:

"execute": ["flow2.yaml", "common/functions/function1.yaml"]

Case 3: Running all flows in a folder

To run all the flow files within one or more specific folders, provide the folder paths.

For example, to run all flows in the common and common/functions folders:

"execute": ["common", "common/functions"]

Case 4: Running a mix of files and folders

You can also mix and match individual files and entire folders.

For example, to run flow1.yaml and all the flows in the common/functions folder:

"execute": ["flow1.yaml", "common/functions"]

By following this structure and using the execute parameter correctly, you can ensure your Maestro tests run smoothly and predictably on BrowserStack.

Related topic

Execute Maestro tests