Join our Discord
Run a sample build with Maestro
Run a sample Percy build with Maestro web flows to catch visual differences on your website.
This guide walks you through running your first Percy build with Maestro using our sample repository.
Prerequisites
Before you start, ensure you have the following installed:
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.
Run your sample build
To clone the sample project, run two builds, and view the visual differences in Percy, follow these steps:
Clone the sample project
Clone the sample project and install its dependencies:
This installs the @percy/maestro-web SDK and the Percy CLI. The Maestro flows are in the flows/ folder, and the project-level Percy settings, such as snapshot widths, are in .percy.yml.
Create a Percy project
Sign in to Percy, create a new project, and select Web as the project type. Percy generates a unique project token. Set it as an environment variable:
export PERCY_TOKEN="your-percy-token"
For details on creating a project, see Create a Percy project.
Generate the first build
Run the flows/test-cases-labels.yaml flow. The flow opens the Percy website and takes three snapshots, grouped into two test cases:
The command wraps maestro test with percy-maestro-web exec, which starts the Percy CLI, uploads each snapshot, and finalizes the build when the flow exits. On completion, the CLI output shows the build URL. There are no visual comparisons yet.
Introduce a visual change
Open flows/test-cases-labels.yaml and add a PERCY_CSS override to the homepage-top snapshot. Percy applies this CSS at render time, so the snapshot changes without editing the website:
Generate the second build
Run the flow again:
Percy takes new snapshots, uploads them, and compares them with the snapshots from the first build.
View the results
- Open your project dashboard to view your builds.
- Open the second build to view the visual differences compared to the first build.
Percy highlights the changed heading in the homepage-top snapshot. To group the snapshots by test case, use the Group snapshots by filter and select Test cases. Use the options on the screen to review the changes on different browsers and widths.
Explore other sample flows
The sample project includes a flow for each Percy feature. To run a flow, use its command from the following table:
| Feature | Flow file | Command |
|---|---|---|
| All features in one build | flows/web-percy.yaml |
npm run test-web |
| Multi-page navigation and cookies | flows/auth-flow.yaml |
npm run test-auth |
| Ignore, layout, and Intelli Ignore regions | flows/regions-demo.yaml |
npm run test-regions |
Regions built with createRegion()
|
flows/coded-regions.yaml |
npm run test-coded-regions |
| Responsive DOM capture per width | flows/responsive-demo.yaml |
npm run test-responsive |
| Scoped snapshot of a DOM subtree | flows/scoped-demo.yaml |
npm run test-scoped |
| Test cases and labels | flows/test-cases-labels.yaml |
npm run test-cases-labels |
| Cross-origin iframe capture | flows/cors-iframe.yaml |
npm run test-cors |
The test-cors flow requires Python 3.
Summary
You’ve run your first Percy build with Maestro. As you’ve seen, Percy captures visual differences on your website that functional tests alone don’t detect.
To use Percy with your own Maestro flows, integrate Maestro with Percy.
Related topics
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!