To run Percy visual tests in GitHub Actions, install the Percy CLI and the SDK for your test framework, add snapshots at the page states you want to compare, and run the test command through percy exec. Save the Percy project token as a GitHub Actions secret and expose it to the workflow as PERCY_TOKEN—never commit it to your repository.
How the Percy workflow fits together
Your browser tests navigate and interact with the application; Percy’s framework SDK records named snapshots at selected states, and the Percy CLI wraps the test run and uploads the snapshots to the project associated with your token. Percy then compares them with a baseline so you can review visual changes. See the BrowserStack guide to Percy in GitHub Actions.
This guide covers browser tests using Playwright or Cypress. If you want to compare generated static pages rather than states reached by tests, Percy also documents a separate percy snapshot workflow for a built directory.
Set up the Percy project token in GitHub
- Create or select a Percy web project and retrieve its project token.
- In your GitHub repository, open Settings → Secrets and variables → Actions, choose New repository secret, and save the token as
PERCY_TOKEN. If your repository uses an environment-specific secret, make sure the job declares that environment. - Expose the secret only to the step that runs Percy by mapping it to the
PERCY_TOKENenvironment variable. Do not place the token directly in workflow YAML, application code, or a command-line argument.
Percy’s GitHub Actions integration guide and SDK examples use PERCY_TOKEN to associate CI uploads with a Percy project.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minute#1 Best Overall
- CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
- WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
- A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents
Choose the integration for your test suite
Playwright
Install the CLI and Playwright SDK as development dependencies:
npm install --save-dev @percy/cli @percy/playwright
Import percySnapshot in a Playwright test and call it after the page reaches a state worth comparing:
import { test } from '@playwright/test';
import percySnapshot from '@percy/playwright';
Rank #2
- CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
- SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
test('product page visual check', async ({ page }) => {
await page.goto('https://example.com/products/widget');
await percySnapshot(page, 'Product page');
});
Replace the example URL with a page your test can access and give snapshots stable, useful names. The Percy Playwright client library also documents a drop-in option for existing toHaveScreenshot() assertions. Check its stated version requirements against your installed Playwright and Percy packages before adopting that route.
Cypress
Install the CLI and Cypress SDK:
npm install --save-dev @percy/cli @percy/cypress
Import the SDK in your Cypress support file, following the current setup instructions in the Percy Cypress SDK repository. Then call cy.percySnapshot() at a meaningful point in a test, for example after navigating and asserting that the page has loaded. Run the Cypress command under percy exec so the snapshots are uploaded.
Add a GitHub Actions workflow
Use the workflow below as a template for an npm project whose Playwright tests run with npx playwright test. It maps the repository secret to the Percy step rather than storing the token in the file:
Recommended Free Tools
Rank #3
- Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
- Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
- Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
- In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
- Ultra-thin bezels: Maximize your viewing experience with thin bezels.
name: Visual tests
on:
push:
pull_request:
jobs:
percy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- name: Run Percy visual tests
run: npx percy exec -- npx playwright test
env:
PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}
The action and Node versions shown here are example pins, not a claim that they are the only compatible or permanently current choices. Check current GitHub Actions and runtime support, and keep the CLI, SDK, runtime, and actions maintained. BrowserStack’s Percy Actions example is useful for understanding the workflow shape, but its displayed version pins are older.
Use Cypress instead
Keep the checkout, Node setup, dependency installation, and secret mapping, but change the run command to your Cypress script, commonly:
npx percy exec -- npx cypress run
If your repository uses npm scripts or a custom Cypress configuration, pass the project’s usual command and options after percy exec --.
Rank #4
- CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
- SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
- MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
- KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
- INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient
Capture a static build directory
For generated HTML output, build the site first, then use Percy’s documented percy snapshot command on the output directory instead of adding SDK calls to browser tests. Follow the exact CLI syntax and directory requirements in the Percy GitHub Actions documentation; this workflow compares static output, not interactive states visited by Playwright or Cypress.
Establish and review the baseline
On the first successful run, check the Percy dashboard for the new build and establish or approve the baseline as required by your project workflow. Later builds compare snapshots against that baseline and present visual changes for review. Do not treat the first upload as evidence that future changes are already approved.
For Playwright setups relying on automatic baseline discovery or seeding, verify that Percy is reading the intended Playwright configuration. The Percy example Playwright project notes that discovery reads Playwright’s default config; a custom config path can interfere with mapping screenshots during first-run seeding. The example also describes BrowserStack session requirements for its Automate drop-in, so those requirements apply to that integration path rather than every Percy Playwright workflow.
Troubleshoot missing or unexpected Percy builds
- No Percy build or snapshots appear: Confirm the command is wrapped as
npx percy exec -- <test command>, that the job receivesPERCY_TOKEN, and that the secret belongs to the Percy project you intend to update. The SDKs document that snapshots are disabled when tests run without Percy execution and token configuration; see the Playwright library and Cypress SDK. - The test passes but a page is absent from the build: Ensure the test actually reaches the snapshot call and that the call follows the relevant navigation, rendering, and interaction. A snapshot call placed before the target state will capture the wrong point in the test.
- First-run Playwright baseline mapping fails: Check whether your project uses a non-default Playwright config path and whether Percy’s discovery is reading that path. The example project documents default-config discovery as a relevant assumption.
- An existing screenshot assertion does not integrate as expected: Verify the Playwright, Percy SDK, and drop-in version requirements together before switching from
percySnapshotto thetoHaveScreenshot()integration. Compatibility is version-sensitive. - The first build is visible but comparisons are not useful yet: Review and establish the baseline in Percy before relying on later builds for change review.
- A workflow copied from an example stops working after updates: Check the current compatibility and support for the pinned GitHub Actions, Node runtime, CLI, and framework SDK. Example repository pins describe that sample, not a universal current matrix.
Performance, reliability, and cost considerations
The cited integration instructions establish how to capture and upload snapshots, but do not provide a quantitative speed or cost comparison between Playwright, Cypress, and static-directory capture. In practice, choose the workflow that matches the states you need to review and the framework your project already runs; avoid adding duplicate snapshots for states that do not answer a review question.
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 →Best Value
- 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
- 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
- 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.
CI reliability depends on the test command completing and the Percy wrapper receiving its token. Keep dependencies and action versions intentionally maintained, and make baseline approval part of the team’s visual-review process. The supplied Percy setup materials do not establish a universal runtime, upload SLA, or price figure, so those should not be inferred from the integration examples.
Or skip the browser setup
If you need screenshots through a direct API call rather than Percy snapshots attached to a browser-test build, ScreenshotNeo is a website screenshot API and MCP server for developers. Its one-call GET endpoint can return an image or PDF; its response headers identify the page verdict and billing status. It is a different workflow from Percy’s baseline-based visual testing.
For example, save a screenshot of a page as WebP with cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
Quick Recap
See the ScreenshotNeo API documentation for request options and authentication. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. An 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 the 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.
