How to Run Percy Visual Tests with BrowserStack Automate

Use the BrowserStack SDK to run functional tests through BrowserStack Automate and connect Percy visual tests in the same pipeline. Create a Percy Web project, set its matching projectName and percy: true in browserstack.yml, then choose automatic or manual snapshot capture. Exact installation commands and screenshot calls depend on your language and framework; confirm support and follow its official guide before adding the SDK.

This guide covers the BrowserStack SDK route, which BrowserStack presents as a unified configuration for functional and visual testing. It also explains Percy SDK tradeoffs, snapshot review, parallel builds, and common setup failures.

1. Check framework and language support

Before changing your test runner, check the current BrowserStack SDK framework coverage. Coverage can vary by language-framework combination and capture mode. A combination may support manual snapshots but not automatic capture. Supported frameworks and documentation can change, so do not infer support from another language’s setup.

Find the official BrowserStack Automate setup guide for your framework. Use its install command, test runner integration, driver setup, and configuration conventions. There is no one install command or screenshot API that applies to every framework.

2. Create the Percy project

In Percy, create a project and choose Web App.
Give it a stable name. Use the same name for projectName in your BrowserStack configuration.
Select the BrowserStack Automate or Percy execution route that matches your desired project setup. BrowserStack notes that the execution choice made during project creation cannot be changed later.
Optionally connect a repository and select a baseline-management approach appropriate to your team’s workflow.
Keep the project’s Percy token in your CI secret store or another approved secret manager.

See BrowserStack’s current project creation guide for the dashboard flow and configuration fields.

3. Configure BrowserStack Automate and Percy

Add or update browserstack.yml in the format expected by your BrowserStack SDK version. The essential Percy settings are shown below; merge them into the framework-specific configuration rather than replacing required test or browser settings.

framework: YOUR_FRAMEWORK
# Keep the framework-specific platforms and test settings required by your project.
browserstackAutomation: true
percy: true
projectName: your-stable-percy-project-name
percyCaptureMode: manual

Choose auto or manual for percyCaptureMode. Automatic mode captures at supported predefined events. Manual mode gives the test explicit checkpoint control using the screenshot method documented for the SDK and language. Use the exact project name that receives the snapshots.

Store BrowserStack credentials and Percy credentials in environment variables or CI secrets. Never commit real access keys or project tokens into the repository. The variable names and credential wiring should follow the official setup guide for your framework and SDK.

4. Choose how to capture Percy snapshots

Mode	Best fit	Tradeoff
Automatic	You want broad capture at supported predefined events without adding calls throughout the suite.	Capture depends on framework support and event behavior; verify that generated snapshots correspond to useful states.
Manual	You want snapshots at named, intentional checkpoints such as a completed checkout form or open navigation menu.	You must add calls at the chosen states and ensure the correct page or driver is passed.

BrowserStack’s integration documentation gives PercySDK.screenshot(driver, name) as an example of a manual capture call. Treat it as illustrative: method names, imports, and accepted driver types depend on your SDK and framework. Consult the relevant framework-specific guide for runnable code rather than copying that example into an unrelated stack.

For dependable manual checkpoints, navigate to the page, wait for the application state you intend to compare, dismiss or set overlays consistently, and give each snapshot a stable descriptive name. Capture the same meaningful state on future runs; unstable data and timing can create noisy diffs.

5. Run tests and review the Percy build

Run the suite with the command prescribed by your BrowserStack SDK and test framework. The BrowserStack SDK sends functional sessions to Automate and coordinates visual testing with Percy. After the run, open the corresponding Percy build and inspect its snapshots.

Confirm the build belongs to the intended project and branch or commit.
Review highlighted visual changes in context. Decide whether each change is expected or needs investigation.
Approve intended changes so they can become the appropriate baseline according to your project’s baseline workflow.
Check repository or pull-request status when source-control integration is configured. A passing functional test does not mean the visual changes have been reviewed.

Percy builds are review artifacts: the value comes from examining visual diffs and approving the changes your team intends to accept. See BrowserStack’s Visual Testing with Percy documentation for the build and review workflow.

6. Run parallel tests without leaving builds open

Decide whether workers run across separate machines or containers, or whether multiple test processes share one machine. Percy’s parallel handling differs between these cases.

Workers on multiple machines or containers

Group worker output into the same Percy build and finalize only after every worker has finished. Percy documents using percy exec --parallel for each worker and then running percy build:finalize after all workers complete. The following is a generic shape, not a replacement for the BrowserStack SDK command your framework needs:

# Worker job, repeated for each shard
npx percy exec --parallel -- YOUR_BROWSERSTACK_TEST_COMMAND

# Finalizer job, with the same Percy project credentials
npx percy build:finalize

Configure CI dependencies so the finalizer runs after all shards. If your CI provider is not automatically recognized, Percy’s parallel workflow requires a unique PERCY_PARALLEL_NONCE for the run. Avoid reusing a nonce across rebuilds.

Parallel processes on one machine

Use Percy’s shared server approach when the processes on one host need to send snapshots to one Percy server. Start it before the tests and stop it only after all test processes exit. Follow the current parallel test suite instructions for exact commands and environment requirements.

BrowserStack SDK or Percy SDK?

Choice	Use it when	Consider
BrowserStack SDK	You want functional tests on Automate and Percy visual testing coordinated through a unified configuration.	Confirm framework support and whether its automatic or manual capture coverage matches your needs.
Percy SDK	You need direct Percy controls in test code, such as DOM transformations, responsive snapshots, or advanced Percy configuration.	You will integrate Percy directly with the functional test framework; this is a different setup from the unified BrowserStack SDK flow.

BrowserStack describes the BrowserStack SDK as the route for a unified Automate and Percy pipeline, while the Percy SDK exposes direct visual-testing controls. Check the current integration options and feature compatibility before choosing. Do not assume the two SDKs support identical features or have interchangeable APIs.

Do-it-yourself screenshot checks outside Percy

Percy snapshots are designed for visual comparisons inside a test workflow. For a one-off rendered page image, a screenshot API can avoid maintaining a browser installation and capture script. ScreenshotNeo is a website screenshot API and MCP server; it accepts a URL and returns PNG, JPEG, WebP, or PDF. See ScreenshotNeo for the service overview. This is a separate capture workflow and does not replace Percy’s build review process.

Or skip the browser setup

Make one request to capture a page with ScreenshotNeo. The examples below use the documented API endpoint; replace the URL and put your API key in a secret, not committed source code. See the ScreenshotNeo API documentation for parameters.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

In Node.js environments without Bun, write the response bytes with the runtime’s filesystem API. ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses indicate the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.

Troubleshooting

Symptom	Likely cause	Fix
No Percy build or snapshots appear	`percy` is disabled, the project name is wrong, credentials are unavailable, or the test command bypasses the SDK.	Check the SDK’s config discovery location, set `percy: true`, match the exact project name, verify CI secrets, and use the framework’s documented command.
Automatic mode captures nothing	The framework-language combination may only support manual capture, or the expected events are not occurring.	Check the current coverage table. Switch to manual mode if supported and add documented calls at stable checkpoints.
Manual capture method errors	The example method does not match the language, SDK, or driver type.	Use the framework-specific BrowserStack guide for import, method name, and expected driver object; do not treat the generic example as universal.
Snapshots show the wrong state	Capture happens before navigation or asynchronous rendering is complete, or the wrong tab/window is active.	Wait for an application-specific ready condition before capture, confirm the active page, and use stable test data.
Unexpectedly noisy visual diffs	Dynamic content, animation, timestamps, ads, or inconsistent viewport/state affects rendering.	Make test state and content deterministic, capture at the same checkpoint, and apply only the framework or Percy stabilization options documented for your setup.
Parallel build remains “Receiving”	A worker did not finish or the distributed build was never finalized; a configured expected worker count may also be unmet.	Ensure every shard uses the same build grouping, inspect failed workers, then finalize after all workers complete. Check nonce uniqueness and parallel settings.
Snapshots go to the wrong project	`projectName` differs from the Percy project name or the wrong project token is injected.	Align the configuration and token with the intended project, then rerun and verify the build destination.

Performance, reliability, and cost considerations

Runtime: Percy adds snapshot collection and upload work to the visual workflow. Capture only states that answer a review question; use supported parallel execution when suites need sharding.
Reliability: Keep project identity and credentials explicit, make snapshots deterministic, and ensure parallel finalization runs even when CI jobs are split. Report visual review separately from functional pass/fail.
Coverage: Browser combinations and capture support depend on the chosen SDK and project setup. Confirm current framework coverage and execution options rather than assuming all combinations are available to every integration.
Cost: The research sources here do not establish current BrowserStack or Percy pricing, quotas, or plan limits. Check the vendors’ current plan details for your account and expected Automate and visual-testing volume.
Alternative capture costs: ScreenshotNeo bills only clean shots; its response headers identify page verdict and billing. Its published plans include 1,000 free monthly shots, then paid tiers starting at $5 for 3,000. This is pricing for ScreenshotNeo captures, not Percy or BrowserStack Automate.

FAQ

Does Percy replace BrowserStack Automate?

No. In this workflow, Automate runs the functional browser sessions and the BrowserStack SDK connects Percy visual testing to the pipeline.

Do I need to write a snapshot call in every test?

Not necessarily. Supported combinations can use automatic capture; manual capture is for deliberately selected checkpoints.

Can a passing test suite approve visual changes?

No. A functional pass and review of Percy’s visual diffs answer different questions. Review and approve intended visual changes in the Percy build.

Can I use ScreenshotNeo images as Percy baselines?

The documented ScreenshotNeo API returns page captures; the research for this guide does not establish a Percy integration. Use Percy’s supported SDK workflow for Percy builds and comparisons.