Integrate Maestro with Percy

Learn how to integrate Maestro with Percy to run visual tests on your Maestro web flows.

This page guides you through integrating Maestro with Percy, from creating a Percy project to capturing your first snapshot.

Use the @percy/maestro-web SDK to integrate Percy visual testing with your Maestro web test suite. This is the only Percy SDK you need to install for Maestro, the steps below cover the full setup.

Prerequisites

Before you begin, ensure you have the following installed:

• Node 16 or later
• Java 17 or later
• Maestro CLI latest version

Set the JAVA_HOME environment variable before running your Maestro flow. If you encounter a JAVA_HOME not set error, follow the OS-specific setup steps in the Maestro installation guide.

Steps

Follow these steps to set up the Percy - Maestro integration:

Step 1: Create a Percy project.

1. Sign in to Percy.
2. Create a new project, select Web as the project type, and name your project.
3. Once you create the project, Percy generates a unique project token. Copy the token. Use it as an environment variable in the next step.

Step 2: Set the Percy token as an environment variable so the Percy CLI can authenticate with your project. Choose the command for your operating system and shell:

export PERCY_TOKEN="your-percy-token"

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

set PERCY_TOKEN=your-percy-token

Step 3: Install Percy dependencies using the following command:

npm install --save-dev @percy/maestro-web @percy/cli

This installs the SDK and the Percy CLI.

Step 4: Update your Maestro flow.

To capture a Percy snapshot at a specific point in your Maestro flow, add a runScript: block that points to the SDK’s snapshot script.

Minimum flow:

url: https://example.com
---
- launchApp
- runScript:
    file: ../node_modules/@percy/maestro-web/scripts/snapshot.js
    env:
      NAME: "Home page"

NAME is the only required field, every other option is read from .percy.yml (Step 5) or can be overridden per-snapshot.

Multi-snapshot flow with overrides:

url: https://example.com
---
- launchApp
- runScript:
    file: ../node_modules/@percy/maestro-web/scripts/snapshot.js
    env:
      NAME: "Home"
      TEST_CASE: "homepage-suite"
- tapOn: "Sign in"
- inputText: "user@example.com"
- tapOn: "Continue"
- runScript:
    file: ../node_modules/@percy/maestro-web/scripts/snapshot.js
    env:
      NAME: "Sign-in form"
      WIDTHS: "375,1280"
      LABELS: "auth,critical-path"

Step 5: Configure project defaults.

Create a .percy.yml at your project root:

version: 2
snapshot:
  widths: [375, 1280]
  minHeight: 1024

Per-snapshot env: overrides take precedence over .percy.yml defaults. For more information, refer to Percy SDK configuration.

Step 6: Run Percy with your Maestro flow:

percy-maestro-web exec -- maestro test flow.yaml

Sample output:

[percy] Percy has started!
[percy] Created build #142
[percy] Snapshot taken: Home page
[percy] Snapshot taken: Sign-in form
[percy] Finalized build #142
[percy] Done!

Percy renders each snapshot in Chrome, Safari, Firefox, and Edge across every configured width.

Step 7: A build link appears in the CLI output. Click the link to view your Percy snapshots.

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

Per-snapshot overrides

Names are case-insensitive and accepted with or without the PERCY_SNAPSHOT_ prefix.

Once set up, Maestro flows that include the Percy snapshot script will automatically capture and upload visual snapshots to Percy, allowing you to review visual changes alongside your functional tests in the Percy dashboard.

Related topics

• Percy CLI commands
• SDK configuration (.percy.yml)
• Regions in Percy
• Synchronous comparison results
• Integrate Percy with GitHub Actions