Migrating to Percy CLI

Overview

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:

$ npx @percy/migrate
? Are you currently using @percy/puppeteer? Yes
? Install @percy/cli? Yes
? Migrate Percy config file? Yes
? Upgrade SDK to @percy/[email protected]?

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:

Attempt to detect your SDK by examining your project’s dependencies.
Install @percy/cli to your project (and uninstall @percy/agent if present).
Migrates any Percy config file to the latest version.
Update your SDK to the latest version (JS SDKs only).
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:

[percy] Warning: It looks like you’re using @percy/cli with an older SDK. Please upgrade to the latest version to fix this warning. See these docs for more info: https://docs.percy.io/docs/migrating-to-percy-cli

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

Code migration completed

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

WIP

Not started

All SDKs done!