How to migrate your Visual Testing Project to Percy CLI

Regression testing ensures changes in the application don’t break any functionality. The software testing tools are mostly focused on testing the functionality. Today, the web application has been built, giving the same importance to User Interface and Functionality. So both have equal importance and priority. Testing the visual aspect of the website was difficult in earlier days, as one had to compare two images manually, but today, there are a lot of tools that emerged in the market which make visual testing easier.

Percy for Visual Regression Testing

Percy is one such tool dedicated to visual regression tests. It helps identify the visual changes of web applications such as styles, fonts, colors, etc. Percy is a SaaS-based product that provides many features such as multiple browser visual validations, side-by-side comparison, review, reject and accept changes from anywhere, etc.

Percy is typically integrated with popular test automation tools such as Cypress, Puppeteer, Playwright, etc., to yield the best possible outcome. Percy supports integration with almost all test automation tools. 

Earlier, Percy was shipped with the package @percy/agent; using this package user was interacting with Percy and its infrastructure. Later Percy understood the user requirement and decided to develop a next-generation user-friendly package which is now shipped as  @percy/cli.

Talk to an Expert

The @percy/agent is now deprecated. No active development is happening there.

If you navigate to @percy/agent npm page you will see the message “This package has been deprecated”.

Considering the deprecation of @percy/agent and the introduction of brand new next-generation SDK @percy/cli, Percy suggested migrating all existing projects those are using @percy/agent to the latest @percy/cli.

Why should you migrate the visual testing project to Percy CLI?

The @percy/agent is deprecated, there will not be active development in the future. This does your project and tests flaky and unreliable. Percy is actively releasing new features however, if you do not migrate your project to Percy CLI, you will not receive any features or bug fixes. In the future, at some point in time, your visual regression project will become obsolete. So it is important to migrate your visual regression project to Percy CLI.

How to migrate the visual testing project to Percy CLI?

The @percy/cli has breaking changes, which means your project doesn’t work as is when you install @percy/cli. So you need to migrate your project. Percy understands user pain, as migration requires some effort and learning new SDK configurations, so Percy is providing the dedicated npm package to migrate your project. The @percy/migrate can be used for hassle-free migration of Percy to the latest version.

Let’s understand what @percy/migrate does

• Detects the SDK by examining project dependencies
• If the project is using old SDK @percy/agent, then it uninstalls
• Installs the latest Percy SDK @percy/cli
• Migrates all Percy config files to match the latest version

Though all of the above steps can be performed manually the package makes hassle-free migration by doing it in an automated way.

Step by Step guide to migrating visual regression test project to the latest Percy SDK

Step 1: Launch the Percy migration tool

The @percy/migrate tool is useful in migrating your visual validation project to the latest Percy CLI. Use the below command to launch the migration tool.

npx @percy/migrate

Step 2: Choose the best possible option in CLI

When you launch the CLI migration tool, it automatically detects the Percy SDK, which you are using, such as @percy/cypress, @percy/puppeteer, @percy/webdriverio, etc. Typically below set of questions will be asked.

Are you currently using @percy/cypress? Answer Yes

The next question will be 

Install @percy/cli (and remove @percy/agent)? Answer Yes

This migrates your project to the latest Percy SDK and installs the Percy CLI.

Depending on your project, Percy might ask you a few more questions. For example, if you are using Cypress, it asks to modify the file. However, this differs from your test automation framework (Percy SDK).

Below is the example of an additional question asked by the migration tool in Cypress

Percy tasks were removed, update Cypress plugins file? Answer Y

Which files? cypress/plugins/index.js

By Pressing the [Enter] key, Percy updates the required files, this may take some time, wait until it finishes. In the end, you should see the message “Migration complete!”.

Now, you are all set to use the Percy CLI, which is the latest available version.

Step 3: Execute your Percy Tests

The Percy execution commands are specific to Percy SDK you are using. For example, if you are using the Cypress, you can use the below command to execute your test.

percy exec -- cypress run

Percy CLI is now supported for all available automation frameworks, So irrespective of the framework you are using, you can migrate your SDK and Percy CLI to the latest version.

Conclusion

Visual Regression Test is the best and most effective way to test any UI features and regressions. Visual Regression can help you to deliver quality UI in a faster delivery cycle. 

Percy makes visual regression tests easier, whenever you choose a new tool most challenging job is learning or upgrading the skills, but Percy makes it easier, and you can directly integrate Percy with your test automation suite. You just have to spend a few hours learning the Percy commands and their options.

Try Percy for Free