@percy/client
v1.28.5
Published
Communicate with Percy's API to create builds and snapshots, upload resources, and finalize builds and snapshots. Uses [`@percy/env`](.packages/env) to send environment information with new builds. Can also be used to query for a project's builds using a
Downloads
1,822,457
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
- 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'sPERCY_TOKEN
(defaultprocess.env.PERCY_TOKEN
)clientInfo
— Client info sent to Percy via a user-agent stringenvironmentInfo
— 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 namewidths
— Widths to take screenshots atminHeight
— Miniumum screenshot heightenableJavaScript
— Enable JavaScript for screenshotsclientInfo
— Additional client infoenvironmentInfo
— Additional environment inforesources
— Array of snapshot resourcesurl
— Resource URL (required)mimetype
— Resource mimetype (required)content
— Resource content (required)sha
— Resource content sharoot
— 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 infoenvironmentInfo
— Additional environment infoexternalDebugUrl
— External debug URLtag
— Tagged information about this comparisonname
— 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 comparisonheight
- The height for this type of comparisonorientation
- Either "portrait" or "landscape"
tiles
— Array of comparison tilessha
— Tile file contents SHA-256 hashfilepath
— Tile filepath in the filesystem (required when missingcontent
)content
— Tile contents as a string or buffer (required when missingfilepath
)statusBarHeight
— Height of any status bar in this tilenavBarHeight
— Height of any nav bar in this tileheaderHeight
— Height of any header area in this tilefooterHeight
— Height of any footer area in this tilefullscreen
— 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 shashas
— An array of commit shasbranch
— The name of a branchstate
— 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 missingcommit
)commit
— Commit SHA (required when missingbuild
)project
— Project slug (required when usingcommit
)timeout
— Timeout in milliseconds to wait with no updates (default10 * 60 * 1000
)interval
— Interval in miliseconds to check for updates (default10000
)