Continuous Integration (CI) setup

👍
Covered in this doc

List of supported CI services

Overview of how our CI integrations work

Percy works best when integrated into your CI workflow, running continuously alongside your test suite. Percy integrates with all common CI providers and can be configured for custom environments.

Supported CI integrations

You can integrate Percy with the following CI services:

Click each CI service to see step-by-step integration instructions.

Don't see your CI service? We're constantly adding support for CI services. Reach out to support to see if yours is on the way.

How it works

Percy is designed to integrate with your tests and CI environment to run continuous visual reviews. After you add Percy to your tests and your CI environment, Percy starts receiving and rendering screenshots every time a CI build runs.

Configure CI environment variables

To enable Percy, configure the environment variable, 'PERCY_TOKEN', in your CI service. This is our write-only API token unique for each Percy project and should be kept secret.

You can find PERCY_TOKEN in your project settings.

Start and stop Percy CLI

There are two ways to start and stop Percy CLI from your CI setup:

Percy execution command

Add the percy exec command in your configuration file (for example, make file, package.json, or req.txt) to start Percy, as shown below:

{
  "scripts": {
    "test": "percy exec -- node test.js"
  }
}

test:
	$(NPM)/percy exec -- mvn compile exec:java -Dexec.mainClass="io.percy.examplepercyjava.java"

In your pipeline script, make changes similar to the following:

- script: |
    npm install --save-dev @percy/cli
  displayName: 'install cli'

- script: |
    npm install
    npm run test
  displayName: 'npm install and test'
  env:
    PERCY_TOKEN: $(PERCY_TOKEN)

Percy start and stop commands

If you cannot use the percy exec command in your configuration file, use the percy exec:start and percy exec:stop commands.

In this case, your configuration file looks as follows:

{
  "scripts": {
    "test": "node test.js"
  }
}

test:
 mvn compile exec:java -Dexec.mainClass="io.percy.examplepercyjava.java"

And your pipeline script should be similar to the following:

- script: |
    npm install --save-dev @percy/cli
  displayName: 'install cli'

- script: |
    npx percy exec:start &  # use "start /B npx percy exec:start" for windows agent
  displayName: 'start cli'
  env:
    PERCY_TOKEN: $(PERCY_TOKEN)

- script: |
    npm install
    npm run test
  displayName: 'npm install and test'

- script: |
    npx percy exec:stop
  displayName: 'stop cli'

The above script performs the following actions:

Install Percy CLI.
Start Percy CLI with PERCY_TOKEN.
Run your tests.
Stop Percy CLI.

Parallel test suites

Percy automatically supports most parallelized test environments. Snapshots are pushed from your tests to Percy and rendered for you to review in the same Percy build, no matter if your tests are run in different processes or even on different machines. You can also simply configure Percy to support complex parallelization setups.