Percy Client (Deprecated)

3.9.0 · deprecated · verified Wed Apr 22

The `percy-client` package was the original JavaScript API client library for Percy, a visual testing and review platform. It provided low-level programmatic access to Percy's API for managing visual builds and snapshots, crucial for integrating automated visual regression testing into CI/CD pipelines. This library allowed developers to create builds, capture DOM snapshots, upload associated resources (like HTML, CSS, and images), and finalize builds directly through code. The package is currently at version 3.9.0, with its last significant update approximately three years ago. It has since entered a maintenance state, receiving only minor dependency updates before being officially deprecated. Its primary differentiation was offering direct API control, which is now handled by the newer `@percy/client` package and the `@percy/cli` ecosystem, which offer a more comprehensive and extensible toolchain for visual testing.

Common errors

```
This package has been deprecated in favor of @percy/client
```
cause Attempting to install or use the deprecated `percy-client` package, which is superseded by a newer, modular architecture.

fix Instead of `percy-client`, install `@percy/cli` (`npm install --save-dev @percy/cli`) and `@percy/client` (`npm install @percy/client`). Update your codebase to use the new API, typically by importing `PercyClient` from `@percy/client` or using `percy exec` with a framework-specific SDK.
```
Error: A WebdriverIO instance is needed to initialise percy-webdriverio
```
cause This specific error indicates an attempt to use `percy-client` (or an SDK like `percy-webdriverio` which might have used it internally) without providing the required framework-specific instance (e.g., a WebDriverIO browser object) in its constructor.

fix Ensure that the `percy-client` or associated SDK is correctly initialized with the necessary context or framework instance as per its specific API requirements. For `percy-webdriverio`, this means passing a WebdriverIO browser instance to its constructor.

Warnings

breaking This package (`percy-client`) is officially deprecated and no longer actively maintained. Users are strongly advised to migrate to the `@percy/client` package and the `@percy/cli` toolchain for all new and existing Percy integrations. Continued use of `percy-client` may lead to compatibility issues with newer Percy platform features.
Fix: Migrate your integration to use `@percy/cli` and `@percy/client`. Refer to the official Percy documentation for migration guides. Start by installing `@percy/cli`: `npm install --save-dev @percy/cli` and then upgrade any Percy SDKs you are using.
gotcha Older versions of `percy-client` might use deprecated `Buffer` constructor syntax, which can lead to runtime warnings or errors in newer Node.js environments. [cite: github releases]
Fix: Upgrade to `percy-client` version 3.2.3 or higher, which updated Buffer usage to remove deprecated constructor syntax. However, the recommended fix is to migrate to the `@percy/client` package as `percy-client` itself is deprecated. [cite: github releases]

Install

npm install percy-client npm
yarn add percy-client yarn
pnpm add percy-client pnpm

Imports

PercyClient
wrong:
```
const PercyClient = require('percy-client');
```
correct:
```
import PercyClient from 'percy-client';
```
While CommonJS `require` was historically common for this package, modern Node.js projects should use ESM `import`. However, this package is deprecated; use `@percy/client` instead.

Quickstart

This quickstart demonstrates how to programmatically create a Percy build, create a snapshot, upload HTML content as a resource, and finalize the snapshot and build using the `percy-client` library. It illustrates the low-level API interaction for visual testing.

import PercyClient from 'percy-client';

// Ensure PERCY_TOKEN is set in your environment variables for authentication
// For example: export PERCY_TOKEN='YOUR_PERCY_PROJECT_TOKEN'
const percyToken = process.env.PERCY_TOKEN || '';

const client = new PercyClient({
  token: percyToken,
  clientInfo: 'my-custom-integration',
  environmentInfo: 'my-node-environment'
});

async function runPercyBuildAndSnapshot() {
  if (!percyToken) {
    console.warn('PERCY_TOKEN is not set. Snapshots will be skipped.');
    return;
  }

  console.log('Creating a new Percy build...');
  const build = await client.createBuild();
  console.log(`Build created: ${build.attributes['web-url']}`);

  console.log('Creating a snapshot...');
  const htmlContent = `
    <!DOCTYPE html>
    <html>
    <head><title>My Test Page</title></head>
    <body>
      <h1>Hello from Percy!</h1>
      <p>This is a test snapshot.</p>
    </body>
    </html>
  `;
  const snapshot = await client.createSnapshot(build.id, {
    name: 'Homepage with H1',
    widths: [768, 1280]
  });

  // Uploading the HTML content as a resource for the snapshot
  await client.uploadResource(build.id, snapshot.id, {
    resourceUrl: '/', // The URL this resource represents
    mimetype: 'text/html',
    content: Buffer.from(htmlContent)
  });

  console.log('Finalizing snapshot...');
  await client.finalizeSnapshot(snapshot.id);

  console.log('Finalizing build...');
  await client.finalizeBuild(build.id);
  console.log('Percy build process completed!');
}

runPercyBuildAndSnapshot().catch(error => {
  console.error('An error occurred during Percy process:', error);
  process.exit(1);
});

view raw JSON →