Ask the Community
Run Maestro tests with tags
Learn how to use tags to selectively run a subset of your Maestro test flows on BrowserStack App Automate.
You can refine your Maestro test runs on BrowserStack by using tags to filter which flows are executed. This is useful for running specific test subsets, such as smoke tests, regression tests, or tests related to a specific feature, without altering your test suite.
Prerequisites
- You have already uploaded your Maestro test suite to BrowserStack.
- You have a
.zipfile containing your flow files.
How to filter Maestro tests with tags
The process involves two steps: first, you add tags to your test flows, and second, you use those tags in your REST API request to filter the execution.
Add tags to your Maestro flow files
Define tags within your individual YAML flow files using the tags key. A single flow can have multiple tags.
Example flow files:
Here, flowA.yml is tagged for both dev and pull-request runs, while flowB.yml is only tagged for dev.
# flowA.yml
appId: com.example.app
tags:
- dev
- pull-request
# flowB.yml
appId: com.example.app
tags:
- dev
Use tags in your API request
Use the tags parameter in your REST API request to specify which flows to run using includeTags and excludeTags.
-
includeTags: A list of tags to include. A flow is selected if it has at least one of the tags in this list (logical OR). -
excludeTags: A list of tags to exclude. A flow is removed from the selection if it has at least one of the tags in this list (logical OR).
How filtering works: The system determines the final selection of flows using an AND operation. A flow must meet the includeTags criteria AND not meet the excludeTags criteria to be executed.
Examples
Let’s consider these two flows:
-
flowA.yml has tags:
dev,pull-request -
flowB.yml has tags:
dev
Here’s how different API requests would filter them:
tags object in API request |
Flows executed | Reason |
|---|---|---|
{"includeTags": ["dev"]} |
flowA, flowB
|
Both flows have the dev tag. |
{"includeTags": ["dev", "pull-request"]} |
flowA, flowB
|
Both flows have at least one of the specified tags. |
{"excludeTags": ["pull-request"]} |
flowB |
flowA is excluded because it has the pull-request tag. |
{"includeTags": ["dev"], "excludeTags": ["pull-request"]} |
flowB |
Both flows are included by dev, but flowA is then removed by the exclude filter. |
Example cURL request:
This request executes flows tagged with dev but excludes any that are also tagged with pull-request. Based on the examples above, only flowB.yml executes.
curl -u "username:accesskey" \
-X POST "https://api-cloud.browserstack.com/app-automate/maestro/v2/android/build" \
-H "Content-Type: application/json" \
-d '{"app": "bs://9c6dcb5649a8280ca800075bfd8f151115bba6b3",
"testSuite": "bs://89c874f21852ba57957a3fdc33f47514288c4ba1",
"project": "Maestro_Test",
"devices": ["Samsung Galaxy S20-10.0", "Google Pixel 3-9.0"],
"setEnvVariables": {
"USERNAME": "abcxyz",
"PASSWORD": "password123"
},
"tags" : {
"includeTags" : ["dev"],
"excludeTags" : ["pull-request"]
}
}'
curl -u "username:accesskey" \
-X POST "https://api-cloud.browserstack.com/app-automate/maestro/v2/ios/build" \
-H "Content-Type: application/json" \
-d '{"app": "bs://9c6dcb5649a8280ca800075bfd8f151115bba6b3",
"testSuite": "bs://89c874f21852ba57957a3fdc33f47514288c4ba1",
"project": "Maestro_Test",
"devices": ["iPhone 15-17.0"],
"setEnvVariables": {
"USERNAME": "abcxyz",
"PASSWORD": "password123"
},
"tags" : {
"includeTags" : ["dev"],
"excludeTags" : ["pull-request"]
}
}'
Providing the same tag in both the includeTags and excludeTags arrays results in an error.
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!