Structure your Maestro accessibility tests

Learn how to organize and structure your Maestro test suite.

To run Maestro tests on BrowserStack, you must correctly organize your test suite’s folder structure. Incorrect structures and zipped test suites are common reasons for test run failures.

This guide explains how to correctly structure your files and how to use the execute parameter to run specific tests.

Use a parent folder

Place all your test files, sub-folders, and related assets inside a single parent folder, then zip it for upload.

Even if you have only a single Flow file, place it 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

Your test suite should be a single .zip file. After unzipping on our servers, it should look 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 tests

After uploading your app and test suite, specify which tests to run using the execute parameter. All paths provided in the execute parameter should be relative to the root folder (e.g., sample_parent_folder in the earlier example).

Case 1: Run the entire suite (default behavior)

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

• Using the example structure, this runs flow1.yaml, flow2.yaml, and flow3.yaml.
• Flows inside common/, subflows/, or other directories are ignored.

Case 2: Run specific flow files

To run 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: Run all flows in a folder

To run all flow files within 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: Run a mix of files and folders

You can mix individual files and entire folders.

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

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

Next steps

• Integrate Maestro test suite with App Accessibility testing