@percy/cli

What is @percy/cli?

@percy/cli is a command-line interface for Percy, a visual testing and review platform. It allows you to automate visual testing for your web applications by capturing screenshots and comparing them against baselines to detect visual changes.

What are @percy/cli's main functionalities?

Snapshot

This feature allows you to capture snapshots of your web application at different screen widths. The code sample demonstrates how to capture snapshots of a local web application running on port 3000 at three different screen widths.

const percySnapshot = require('@percy/cli');

(async () => {
  await percySnapshot('http://localhost:3000', { widths: [375, 768, 1280] });
})();

Start and Stop Percy

This feature allows you to start and stop the Percy agent programmatically. The code sample demonstrates how to start the Percy agent, run your tests, and then stop the agent.

const { start, stop } = require('@percy/cli');

(async () => {
  await start();
  // Run your tests here
  await stop();
})();

Upload Snapshots

This feature allows you to upload pre-captured snapshots to Percy for comparison. The code sample demonstrates how to upload snapshots from a local directory.

const { upload } = require('@percy/cli');

(async () => {
  await upload({ snapshots: ['./snapshots'] });
})();

Other packages similar to @percy/cli

cypress

Cypress is a JavaScript end-to-end testing framework that also supports visual testing through plugins like cypress-image-snapshot. It provides a comprehensive testing solution but requires additional setup for visual testing compared to @percy/cli.

puppeteer

Puppeteer is a Node library that provides a high-level API to control Chrome or Chromium over the DevTools Protocol. While it is primarily used for browser automation, it can also be used for visual testing by capturing screenshots and comparing them manually or with additional tools.

webdriverio

WebdriverIO is a test automation framework that allows you to run tests based on the WebDriver protocol and Appium. It supports visual regression testing through plugins like wdio-visual-regression-service, but requires more configuration compared to @percy/cli.

README

Percy CLI

The Percy CLI is used to interact with, and upload snapshots to, percy.io via the command line.

• Installation
• Command Topics
• Advanced
• Issues
• Developing

Installation

$ npm install --save-dev @percy/cli

Command Topics

• percy exec - capture and upload snapshots
• percy snapshot - snapshot a static directory or a list of pages
• percy upload - upload a static directory of images
• percy config - manage configuration files
• percy build - interact with Percy builds

Advanced

In addition to the CLI packages, this repo contains core libraries responsible for Percy's CI/CD integrations, Percy API communication, DOM serialization, asset discovery, etc.

• @percy/core - performs snapshot asset discovery and uploading
• @percy/client - handles communicating with the Percy API
• @percy/dom - serializes DOM snapshots
• @percy/env - captures CI build environment variables
• @percy/config - loads Percy configuration files
• @percy/logger - common logger used throughout the CLI
• @percy/sdk-utils - shared helpers for JavaScript SDKs
• @percy/cli-command - Percy CLI command framework

Issues

For problems directly related to the CLI, add an issue on GitHub.

For other issues, open a support request.

Developing

This project is built with lerna. The core libraries and CLI plugins are located in ./packages. Run yarn to install dependencies after cloning the repo and use the following scripts for various development tasks:

• yarn build - build all packages
• yarn build:watch - build and watch all packages in parallel
• yarn clean - clean up build and coverage output
• yarn lint - lint all packages
• yarn readme - generate cli commands readme usage
• yarn test - run all tests, one package after another
• yarn test:coverage - run all tests with coverage, one package after another
• yarn global:link - links all packages being developed as global.
  • requires yarn build to be run before consuming.
  • we can then consume this package using yarn link @percy/[core|cli..]
  • Note: linking is only required once, subsequent changes for development requires running build command.
• yarn global:unlink - unlinks all packages globally

Individual package scripts can be invoked using yarn's workspace command. For example:

$ yarn workspace @percy/core test

How to update Chromium revision?

check in Core Package's readme here.