Migrate to Percy CLI

A guide to migrating from @percy/agent to percy cli, which serves as Percy’s next-generation software development kit (SDK) toolchain.

Percy CLI is the backbone of Percy’s next generation SDK toolchain and builds upon what was learned from @percy/agent (powering the outgoing Percy SDKs). Percy CLI is more extensible and breaks core pieces into individual packages (for extensibility). (If you’re curious, you can find a full list of new packages here).

The JS and non-JS Percy SDKs will have slightly different migration paths. This is due to @percy/agent being a direct dependency on current JS SDKs. Non-JS SDKs have a slightly different upgrade path since @percy/agent was installed manually during setup.

Automated migration with @percy/migrate

We have built a package to help automate migrating to the new CLI toolchain. Migrating can be done by running the following commands and following the prompts:

Each step can be performed manually without this tool to achieve the same outcome (described in the sections below). At a high level, @percy/migrate will:

1. Attempt to detect your SDK by examining your project’s dependencies.
2. Install @percy/cli to your project (and uninstall @percy/agent if present).
3. Migrates any Percy config file to the latest version.
4. Update your SDK to the latest version (JS SDKs only).
5. Maybe prompts to run code mods on specific files.

Non-JS SDK migration

Upgrading a non-JS Percy SDK can be done in a few steps:

• Uninstall @percy/agent: npm uninstall @percy/agent
• Install @percy/cli: npm install --save-dev @percy/cli
• If you have a Percy config file, migrate it to v2: npx percy config:migrate
• Upgrade your Percy SDK to the latest version (pip, mvn, gem, etc)

It’s possible to only replace @percy/agent with ` @percy/cli` in these SDKs, but you will see this warning logged until you upgrade the SDK package:

JS SDK migration

Upgrading a JS Percy SDK can be done in a few steps. There might be additional steps for the SDK you are currently using. These can be found in that specific SDK’s docs.

• Install @percy/cli: npm install --save-dev @percy/cli
• If you have a Percy config file, migrate it to v2: npx percy config:migrate
• Upgrade your Percy SDK to the latest version
• Check your SDK’s docs for additional steps, like package export changes

Overall breaking changes

Parallel builds

Percy CLI no longer automatically sets PERCY_PARALLEL_TOTAL based on detected CI container count. The new recommended way to is pass the --parallel flag to Percy CLI and then call percy build:finalize after all parallel tests have completed.

If you manually set PERCY_PARALLEL_TOTAL to a specific number, builds should continue to work as they did before.

Current migration status

All Percy SDKs are now using Percy CLI

This is the current status Percy SDKs migration to @percy/cli (and away from @percy/agent). You can also look at this GitHub issue to double check.

Completed

• Puppeteer
• WebdriverIO
• Protractor
• Nightmare
• Nightwatch
• TestCafe
• Selenium for Java
• Selenium for JavaScript
• Cypress
• Ember
• Capybara
• Storybook
• Gatsby

Code migration completed

These packages have betas released (check the GitHub README if you’d like to use the beta)

• N/A

WIP

• N/A

Not started

• All SDKs done!