@percy/client

What is @percy/client?

@percy/client is an npm package that provides a client for interacting with the Percy visual testing and review platform. It allows developers to automate visual testing by capturing screenshots of web pages and comparing them against baseline images to detect visual changes.

What are @percy/client's main functionalities?

Initialize Percy Client

This feature allows you to initialize the Percy client with your project token, which is necessary for authenticating API requests.

const Percy = require('@percy/client');
const percy = new Percy({ token: 'your-project-token' });

Create a Build

This feature allows you to create a new build in Percy. A build is a collection of snapshots that will be compared against the baseline images.

const build = await percy.createBuild();
console.log(`Build created: ${build.data.id}`);

Upload a Snapshot

This feature allows you to upload a snapshot to a specific build. A snapshot is a screenshot of a web page at different widths.

await percy.uploadSnapshot(build.data.id, {
  name: 'Home Page',
  url: 'http://localhost:3000',
  widths: [375, 768, 1280]
});

Finalize a Build

This feature allows you to finalize a build, which triggers Percy to process the snapshots and compare them against the baseline images.

await percy.finalizeBuild(build.data.id);
console.log('Build finalized');

Other packages similar to @percy/client

backstopjs

BackstopJS is a visual regression testing tool that uses headless browsers to capture screenshots of web pages and compare them against baseline images. Unlike @percy/client, BackstopJS is a standalone tool that does not require a separate service for storing and comparing images.

cypress

Cypress is an end-to-end testing framework that includes built-in support for visual testing through plugins like cypress-image-snapshot. While Cypress is primarily focused on functional testing, it can be extended to perform visual regression testing similar to @percy/client.

webdriverio

WebdriverIO is a testing framework for Node.js that supports visual regression testing through plugins like wdio-visual-regression-service. It allows you to capture and compare screenshots during your end-to-end tests, similar to @percy/client.

README

@percy/client

Communicate with Percy's API to create builds and snapshots, upload resources, and finalize builds and snapshots. Uses @percy/env to send environment information with new builds. Can also be used to query for a project's builds using a read access token.

Usage

new PercyClient([options])

import PercyClient from '@percy/client';

// provide a read or write token, defaults to PERCY_TOKEN environment variable
const client = new PercyClient({ token: 'abcdef123456' })

Create a build

await client.createBuild()

Create, upload, and finalize snapshots

await client.sendSnapshot({
  name,
  widths,
  minimumHeight,
  enableJavaScript,
  clientInfo,
  environmentInfo,
  // `sha` falls back to `content` sha
  resources: [{ url, sha, content, mimetype, root }]
})

Finalize a build

await client.finalizeBuild()

// finalize all parallel build shards
await client.finalizeBuild({ all: true })

Query for a build

Requires a read access token

await client.getBuild(buildId)

Query for a project's builds

Requires a read access token

await client.getBuilds(projectSlug/*, filters*/)

Wait for a build to be finished

Requires a read access token

await client.waitForBuild({ build: 'build-id' })
await client.waitForBuild({ project: 'project-slug', commit: '40-char-sha' })