Migration steps

Automatically with @percy/migrate

We 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:

This will automatically run the changes described below for you.

Manually

In v1.x there wasn’t a default export of the package (only a named export). With v2.x the named export is removed and there is only a default export.

If you have a previous Percy configuration file, migrate it to the newest version with the config:migrate command:

Automatically with @percy/migrate

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

This will automatically run the changes described below for you.

Manually

If you’re coming from a pre-3.0 version of this package, make sure to install @percy/cli after upgrading to retain any existing scripts that reference the Percy CLI command.

If you’re coming from 2.x the health check task, @percy/cypress/task, is no longer needed and no longer exists. You should remove this task from your cypress/plugins/index.js file.

If you have a previous Percy configuration file, migrate it to the newest version with the config:migrate command:

Automatically with @percy/migrate

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

This will automatically run the changes described below for you.

Manually

If you’re coming from a pre-3.0 version of this package, make sure to install @percy/cli after upgrading to retain any existing scripts that reference the Percy CLI command. You will also want to uninstall @percy/agent, as it’s been replaced by @percy/cli.

If you have a previous Percy configuration file, migrate it to the newest version with the config:migrate command:

Automatically with @percy/migrate

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

This will automatically run the changes described below for you.

Manually

If you’re coming from the @percy/seleniumjs package, make sure to uninstall that package first before installing this one.

Now you can safely install @percy/selenium-webdriver and @percy/cli.

If you’re coming from a pre-1.0 version of this package, make sure to install @percy/cli after upgrading to retain any existing scripts that reference the Percy CLI command.

If you have a previous Percy configuration file, migrate it to the newest version with the config:migrate command:

Automatically with @percy/migrate

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

This will automatically run the changes described below for you.

Manually

If you’re coming from a pre-2.0 version of this package, make sure to install @percy/cli after upgrading to retain any existing scripts that reference the Percy CLI command.

If you’re coming from a pre-2.0 version of this package, the percySnapshot function is now the default export.

If you have a previous Percy configuration file, migrate it to the newest version with the config:migrate command:

Automatically with @percy/migrate

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

This will automatically run the changes described below for you.

Manually

If you’re coming from a pre-2.0 version of this package, make sure to install @percy/cli after upgrading to retain any existing scripts that reference the Percy CLI command.

If you have a previous Percy configuration file, migrate it to the newest version with the config:migrate command:

Automatically with @percy/migrate

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

This will automatically run the changes described below for you.

Manually

If you’re coming from a pre-2.0 version of this package, make sure to install @percy/cli after upgrading to retain any existing scripts that reference the Percy CLI command.

If you have a previous Percy configuration file, migrate it to the newest version with the config:migrate command:

Automatically with @percy/migrate

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

This will automatically run the changes described below for you.

Manually

If you’re coming from a pre-2.0 version of this package, make sure to install @percy/cli after upgrading to retain any existing scripts that reference the Percy CLI command.

If you have a previous Percy configuration file, migrate it to the newest version with the config:migrate command:

Automatically with @percy/migrate

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

This will automatically run the changes described below for you.

Manually

If you’re coming from a pre-3.0 version of this package, make sure to install @percy/cli after upgrading to retain any existing scripts that reference the Percy CLI command.

If you have a previous Percy configuration file, migrate it to the newest version with the config:migrate command:

Automatically with @percy/migrate

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

This will automatically run the changes described below for you, with the exception of changing the require.

Manually

The name of the require has changed from require 'percy' to require 'percy/capybara'. This is to avoid conflict with our Ruby Selenium SDK’s require statement.

The previous version of this SDK had the following function signature:

v5.x of this SDK has a significant change to the API. There no longer is a stand alone module to call and you no longer need to pass the page/driver. It’s available on the current Capybara session (page):

If you were using this SDK outside of Capybara, you’ll likely find the Ruby Selenium SDK a better fit.

Installing @percy/cli & removing @percy/agent

If you’re coming from a 4.x version of this package, make sure to install @percy/cli after upgrading to retain any existing scripts that reference the Percy CLI command. You will also want to uninstall @percy/agent, as it’s been replaced by @percy/cli.

If you have a previous Percy configuration file, migrate it to the newest version with the config:migrate command:

Prior versions of the Storybook SDK were drastically different than the current version. The command, it’s arguments, and how the SDK works internally have changed completely. Using the old command with new versions will now result in an error message. The new command is now integrated into @percy/cli as a plugin.

To use new versions of this SDK, you will have to also install the CLI with the SDK:

Since both the command and arguments have changed, you’ll need to replace your existing usage with the new usage. For some projects, this may require setting additional configuration options. See the list of breaking changes below for details.

Breaking changes

Most importantly, the command itself has changed and all previous arguments are no longer accepted.

• The percy-storybook command has been replaced with a percy CLI subcommand, percy storybook.

• The previous --build_dir flag is now a command argument and there is no default build directory. If you relied on the default, it must now be explicitly provided.

• The --widths flag is no longer accepted. Widths can be set using the respective widths Percy config file snapshot option or percy Storybook parameter.

• The --minimum_height flag is no longer accepted and therefore no longer defaults to 800px. The default minimum height shared by all SDKs is 1024px. The minimum height can be set using the respective min-height Percy config file snapshot option or percy Storybook parameter.

• The --debug flag is now --verbose, inherited from the CLI.

• The --output_format flag is no longer accepted and has no alternative. If you relied on this flag, please open an issue.

• The --rtl and --rtl_regex flags are no longer accepted. The --rtl flag duplicated stories and set the direction=rtl query parameter for the duplicate’s URL. The --rtl_regex flag was used to determine when to create this RTL duplicate story.

Versions of this plugin prior to 1.0 depended on and invoked the snapshot command from the now deprecated @percy/agent package. The new @percy/cli, the core for all Percy SDKs, must now be installed explicitly. The new plugin no longer invokes any commands automatically, but will detect if the CLI is running and send pages to it for snapshotting.

After upgrading this plugin, install @percy/cli:

See modify your test section for running with Percy.

All previous plugin options were provided to the snapshot command as flags. These options have now been removed. If using any of the previous plugin options, replace them with the below alternatives:

• config - Use the CLI --config flag instead (percy exec --config ... -- gatsby build)
• files - Use the include static option (can be provided as a plugin option)
• ignore - Use the exclude static option (can be provided as a plugin option)

See [options]((/docs/percy/integrate/gatsby#options) above for all accepted options.

If you have a previous Percy configuration file, migrate it to the newest version with the config:migrate command:

If you’re coming from a pre-2.0 version of this package, the percySnapshot function is now the default export, and the browser argument is now only required when used in standalone mode.

If you have a previous Percy configuration file, migrate it to the newest version with the config:migrate command: