@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
Create a build
Create, upload, and finalize snapshots
Create, upload, and finalize comparisons
Finalize a build
Query for a build*
Query for a project's builds*
Wait for a build to be finished*

Usage

import PercyClient from '@percy/client'

const client = new PercyClient(options)

Options

token — Your project's PERCY_TOKEN (default process.env.PERCY_TOKEN)
clientInfo — Client info sent to Percy via a user-agent string
environmentInfo — Environment info also sent with the user-agent string

Create a build

Creates a percy build. Only one build can be created at a time per instance. During this step, various environment information is collected via @percy/env and associated with the new build. If PERCY_PARALLEL_TOTAL and PERCY_PARALLEL_NONCE are present, a build shard is created as part of a parallelized Percy build.

await client.createBuild()

Create, upload, and finalize snapshots

This method combines the work of creating a snapshot, uploading any missing resources, and finally finalizng the snapshot.

await client.sendSnapshot(buildId, snapshotOptions)

Options

name — Snapshot name
widths — Widths to take screenshots at
minHeight — Minimum screenshot height
enableJavaScript — Enable JavaScript for screenshots
clientInfo — Additional client info
environmentInfo — Additional environment info
resources — Array of snapshot resources
- url — Resource URL (required)
- mimetype — Resource mimetype (required)
- content — Resource content (required)
- sha — Resource content sha
- root — Boolean indicating a root resource## Create, upload, and finalize snapshots

Create, upload, and finalize comparisons

This method combines the work of creating a snapshot, creating an associated comparison, uploading associated comparison tiles, and finally finalizing the comparison.

await client.sendComparison(buildId, comparisonOptions)

Options

name — Snapshot name (required)
clientInfo — Additional client info
environmentInfo — Additional environment info
externalDebugUrl — External debug URL
tag — Tagged information about this comparison
- name — The tag name for this comparison, e.g. "iPhone 14 Pro" (required)
- osName - OS name for the comparison tag; e.g. "iOS"
- osVersion - OS version for the comparison tag; e.g. "16"
- width - The width for this type of comparison
- height - The height for this type of comparison
- orientation - Either "portrait" or "landscape"
tiles — Array of comparison tiles
- sha — Tile file contents SHA-256 hash
- filepath — Tile filepath in the filesystem (required when missing content)
- content — Tile contents as a string or buffer (required when missing filepath)
- statusBarHeight — Height of any status bar in this tile
- navBarHeight — Height of any nav bar in this tile
- headerHeight — Height of any header area in this tile
- footerHeight — Height of any footer area in this tile
- fullscreen — Boolean indicating this is a fullscreen tile

Finalize a build

Finalizes a build. When all is true, all-shards=true is added as a query param so the API finalizes all other parallel build shards associated with the build.

// finalize a build
await client.finalizeBuild(buildId)

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

Query for a build

Retrieves build data by id.

Requires a read access token

await client.getBuild(buildId)

Query for a project's builds

Retrieves project builds, optionally filtered. The project slug can be found as part of the project's URL. For example, the project slug for https://percy.io/percy/example is "percy/example".

Requires a read access token

// get all builds for a project
await client.getBuilds(projectSlug)

// get all builds for a project's "master" branch
await client.getBuilds(projectSlug, { branch: 'master' })

Filters

sha — A single commit sha
shas — An array of commit shas
branch — The name of a branch
state — The build state ("pending", "finished", etc.)

Wait for a build to be finished

This method resolves when the build has finished and is no longer pending or processing. By default, it will time out if there is no update after 10 minutes.

Requires a read access token

// wait for a specific project build by commit sha
await client.waitForBuild({
  project: 'percy/example',
  commit: '40-char-sha'
}, data => {
  // called whenever data changes
  console.log(JSON.stringify(data));
})

Options

build — Build ID (required when missing commit)
commit — Commit SHA (required when missing build)
project — Project slug (required when using commit)
timeout — Timeout in milliseconds to wait with no updates (default 10 * 60 * 1000)
interval — Interval in milliseconds to check for updates (default 10000)

Current Tags

1.30.9-alpha-1.0 ... alpha (a year ago)
1.31.9-beta.5 ... beta (2 months ago)
1.31.8 ... latest (3 months ago)

330 Versions

1.31.9-beta.5 ... 2 months ago
1.31.9-beta.4 ... 2 months ago
1.31.9-beta.3 ... 2 months ago
1.31.9-beta.2 ... 2 months ago
1.31.9-beta.1 ... 3 months ago
1.31.9-beta.0 ... 3 months ago
1.31.8 ... 3 months ago
1.31.8-beta.0 ... 3 months ago
1.31.7 ... 3 months ago
1.31.7-beta.0 ... 4 months ago
1.31.6 ... 4 months ago
1.31.6-beta.8 ... 4 months ago
1.31.6-beta.7 ... 4 months ago
1.31.6-beta.6 ... 4 months ago
1.31.6-beta.5 ... 4 months ago
1.31.6-beta.4 ... 4 months ago
1.31.5 ... 4 months ago
1.31.5-beta.3 ... 4 months ago
1.31.5-alpha.0 ... 4 months ago
1.31.5-beta.2 ... 4 months ago
1.31.5-beta.1 ... 5 months ago
1.31.5-beta.0 ... 5 months ago
1.31.4 ... 6 months ago
1.31.4-beta.2 ... 6 months ago
1.31.4-beta.1 ... 6 months ago
1.31.4-beta.0 ... 6 months ago
1.31.3 ... 6 months ago
1.31.3-beta.6 ... 6 months ago
1.31.3-beta.5 ... 6 months ago
1.31.3-beta.4 ... 6 months ago
1.31.3-beta.3 ... 7 months ago
1.31.3-beta.2 ... 7 months ago
1.31.3-beta.0 ... 7 months ago
1.31.2 ... 7 months ago
1.31.2-beta.4 ... 7 months ago
1.31.2-beta.3 ... 7 months ago
1.31.2-beta.2 ... 7 months ago
1.31.2-beta.1 ... 8 months ago
1.31.2-beta.0 ... 8 months ago
1.31.1 ... 9 months ago
1.31.1-beta.2 ... 9 months ago
1.31.1-beta.1 ... 10 months ago
1.31.1-beta.0 ... 10 months ago
1.31.0 ... 10 months ago
1.30.11-beta.4 ... 10 months ago
1.30.11-beta.3 ... 10 months ago
1.30.11 ... a year ago
1.30.11-beta.2 ... a year ago
1.30.11-beta.1 ... a year ago
1.30.11-beta.0 ... a year ago
1.30.10 ... a year ago
1.30.10-beta.0 ... a year ago
1.30.9 ... a year ago
1.30.9-alpha-1.0 ... a year ago
1.30.9-1.30.9-alpha-1.0 ... a year ago
1.30.9-beta.4 ... a year ago
1.30.9-beta.3 ... a year ago
1.30.9-beta.2 ... a year ago
1.30.9-alpha.0 ... a year ago
1.30.9-beta.1 ... a year ago
1.30.9-beta.0 ... a year ago
1.30.8-beta.2 ... a year ago
1.30.8 ... a year ago
1.30.8-beta.1 ... a year ago
1.30.7 ... a year ago
1.30.7-beta.3 ... a year ago
1.30.7-beta.2 ... a year ago
1.30.7-beta.1 ... a year ago
1.30.7-beta.0 ... a year ago
1.30.6 ... a year ago
1.30.6-beta.0 ... a year ago
1.31.0-alpha.3 ... a year ago
1.30.5 ... a year ago
1.30.5-beta.2 ... a year ago
1.31.0-alpha.2 ... a year ago
1.31.0-alpha.0 ... a year ago
1.30.5-beta.1 ... a year ago
1.30.5-beta.0 ... a year ago
1.30.5-alpha.0 ... a year ago
1.30.4 ... a year ago
1.30.3 ... a year ago
1.30.3-beta.1 ... a year ago
1.30.3-alpha.5 ... a year ago
1.30.3-alpha.4 ... a year ago
1.30.3-beta.0 ... a year ago
1.30.3-alpha.3 ... a year ago
1.30.3-alpha.2 ... a year ago
1.30.3-alpha.1 ... a year ago
1.30.3-alpha.0 ... a year ago
1.30.2 ... a year ago
1.30.2-alpha.1 ... a year ago
1.30.2-alpha.0 ... a year ago
1.30.1 ... a year ago
1.30.0 ... 2 years ago
1.29.5-beta.0 ... 2 years ago
1.29.4 ... 2 years ago
1.29.4-beta.6 ... 2 years ago
1.29.4-beta.5 ... 2 years ago
1.29.4-beta.4 ... 2 years ago
1.29.4-beta.3 ... 2 years ago
1.29.4-beta.2 ... 2 years ago
1.29.4-beta.1 ... 2 years ago
1.29.3 ... 2 years ago
1.29.3-beta.2 ... 2 years ago
1.29.3-beta.1 ... 2 years ago
1.29.3-beta.0 ... 2 years ago
1.29.2 ... 2 years ago
1.29.2-beta.0 ... 2 years ago
1.29.1 ... 2 years ago
1.29.1-beta.1 ... 2 years ago
1.29.1-beta.0 ... 2 years ago
1.29.0 ... 2 years ago
1.29.0-beta.1 ... 2 years ago
1.29.1-alpha.0 ... 2 years ago
1.29.0-beta.0 ... 2 years ago
1.28.9 ... 2 years ago
1.28.9-beta.1 ... 2 years ago
1.28.9-beta.0 ... 2 years ago
1.28.8 ... 2 years ago
1.28.8-beta.6 ... 2 years ago
1.28.8-beta.4 ... 2 years ago
1.28.8-beta.3 ... 2 years ago
1.28.8-beta.2 ... 2 years ago
1.28.8-beta.1 ... 2 years ago
1.28.8-beta.0 ... 2 years ago
1.28.7 ... 2 years ago
1.28.7-beta.0 ... 2 years ago
1.28.6 ... 2 years ago
1.28.5 ... 2 years ago
1.28.4 ... 2 years ago
1.28.4-alpha.0 ... 2 years ago
1.28.4-beta.1 ... 2 years ago
1.28.4-beta.0 ... 2 years ago
1.28.3 ... 2 years ago
1.28.3-alpha.1 ... 2 years ago
1.28.3-beta.1 ... 2 years ago
1.28.3-beta.0 ... 2 years ago
1.28.2 ... 2 years ago
1.28.2-alpha.1 ... 2 years ago
1.28.2-beta.2 ... 2 years ago
1.28.2-beta.1 ... 2 years ago
1.28.2-beta.0 ... 2 years ago
1.28.1 ... 2 years ago
1.28.1-alpha.4 ... 2 years ago
1.28.1-beta.1 ... 2 years ago
1.28.1-alpha.3 ... 2 years ago
1.28.1-alpha.2 ... 2 years ago
1.28.1-alpha.1 ... 2 years ago
1.28.1-beta.0 ... 2 years ago
1.28.0 ... 2 years ago
1.28.0-beta.1 ... 2 years ago
1.28.0-beta.0 ... 2 years ago
1.27.7 ... 2 years ago
1.27.7-beta.0 ... 2 years ago
1.27.6 ... 2 years ago
1.27.6-beta.1 ... 2 years ago
1.27.6-beta.0 ... 2 years ago
1.27.5 ... 2 years ago
1.27.5-beta.2 ... 2 years ago
1.27.5-beta.1 ... 2 years ago
1.27.6-alpha.0 ... 2 years ago
1.27.5-beta.0 ... 2 years ago
1.27.4 ... 2 years ago
1.27.4-beta.4 ... 2 years ago
1.27.4-beta.3 ... 2 years ago
1.27.4-beta.2 ... 2 years ago
1.27.5-alpha.0 ... 2 years ago
1.27.4-beta.1 ... 2 years ago
1.27.4-beta.0 ... 2 years ago
1.27.3 ... 3 years ago
1.27.3-beta.0 ... 3 years ago
1.27.2 ... 3 years ago
1.27.1 ... 3 years ago
1.27.1-beta.0 ... 3 years ago
1.27.0 ... 3 years ago
1.27.0-beta.2 ... 3 years ago
1.27.0-beta.1 ... 3 years ago
1.26.3 ... 3 years ago
1.26.3-beta.3 ... 3 years ago
1.26.3-alpha.4 ... 3 years ago
1.26.3-beta.2 ... 3 years ago
1.27.0-beta.0 ... 3 years ago
1.26.3-beta.1 ... 3 years ago
1.26.3-beta.0 ... 3 years ago
1.26.2 ... 3 years ago
1.26.2-beta.0 ... 3 years ago
1.27.0-alpha.0 ... 3 years ago
1.26.1 ... 3 years ago
1.26.0 ... 3 years ago
1.26.0-beta.0 ... 3 years ago
1.25.0 ... 3 years ago
1.24.3-beta.0 ... 3 years ago
1.24.2 ... 3 years ago
1.24.1 ... 3 years ago
1.24.0 ... 3 years ago
1.23.0 ... 3 years ago
1.22.0 ... 3 years ago
1.22.0-alpha.0 ... 3 years ago
1.21.0 ... 3 years ago
1.20.3 ... 3 years ago
1.20.2 ... 3 years ago
1.20.1 ... 3 years ago
1.20.0 ... 3 years ago
1.19.2 ... 3 years ago
1.19.2-alpha.0 ... 3 years ago
1.18.0 ... 3 years ago
1.19.1-alpha.0 ... 3 years ago
1.17.0 ... 3 years ago
1.19.0-alpha.0 ... 3 years ago
2.0.0-alpha.0 ... 3 years ago
1.16.0 ... 3 years ago
1.15.0 ... 3 years ago
1.14.0 ... 3 years ago
1.13.0 ... 3 years ago
1.12.0 ... 3 years ago
1.11.0 ... 4 years ago
1.10.4 ... 4 years ago
1.10.3 ... 4 years ago
1.10.2 ... 4 years ago
1.10.1 ... 4 years ago
1.10.0 ... 4 years ago
1.9.1 ... 4 years ago
1.9.0 ... 4 years ago
1.8.1 ... 4 years ago
1.8.0 ... 4 years ago
1.7.2 ... 4 years ago
1.7.1 ... 4 years ago
1.7.0 ... 4 years ago
1.6.4 ... 4 years ago
1.6.3 ... 4 years ago
1.6.2 ... 4 years ago
1.6.1 ... 4 years ago
1.6.0 ... 4 years ago
1.5.1 ... 4 years ago
1.5.0 ... 4 years ago
1.4.0 ... 4 years ago
1.3.1 ... 4 years ago
1.3.0 ... 4 years ago
1.2.1 ... 4 years ago
1.2.0 ... 4 years ago
1.1.4 ... 4 years ago
1.1.3 ... 4 years ago
1.1.2 ... 4 years ago
1.1.1 ... 4 years ago
1.1.0 ... 4 years ago
1.0.8 ... 4 years ago
1.0.7 ... 4 years ago
1.0.6 ... 4 years ago
1.0.5 ... 4 years ago
1.0.4 ... 4 years ago
1.0.3 ... 4 years ago
1.0.2 ... 4 years ago
1.0.1 ... 4 years ago
1.0.0 ... 4 years ago
1.0.0-beta.76 ... 4 years ago
1.0.0-beta.75 ... 4 years ago
1.0.0-beta.74 ... 4 years ago
1.0.0-beta.73 ... 4 years ago
1.0.0-beta.72 ... 4 years ago
1.0.0-beta.71 ... 4 years ago
1.0.0-beta.70 ... 4 years ago
1.0.0-beta.69 ... 4 years ago
1.0.0-beta.68 ... 5 years ago
1.0.0-beta.67 ... 5 years ago
1.0.0-beta.66 ... 5 years ago
1.0.0-beta.65 ... 5 years ago
1.0.0-beta.64 ... 5 years ago
1.0.0-beta.63 ... 5 years ago
1.0.0-beta.62 ... 5 years ago
1.0.0-beta.61 ... 5 years ago
1.0.0-beta.60 ... 5 years ago
1.0.0-beta.59 ... 5 years ago
1.0.0-beta.58 ... 5 years ago
1.0.0-beta.57 ... 5 years ago
1.0.0-beta.56 ... 5 years ago
1.0.0-beta.55 ... 5 years ago
1.0.0-beta.54 ... 5 years ago
1.0.0-beta.53 ... 5 years ago
1.0.0-beta.52 ... 5 years ago
1.0.0-beta.51 ... 5 years ago
1.0.0-beta.50 ... 5 years ago
1.0.0-beta.49 ... 5 years ago
1.0.0-beta.48 ... 5 years ago
1.0.0-beta.47 ... 5 years ago
1.0.0-beta.46 ... 5 years ago
1.0.0-beta.45 ... 5 years ago
1.0.0-beta.44 ... 5 years ago
1.0.0-beta.43 ... 5 years ago
1.0.0-beta.42 ... 5 years ago
1.0.0-beta.41 ... 5 years ago
1.0.0-beta.40 ... 5 years ago
1.0.0-beta.39 ... 5 years ago
1.0.0-beta.38 ... 5 years ago
1.0.0-beta.37 ... 5 years ago
1.0.0-beta.36 ... 5 years ago
1.0.0-beta.35 ... 5 years ago
1.0.0-beta.34 ... 5 years ago
1.0.0-beta.33 ... 5 years ago
1.0.0-beta.32 ... 5 years ago
1.0.0-beta.31 ... 5 years ago
1.0.0-beta.30 ... 5 years ago
1.0.0-beta.29 ... 5 years ago
1.0.0-beta.28 ... 5 years ago
1.0.0-beta.27 ... 5 years ago
1.0.0-beta.26 ... 5 years ago
1.0.0-beta.25 ... 5 years ago
1.0.0-beta.24 ... 5 years ago
1.0.0-beta.23 ... 5 years ago
1.0.0-beta.22 ... 5 years ago
1.0.0-beta.21 ... 5 years ago
1.0.0-beta.20 ... 5 years ago
1.0.0-beta.19 ... 5 years ago
1.0.0-beta.18 ... 5 years ago
1.0.0-beta.17 ... 5 years ago
1.0.0-beta.16 ... 6 years ago
1.0.0-beta.15 ... 6 years ago
1.0.0-beta.14 ... 6 years ago
1.0.0-beta.13 ... 6 years ago
1.0.0-beta.12 ... 6 years ago
1.0.0-beta.11 ... 6 years ago
1.0.0-beta.10 ... 6 years ago
1.0.0-beta.9 ... 6 years ago
1.0.0-beta.8 ... 6 years ago
1.0.0-beta.7 ... 6 years ago
1.0.0-beta.6 ... 6 years ago
1.0.0-beta.5 ... 6 years ago
1.0.0-beta.4 ... 6 years ago
1.0.0-beta.3 ... 6 years ago
1.0.0-beta.2 ... 6 years ago
1.0.0-beta.1 ... 6 years ago