Use BrowserStack’s SDK route to run functional tests on Automate and coordinate Percy visual tests in the same pipeline. Create a Percy Web App project, match its project name in browserstack.yml, enable Percy and Automate, choose automatic or manual capture, then run the suite and review the resulting Percy build. The exact install command and snapshot call depend on your language and test framework, so start with BrowserStack’s current SDK integration guide and verify that your framework is supported.
Choose the integration route and confirm framework support
BrowserStack’s SDK is the natural starting point when you want functional tests executed through Automate and Percy visual tests configured as part of the same workflow. Check BrowserStack’s available SDK integrations for your language and framework before changing the project. Its listed examples include WebdriverIO, Java test frameworks, and NUnit; supported frameworks may change.
The alternative is Percy’s own SDK. BrowserStack describes that route as suitable when a team needs direct Percy controls such as DOM transformations, responsive snapshots, or advanced Percy configuration. Choose based on framework compatibility and the controls your test suite actually needs; the BrowserStack SDK and Percy SDK are not interchangeable configurations. See BrowserStack’s integration options.
Create the Percy project and configure BrowserStack
- Create a Percy project. In Percy, create a Web App project and select the BrowserStack SDK / Automate path available in the current interface. Use a stable project name; the configured
projectNamemust correspond to the project where snapshots should appear. Follow BrowserStack’s project setup guide for the current UI. - Configure the SDK. In your project’s
browserstack.yml, setpercy: true, setprojectNameto the matching Percy project name, ensure Automate is enabled withbrowserstackAutomation, and choosepercyCaptureModeasautoormanual. - Keep credentials out of source control. Supply BrowserStack and Percy credentials using the secret-management mechanism recommended for your environment. Do not commit access tokens in the YAML file or test code. Follow the current SDK documentation for required credential names and setup; the precise requirements can vary by SDK and framework.
- Install and invoke the correct framework SDK. Use the official guide for your chosen language and framework for installation, dependencies, and test-runner commands. There is no single universal install command or screenshot method that applies to every supported framework.
BrowserStack’s SDK works from project configuration and can also support Automate capabilities such as cross-browser and parallel testing; see How BrowserStack SDK works for its SDK overview and the framework-specific guide for your setup.
#1 Best Overall
Choose automatic or manual Percy capture
| Mode | How it works | Best fit |
|---|---|---|
auto |
Captures at supported predefined events. | Suites where broad capture at the SDK’s built-in points is useful and minimal test-code changes are preferred. |
manual |
You invoke the framework’s documented screenshot method at deliberate checkpoints. BrowserStack’s example is PercySDK.screenshot(driver, name); adapt it to your SDK and language. |
Tests where only named states or carefully chosen user-flow checkpoints should become snapshots. |
For manual mode, place the call after the UI reaches the stable state you intend to compare—for example, after navigation and any required interaction or wait. The exact method signature, driver type, and import are framework-specific; copy them from the applicable BrowserStack guide rather than assuming the example is universal. Capture names should make the page or state identifiable during review.
Run the tests and review the Percy build
- Run the suite using the BrowserStack SDK command documented for your framework and configured environment.
- Open the Percy build associated with the test run and inspect its snapshots. Percy highlights visual changes for review.
- Approve intended changes or builds after review. Where repository integration is configured, approvals can update pull-request or commit status.
A successful functional test run only shows that the application behaved as the functional assertions expected; it does not mean visual differences have been reviewed. Percy’s build and snapshot workflow is described in Visual Testing with Percy.
Rank #2
Handle parallel test execution and finalize builds
For workers distributed across machines or containers, Percy needs to group their snapshots into the same build and know when all workers have finished. Percy documents using --parallel for parallel runs and finalizing the build after all workers complete. If finalization is missed, a distributed build can remain in “Receiving” rather than completing.
When multiple processes are parallelized on one machine, use Percy’s shared server approach and stop the server only after all test processes exit. Follow the relevant commands and lifecycle instructions in BrowserStack’s parallel test suites guide; exact invocation depends on the SDK and how the suite is launched.
Rank #3
Troubleshoot common setup problems
- No Percy build or snapshots appear: confirm
percy: true, that the intended capture mode is active, and that the test command actually runs through the configured BrowserStack SDK. Check the current framework integration guide for its required setup and output. - Snapshots appear under the wrong project: compare the Percy project name with
projectNameinbrowserstack.yml; make them match exactly. - Manual mode produces no snapshots: verify that the framework-specific Percy screenshot method is invoked in the test and that it runs after the desired page state is ready. A method example for one language is not a universal API.
- Automate execution is not enabled: check the SDK configuration for
browserstackAutomationand consult the current setup guide for the selected framework. - A parallel build stays in “Receiving”: verify that every worker belongs to the intended parallel build and that the documented finalization step runs after all workers finish. On one machine, keep the shared Percy server running until every parallel process exits.
- A framework or command in a tutorial does not match your project: use BrowserStack’s current supported-framework list and select the guide for your actual language, runner, and SDK. BrowserStack’s interface and supported frameworks can change.
Or skip the browser setup
For a one-off website screenshot rather than a Percy test run, ScreenshotNeo offers a website screenshot API and MCP server. It is not a replacement for Percy build review or BrowserStack Automate execution. Its API takes one GET request with a URL and returns an image or PDF. See ScreenshotNeo and the API documentation.
Quick Recap
Best Value
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes supported cookie banners, popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo’s free plan.
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.
