How to Set Up Percy Visual Testing in CI

Percy renders snapshots in its own cloud browsers, so CI only needs @percy/cli, a percy exec wrapper, and the PERCY_TOKEN secret.

Install @percy/cli and the matching SDK, wrap your test runner with percy exec --, and expose PERCY_TOKEN so uploaded snapshots appear in the Percy dashboard.

Steps

Install @percy/cli and the SDK for your framework.
Add percy snapshot calls (or use the framework integration).
Wrap the run with percy exec -- <test command>.
Set the PERCY_TOKEN repository secret.

Install

Terminal

npm install --save-dev @percy/cli @percy/playwright

Workflow

.github/workflows/ci.yml

jobs:
  percy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npx percy exec -- npx playwright test
        env:
          PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}

Gotchas

Without percy exec, the CLI has no running agent and snapshots are dropped.
A missing PERCY_TOKEN makes the CLI skip uploads instead of failing loudly.