Run a sample App Percy build with Maestro

Clone the sample project

Clone the example project and install its dependencies:

git clone https://github.com/percy/example-percy-maestro-app
cd example-percy-maestro-app
npm install

This installs @percy/maestro-app and @percy/cli. The project includes a sample Android calculator app at resources/app-debug.apk and two Maestro flows in the flows/ directory:

• flows/screenshot.yaml captures two screenshots of the calculator.
• flows/regions.yaml captures two screenshots and masks the status bar and the result field using regions.

Create an App Percy project

Sign in to Percy, create a new project, and select App as the project type. Percy generates a unique PERCY_TOKEN for the project. Copy the token. You pass it in the build payload in a later step.

Upload the sample app

Upload the bundled APK to BrowserStack:

curl -u "BROWSERSTACK_USERNAME:BROWSERSTACK_ACCESS_KEY" \
  -X POST "https://api-cloud.browserstack.com/app-automate/maestro/v2/app" \
  -F "file=@resources/app-debug.apk"

Note the app_url value in the response. You pass it in the build payload in a later step.

Prepare and upload the test suite

Package the flows along with the App Percy SDK files into a zip:

npm run prepare-zip

Upload the resulting Flows.zip to BrowserStack:

curl -u "BROWSERSTACK_USERNAME:BROWSERSTACK_ACCESS_KEY" \
  -X POST "https://api-cloud.browserstack.com/app-automate/maestro/v2/test-suite" \
  -F "file=@Flows.zip"

Note the test_suite_url value in the response. You pass it in the build payload in the next step.

Trigger the build with App Percy

Trigger the build, passing your app URL, test suite URL, and Percy token from the previous steps. Set the token in the appPercy object of the payload:

curl -u "BROWSERSTACK_USERNAME:BROWSERSTACK_ACCESS_KEY" \
  -X POST "https://api-cloud.browserstack.com/app-automate/maestro/v2/android/build" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "<APP_URL>",
    "testSuite": "<TEST_SUITE_URL>",
    "devices": ["Samsung Galaxy S22-12.0"],
    "project": "Percy Maestro Example",
    "appPercy": {
      "PERCY_TOKEN": "<PERCY_TOKEN>"
    }
  }'

View the results

The build runs both flows and uploads four screenshots to your App Percy project. Open the project in Percy to review the build. The screenshots from flows/regions.yaml show the status bar and result field masked, so changes inside those regions don’t trigger a visual difference.

When you run another build with visual changes to the app, Percy takes new screenshots. You can then see the comparisons between the two runs on the new build.