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 called shards and run them in parallel across multiple devices, significantly reducing overall test execution time.
What is test sharding
By default, all flows in your Maestro test suite are executed sequentially. Instead of running your test suite sequentially, you can split flows into different groups called shards. Each shard can then be executed in parallel on one or more devices. This is especially helpful when your test suite has a large number of flows.
For example, if your test suite has 500 flows and each flow takes about a minute to execute, running the test suite sequentially takes close to 500 minutes. If you split your test suite into 10 shards and execute each shard in parallel, the total test execution time comes down to 50 minutes.
Enable test sharding
To enable test sharding, configure the shards parameter in the REST API request to start Maestro test execution.
REST API endpoint:
POST /app-automate/maestro/v2/android/build
POST /app-automate/maestro/v2/ios/build
| Parameter | Description | Values |
|---|---|---|
shards |
Split the test-suite into multiple shards and execute them in parallel. | An object (key-value pairs) to specify the number of shards and configure their behavior. Refer to REST API for detailed reference. |
Example cURL request:
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,
"mapping": [
{
"name": "Shard 1",
"values": {
"execute": [
"flows/payments"
]
}
},
{
"name": "Shard 2",
"values": {
"execute": [
"flows/login"
]
}
}
]
},
"devices": [
"Google Pixel 7-13.0"
],
"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,
"mapping": [
{
"name": "Shard 1",
"values": {
"execute": [
"flows/payments"
]
}
},
{
"name": "Shard 2",
"values": {
"execute": [
"flows/login"
]
}
}
]
},
"devices": [
"iPhone 15-17.0"
],
"app": "bs://f7c874f21852ba57957a3fdc33f47514288c4ba4",
"testSuite": "bs://j3c874f21852ba57957a3fdc33f47514288c4ba4"
}'
In this example, the test suite is split into 2 shards, and each of those shards executes in parallel on Google Pixel 7-13.0 on Android or iPhone 15-17.0 on iOS. This blocks 2 parallel test licenses in your App Automate subscription plan.
Sharding strategy
Each shard’s values object needs at least one of the following strategies to decide which flows it runs: tags, the execute parameter, or a config file. You can combine them in one shard, for example, tags with the execute parameter.
Keep the following in mind when you configure shards:
- 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.
1. Use tags strategy
Using this strategy, you can group flows by the tags defined in your test flows. Use includeTags to run flows that have a tag, and excludeTags to skip flows that have a tag. Tags filter the flows in the directories listed in the execute parameter. If a shard has no execute parameter, tags filter only the flows at the root of your workspace. All the shards execute in parallel on the devices specified in the devices parameter.
Example cURL request:
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,
"mapping": [
{
"name": "Shard 1",
"values": {
"tags": {
"includeTags": [
"smoke"
]
}
}
},
{
"name": "Shard 2",
"values": {
"tags": {
"includeTags": [
"regression"
],
"excludeTags": [
"flaky"
]
}
}
}
]
},
"devices": [
"Google Pixel 7-13.0"
],
"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,
"mapping": [
{
"name": "Shard 1",
"values": {
"tags": {
"includeTags": [
"smoke"
]
}
}
},
{
"name": "Shard 2",
"values": {
"tags": {
"includeTags": [
"regression"
],
"excludeTags": [
"flaky"
]
}
}
}
]
},
"devices": [
"iPhone 15-17.0"
],
"app": "bs://f7c874f21852ba57957a3fdc33f47514288c4ba4",
"testSuite": "bs://j3c874f21852ba57957a3fdc33f47514288c4ba4"
}'
In this example, the first shard runs flows tagged smoke. The second shard runs flows tagged regression, except flows that are also tagged flaky.
2. Use execute strategy
Using this strategy, you can group flows by listing flow file paths or directory paths in the execute parameter. If you list a directory, Maestro runs the flows directly inside it, not flows in its subfolders. To run flows in a subfolder, list the subfolder path. All the shards execute in parallel on the devices specified in the devices parameter.
Example cURL request:
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,
"mapping": [
{
"name": "Shard 1",
"values": {
"execute": [
"flows/payments"
]
}
},
{
"name": "Shard 2",
"values": {
"execute": [
"flows/login"
]
}
}
]
},
"devices": [
"Google Pixel 7-13.0"
],
"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,
"mapping": [
{
"name": "Shard 1",
"values": {
"execute": [
"flows/payments"
]
}
},
{
"name": "Shard 2",
"values": {
"execute": [
"flows/login"
]
}
}
]
},
"devices": [
"iPhone 15-17.0"
],
"app": "bs://f7c874f21852ba57957a3fdc33f47514288c4ba4",
"testSuite": "bs://j3c874f21852ba57957a3fdc33f47514288c4ba4"
}'
In this example, the first shard runs all flows in the flows/payments folder, and the second shard runs all flows in the flows/login folder.
3. Use config file strategy
Using this strategy, you can reference a configuration file for each shard. The file contains detailed instructions about which flows to run, including tag specifications and flow file paths. All the shards execute in parallel on the devices specified in the devices parameter.
Example cURL request:
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,
"mapping": [
{
"name": "Shard 1",
"values": {
"config": "configs/payments.yaml"
}
},
{
"name": "Shard 2",
"values": {
"config": "configs/login.yaml"
}
}
]
},
"devices": [
"Google Pixel 7-13.0"
],
"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,
"mapping": [
{
"name": "Shard 1",
"values": {
"config": "configs/payments.yaml"
}
},
{
"name": "Shard 2",
"values": {
"config": "configs/login.yaml"
}
}
]
},
"devices": [
"iPhone 15-17.0"
],
"app": "bs://f7c874f21852ba57957a3fdc33f47514288c4ba4",
"testSuite": "bs://j3c874f21852ba57957a3fdc33f47514288c4ba4"
}'
In this example, each shard runs the flows defined in its own configuration file.
Device selection strategy
Use the deviceSelection attribute inside the shards parameter to control which devices each shard runs on. If you don’t set it, BrowserStack uses all.
| Parameter | Description | Values |
|---|---|---|
deviceSelection |
Run each shard on all devices, on a randomly selected device from the list of devices specified in the devices parameter, or on one device that you choose for each shard. |
all, any, oneToOne Default: all all: Each shard runs on all devices specified. The total number of test sessions in the build equals (n shards * m devices). any: Each shard runs on one randomly selected device. The total number of test sessions in the build equals (n shards). oneToOne: Each shard runs on exactly one device, the device set in the shard’s mapping entry. If a shard has no device, it runs on the device at the shard’s position in the devices parameter. The total number of test sessions in the build equals (n shards). |
The value you choose also decides how many parallel test licenses the build blocks. For a build with x shards and y devices:
-
all: Each shard runs on every device in thedevicesparameter. The build blocks x × y parallel test licenses. -
any: Each shard runs on one device randomly selected from thedevicesparameter. The build blocks x parallel test licenses. -
oneToOne: Each shard runs on one device that you choose. The build blocks x parallel test licenses.
Run each shard on all devices
Use all when every shard must run on every device in the devices parameter, for example, to confirm that your whole test suite passes on each device model. all is the default value, so each shard runs on all devices even if you don’t set deviceSelection.
The following sample cURL request runs two shards 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 both specified devices, so the build runs 4 test sessions, 2 shards × 2 devices. This consumes 4 parallel test licenses in your App Automate subscription plan.
Run each shard on a random device
Use any when you want to run the test suite with fewer parallel test licenses and it doesn’t matter which device runs each shard. Each shard runs on one device randomly selected from the devices parameter, so a shard can run on a different device in each build.
The following sample cURL request runs each shard on one randomly selected device:
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": "any",
"mapping": [
{
"name": "payments",
"values": {
"execute": [
"flows/payments"
]
}
},
{
"name": "login",
"values": {
"execute": [
"flows/login"
]
}
}
]
},
"devices": [
"Google Pixel 7-13.0",
"Samsung Galaxy S10e-9.0"
],
"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": "any",
"mapping": [
{
"name": "payments",
"values": {
"execute": [
"flows/payments"
]
}
},
{
"name": "login",
"values": {
"execute": [
"flows/login"
]
}
}
]
},
"devices": [
"iPhone 15-17.0",
"iPhone 14-16.0"
],
"app": "bs://f7c874f21852ba57957a3fdc33f47514288c4ba4",
"testSuite": "bs://j3c874f21852ba57957a3fdc33f47514288c4ba4"
}'
In this example, the test suite is split into two shards with deviceSelection set to any. Each shard runs on one device randomly selected from the devices parameter. This consumes 2 parallel test licenses in your App Automate subscription plan, one for each shard.
Run each shard on a device you choose
Use oneToOne when each shard must run on a specific device, for example, to run one group of tests on a newer device and another group on an older device. Each shard runs on exactly one device:
- If the shard’s
mappingentry has adevice, the shard runs on that device. - If the shard has no
device, it runs on the device at the shard’s position in thedevicesparameter: the first shard on the first device, the second shard on the second device, and so on. If there are more shards than devices, the assignment wraps around to the first device. The position counts every shard, including shards that set their owndevice. For example, if you have three shards and only the first shard sets adevice, the second shard runs on the second entry in thedevicesparameter, not the first.
If every shard has its own device, you can omit the devices parameter. The build blocks one parallel test license for each shard.
Set a device for each shard
Add a device to each shard’s mapping entry. The following sample cURL request runs each shard on its own device:
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": "oneToOne",
"mapping": [
{
"name": "payments",
"values": {
"execute": [
"flows/payments"
]
},
"device": "Google Pixel 8-14.0"
},
{
"name": "login",
"values": {
"execute": [
"flows/login"
]
},
"device": "Samsung Galaxy S23-13.0"
}
]
},
"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": "oneToOne",
"mapping": [
{
"name": "payments",
"values": {
"execute": [
"flows/payments"
]
},
"device": "iPhone 15-17"
},
{
"name": "login",
"values": {
"execute": [
"flows/login"
]
},
"device": "iPhone 14-16"
}
]
},
"app": "bs://f7c874f21852ba57957a3fdc33f47514288c4ba4",
"testSuite": "bs://j3c874f21852ba57957a3fdc33f47514288c4ba4"
}'
In this example, the payments shard runs only on Google Pixel 8-14.0 on Android or iPhone 15-17 on iOS, and the login shard runs only on Samsung Galaxy S23-13.0 on Android or iPhone 14-16 on iOS. The request omits the devices parameter because every shard has its own device. This blocks 2 parallel test licenses in your App Automate subscription plan.
Combine shard devices with the devices parameter
You can set a device for some shards and let the others take a device from the devices parameter. The following sample cURL request sets a device only for the payments shard:
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": "oneToOne",
"mapping": [
{
"name": "payments",
"values": {
"execute": [
"flows/payments"
]
},
"device": "Google Pixel 8-14.0"
},
{
"name": "login",
"values": {
"execute": [
"flows/login"
]
}
}
]
},
"devices": [
"Samsung Galaxy S23-13.0"
],
"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": "oneToOne",
"mapping": [
{
"name": "payments",
"values": {
"execute": [
"flows/payments"
]
},
"device": "iPhone 15-17"
},
{
"name": "login",
"values": {
"execute": [
"flows/login"
]
}
}
]
},
"devices": [
"iPhone 14-16"
],
"app": "bs://f7c874f21852ba57957a3fdc33f47514288c4ba4",
"testSuite": "bs://j3c874f21852ba57957a3fdc33f47514288c4ba4"
}'
In this example, the payments shard runs on its own device, Google Pixel 8-14.0 on Android or iPhone 15-17 on iOS. The login shard has no device, so it takes the device at its position in the devices parameter. The list has only one device, so the assignment wraps around and the login shard runs on Samsung Galaxy S23-13.0 on Android or iPhone 14-16 on iOS.
Select a device using a regex pattern
Instead of an exact device, you can set a shard’s device to an object with device and optional os_version regex patterns, such as {"device": "Google Pixel 8.*", "os_version": "14"} or {"device": "iPhone 15.*"}. The shard then runs on any available device that matches.
Rules for the oneToOne value
Follow these rules when you use oneToOne:
- The
devicein a shard’smappingentry applies only whendeviceSelectionis set tooneToOne. Withallorany, it’s ignored. - Use one format throughout. The
devicesparameter and everydeviceinmappingmust all be exactDevice-OSstrings, or must all be regex objects. - A regex object must contain a pattern, such as
.*or[34]. To run a shard on a fixed device, use the exactDevice-OSstring instead of an object. - Every shard needs a device, either its own
deviceinmappingor an entry in thedevicesparameter to fall back on.
If your request doesn’t follow these rules, the API returns one of the following errors and doesn’t create the build:
| Error message | Cause | Fix |
|---|---|---|
[BROWSERSTACK_SHARDS] With "deviceSelection" set to "oneToOne", every shard needs a device: either a "device" in its mapping or an entry in the "devices" parameter. Please pass the required parameters in a valid format and try again. |
Some shards set a device and others don’t, and the devices parameter is missing or empty. |
Add a device to every shard’s mapping entry, or pass at least one device in the devices parameter. |
[BROWSERSTACK_SHARDS] The device defined in the mapping for a shard must use the same format as the entries of the "devices" parameter. Please pass the required parameters in a valid format and try again. |
The devices parameter and the device values in mapping mix exact Device-OS strings and regex objects, a regex object has no device key, or a device value is a number, array, or boolean. |
Use one format throughout: either exact Device-OS strings or regex objects for the devices parameter and every device in mapping. |
[BROWSERSTACK_INVALID_PARAMETER_VALUE_ERROR] Invalid value passed for devices parameter. Please pass a valid value and try again. ... |
A device in mapping is a regex object with no regex pattern, such as {"device": "Google Pixel 8"}. |
Use a regex pattern such as .*, or the exact Device-OS string. |
[BROWSERSTACK_INVALID_DEVICE] ... |
A device in mapping uses the correct format but names a device that is invalid or unavailable. |
Use a device from the list of supported devices. |
Related topics
-
Manage your uploaded app or test suite using the 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.
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
Thank you for your valuable feedback!