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.

Clone the sample project

Clone the example project, install its dependencies, and copy the SDK files into the workspace:

The project includes a sample Android app, and the iOS flow uses the built-in Settings app, so you don’t need an app of your own. It provides Android flows at flows/screenshot.yaml and flows/regions.yaml, and iOS flows at flows/ios/launch.yaml and flows/ios/regions.yaml.

For Android, install the sample app on your connected device or emulator:

Create an App Percy project

Sign in to Percy, create a new project, and select App as the project type. Percy generates a unique project token that starts with app_. Set it as an environment variable:

export PERCY_TOKEN=<your-percy-token>

$Env:PERCY_TOKEN="<your-percy-token>"

set PERCY_TOKEN=<your-percy-token>

On macOS, also set the following so Maestro binds over IPv4:

Run the flow through App Percy

To run the sample flow, wrap the maestro test command with percy app:exec. This starts the Percy CLI, creates a build, captures each screenshot, and finalizes the build when the flow exits.

For Android, run the regions flow against your connected device or emulator:

For iOS, boot a simulator first, then run the iOS regions flow:

The command auto-resolves the screenshot output directory and injects the Percy CLI address, so you don’t set those yourself.

View the results

When the flow finishes, the CLI prints the build URL. Open it to review the snapshots in your App Percy project. The snapshots captured by the regions flow show the masked areas, so changes inside those regions don’t trigger a visual difference.

Approve the baseline in the Percy dashboard. When you run the flow again with visual changes, Percy compares the new snapshots against this baseline and shows the differences on the new build.