Use test sharding to speed up Maestro tests

Speed up your Maestro mobile automation tests by splitting your test suite across real devices on BrowserStack App Automate.

Test sharding allows you to split your test suite into multiple parts (shards) and run them in parallel across multiple devices, significantly reducing overall test execution time. You can configure shards with specific flows, tags, or configuration files, and control whether each shard runs on all devices or a randomly selected device from your device list.

Implement sharding on BrowserStack Maestro

On BrowserStack Maestro, you can configure sharding by specifying the number of shards, the device list, and the tests to run within each shard. Each shard can be configured flexibly using tags, flow files, or configuration files to determine which tests to execute.

Configure shards

To configure shards effectively, you can use one of the following approaches within each shard:

• Tags: Use includeTags and excludeTags to filter and run specific tests based on tags defined in your test flows.
• Execute parameter: Directly specify flow file paths or directory paths containing your test flows. You can provide individual flow files or nested folders, and Maestro will automatically execute all flows within the specified directories.
• Config file: Reference a configuration file that contains detailed instructions about which tests to run, including tag specifications and flow file paths.

You can combine these options based on your needs. For example, you can use tags alone, tags with the execute parameter, the execute parameter alone, or a config file alone. Each shard requires at least one of these parameters to determine which tests to run.

Important considerations

• Parameter precedence: When you define parameters both at the shard level and globally (outside the shard configuration), shard-level parameters take precedence. For instance, if a shard has a specific config file with different test execution settings than the global config file, the shard-level configuration determines the tests to run for that shard.
• Subflow execution: If your flows call any subflows, Maestro automatically runs those subflows as part of the shard, even if you don’t explicitly include them in your configuration.
• Device selection: Use the deviceSelection parameter to control how shards distribute across devices. Setting it to all runs each shard on every specified device, while any runs each shard on a randomly available device from the list.
• Device assignment: Currently, you cannot assign specific devices to individual shards. All shards use the same device list defined in the devices parameter.

Example: Test sharding with device selection

The following sample curl request demonstrates sharding with two shards running on both devices:

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST "https://api-cloud.browserstack.com/app-automate/maestro/v2/android/build" \
-H "Content-Type: application/json" \
-d '{
    "shards": {
        "numberOfShards": 2,
        "deviceSelection": "all",
        "mapping": [
            {
                "name": "Shard 1",
                "values": {
                    "tags": {
                        "includeTags": [
                            "dev"
                        ],
                        "excludeTags": [
                            "pull-request"
                        ]
                    },
                    "execute": [
                        "<FLOW FILE PATH>",
                        "<FLOW DIR PATH>"
                    ]
                }
            },
            {
                "name": "Shard 2",
                "values": {
                    "config": "path/to/your/config.yaml"
                }
            }
        ]
    },
    "devices": [
        "Google Pixel 7-13.0",
        "Samsung Galaxy S10e-9.0"
    ],
    "setEnvVariables": {
        "ENV_VAR_1": "value1",
        "ENV_VAR_2": "value2"
    },
    "app": "bs://f7c874f21852ba57957a3fdc33f47514288c4ba4",
    "testSuite": "bs://j3c874f21852ba57957a3fdc33f47514288c4ba4"
}'

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST "https://api-cloud.browserstack.com/app-automate/maestro/v2/ios/build" \
-H "Content-Type: application/json" \
-d '{
    "shards": {
        "numberOfShards": 2,
        "deviceSelection": "all",
        "mapping": [
            {
                "name": "Shard 1",
                "values": {
                    "tags": {
                        "includeTags": [
                            "dev"
                        ],
                        "excludeTags": [
                            "pull-request"
                        ]
                    },
                    "execute": [
                        "<FLOW FILE PATH>",
                        "<FLOW DIR PATH>"
                    ]
                }
            },
            {
                "name": "Shard 2",
                "values": {
                    "config": "path/to/your/config.yaml"
                }
            }
        ]
    },
    "devices": [
        "iPhone 15-17.0",
        "iPhone 14-16.0"
    ],
    "setEnvVariables": {
        "ENV_VAR_1": "value1",
        "ENV_VAR_2": "value2"
    },
    "app": "bs://f7c874f21852ba57957a3fdc33f47514288c4ba4",
    "testSuite": "bs://j3c874f21852ba57957a3fdc33f47514288c4ba4"
}'

In this example, the test suite is split into two shards with deviceSelection set to all. Each shard uses different parameter combinations: Shard 1 uses tags and execute to run specific flows with tag filtering, while Shard 2 uses only a config file to determine which tests to run. Each shard runs on all specified devices (two devices), resulting in four parallel test executions (2 shards × 2 devices). This consumes 4 parallel test licenses in your App Automate subscription plan.

Related topics

• Manage your uploaded app or test suite using our upload app REST API and upload test suite REST API.

• Use the get app API endpoint and list test suites API endpoint to list your recently uploaded apps and test suites.

• Delete your uploaded app or test suite using the delete app API endpoint and delete test suite API endpoint.