Free tools Windows power users keep installed
One-click scans. No signup required.
For a monorepo with multiple web apps, use Percy’s documented Cypress workflow inside each app’s test job: install the Percy CLI and Cypress SDK, call cy.percySnapshot() at stable UI states, provide that app’s project token as PERCY_TOKEN, and run Cypress through npx percy exec -- cypress run. Percy’s documented setup establishes the capture and token flow; it does not set a universal rule for whether multiple apps should share a Percy project or how to coordinate parallel multi-app builds. Treat those as choices to validate for your current Percy account and CLI.
How Percy fits a monorepo with multiple web apps
Percy’s documented Cypress integration uses the Percy CLI to wrap a Cypress run and the Cypress SDK to take snapshots from tests. Percy associates a run with a project through its project token, supplied as PERCY_TOKEN. In a monorepo, the key implementation task is to make the mapping between each app’s test job and its intended Percy project explicit.
As an Amazon Associate I earn from qualifying purchases.
The official Cypress guide documents this workflow, but does not prescribe a monorepo topology. Separate app-level project or configuration boundaries are a reasonable engineering choice when apps need independent baselines, owners, or review schedules. A shared project can make sense when the team deliberately wants a shared baseline and approval lifecycle. Confirm that the intended setup is supported by the current Percy CLI and your account rather than treating either topology as a Percy rule. Percy’s Cypress documentation
Map each app’s test and Percy ownership
Before changing CI, write down how every app is tested and where its Percy results should go. Keep the mapping in app-specific CI configuration or a repository document that job maintainers can update.
| For each app, record | Why it matters |
|---|---|
| Workspace or app directory | Identifies where its test command and dependencies are managed. |
| Test framework and command | Determines which Percy SDK and test-runner command apply. |
| Deployment URL or base URL | Clarifies which app environment the tests exercise. |
| Percy project and token owner | Connects the CI job to the intended project without ambiguity. |
| CI job and review owner | Makes failures and proposed baseline changes attributable. |
Use the table to decide whether apps need independent projects or can share one intentionally. Compare baseline independence, reviewer ownership, secret management, snapshot-name collisions, and failure attribution. Those are design considerations, not documented Percy requirements.
Install Percy in the relevant workspace
For Cypress, Percy’s guide shows installing the CLI and Cypress SDK as development dependencies:
npm install --save-dev @percy/cli @percy/cypressLoad the Cypress integration in the support setup used by that app’s tests:
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →import '@percy/cypress'Place the dependencies according to your package manager and workspace conventions. Whether dependencies are hoisted or installed in an app package depends on the monorepo setup; the Percy guide does not prescribe package-manager-specific workspace configuration.
Add named snapshots at stable app states
Use the app’s existing Cypress tests to navigate to a meaningful, reproducible state before taking a snapshot. For example:
cy.visit('/account/settings')
cy.get('[data-testid="settings-form"]').should('be.visible')
cy.percySnapshot('Account settings — loaded form')The URL and selector above are illustrative; replace them with routes and elements from your app. Percy’s Cypress guide recommends controlling page state and data, keeping snapshot scope purposeful, naming snapshots clearly, avoiding dynamic content, and reviewing baseline changes deliberately. Apply those practices to each app’s visual coverage:
- Use fixtures or controlled test data so the same test does not render different content on each run.
- Wait for the UI activity relevant to the state being captured to finish instead of snapshotting during a transient loading state.
- Avoid volatile timestamps, randomized content, and animations that create noisy diffs.
- Prefer critical pages and components over taking snapshots of every possible state.
- Choose names that identify the page and state; include the app name when several apps share a project and names could collide.
Route each CI run to the intended Percy project
Store the project token in your CI secret manager and expose the matching token as PERCY_TOKEN only to the job for that app. Percy’s documented setup uses this variable to associate the run with a project. Never commit a real token to source control or place it in a checked-in example.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsMake the app-to-token mapping visible in job configuration. If a shared workflow is used, ensure the calling app supplies the correct secret rather than relying on an implicit default that could send snapshots to the wrong project.
Run Cypress through the Percy CLI
The documented command for the Cypress integration is:
Rank #4
npx percy exec -- cypress runRun it from the appropriate app workspace with that job’s PERCY_TOKEN. For example, an app-level script could be:
{
"scripts": {
"test:visual": "percy exec -- cypress run"
}
}Then invoke the script from your CI job in the app’s workspace, using your normal workspace command. The script is only an example; package-manager-specific workspace syntax varies, and Percy’s guide does not define a universal monorepo command.
For several apps, orchestrate the app-level jobs separately or through a shared workflow that passes each app’s test command and secret explicitly. If jobs run simultaneously, or a suite is sharded, verify the current Percy CLI’s supported mechanism for build or parallel-run coordination. The reviewed Percy documentation does not establish general multi-app parallel-build semantics, so do not assume that separate jobs will automatically be grouped or attributed as intended.
Best Value
Review builds and baseline changes by app
Review the Percy build produced by the app’s job, using the project boundary and snapshot names to identify what changed. Approve only visual changes that have been reviewed as intentional. Clear ownership and recognizable names are particularly useful when a shared project is used, because project context alone may not identify the app or responsible team.
Cross-host assets: treat old configuration as version-sensitive
A historical Percy changelog describes allowing asset discovery from additional hostnames with agent.asset-discovery.allowed-hostnames and says the setting requires @percy/agent v0.10.0 or later. This is a legacy, version-qualified example, not a guarantee that the same syntax is current. If an app loads assets from another hostname, check the documentation for your installed Percy CLI and SDK before relying on that setting. Percy changelog
Or skip the browser setup
If the task is to capture website pages rather than run visual regression tests through Cypress, ScreenshotNeo is a separate website screenshot API and MCP server for developers. A single GET request can return a PNG, JPEG, WebP, or PDF; it is not a replacement for Percy’s baseline review workflow.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Quick Recap
For example, using cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. It removes cookie banners, popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed; and its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up free for ScreenshotNeo.
Troubleshooting Percy in a multi-app repository
- A run appears under the wrong Percy project: check which CI secret the app job exposes as
PERCY_TOKEN, and make the app-to-token association explicit. - No Percy snapshots appear: confirm the Cypress support setup loads
@percy/cypress, the test reachescy.percySnapshot(), and the run usesnpx percy exec -- cypress run. - Snapshots differ on otherwise unchanged code: stabilize fixture data and page state, wait for relevant UI activity, and remove or control volatile content and animation.
- Snapshot names are hard to attribute: add app, page, and state context to names, especially if apps share a project.
- Parallel jobs do not behave as expected: do not infer build grouping or parallelization behavior from the basic Cypress command. Check current CLI documentation for the installed version and validate the account/CI configuration.
- External-host assets are absent: verify current documentation before using the historical
allowed-hostnamessyntax; the changelog reference is old and version-specific.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
