README
@percy/core
The core component of Percy's CLI and SDKs that handles creating builds, discovering snapshot
assets, uploading snapshots, and finalizing builds. Uses @percy/client
for API communication, a
Puppeteer browser for asset discovery, and starts a local API server for posting snapshots from
other processes.
Usage
A Percy
class instance can manage a Percy build, take page snapshots, and perform snapshot asset
discovery. It also hosts a local API server for Percy SDKs to communicate with.
import Percy from '@percy/core'
// create a new instance
const percy = new Percy(percyOptions)
// create a new instance and start it
const percy = await Percy.start(percyOptions)
Options
token
— Your project'sPERCY_TOKEN
(defaultprocess.env.PERCY_TOKEN
)loglevel
— Logger level, one of"info"
,"warn"
,"error"
,"debug"
(default"info"
)server
— Controls whether an API server is created (defaulttrue
)port
— API server port (default5338
)clientInfo
— Client info sent to Percy via a user-agent stringenvironmentInfo
— Environment info also sent with the user-agent stringdeferUploads
— Defer creating a build and uploading snapshots until laterskipUploads
— Skip creating a build and uploading snapshots altogether
The following options can also be defined within a Percy config file
snapshot
— Snapshot options applied to each snapshotwidths
— Widths to take screenshots at (default[375, 1280]
)minHeight
— Minimum screenshot height (default1024
)percyCSS
— Percy specific CSS to inject into the snapshotenableJavaScript
— Enable JavaScript for screenshots (defaultfalse
)
discovery
— Asset discovery optionsallowedHostnames
— Array of allowed hostnames to capture assets fromrequestHeaders
— Request headers used when discovering snapshot assetsauthorization
— Basic authusername
andpassword
for protected snapshot assetsdisableCache
— Disable asset caching (defaultfalse
)userAgent
— Custom user-agent string used when requesting assetscookies
— Browser cookies to use when requesting assetsnetworkIdleTimeout
— Milliseconds to wait for the network to idle (default100
)concurrency
— Asset discovery concerrency (default5
)launchOptions
— Asset discovery browser launch optionsexecutable
— Browser executable path (defaultprocess.env.PERCY_BROWSER_EXECUTABLE
)timeout
— Discovery launch timeout, in milliseconds (default30000
)args
— Additional browser process argumentsheadless
— Runs the browser headlessy (defaulttrue
)
Additional Percy config file options are also allowed and will override any options defined by a local config file. These config file options are also made available to SDKs via the local API health check endpoint.
#start()
Starting a Percy
instance will start a local API server, start the asset discovery browser, and
create a new Percy build. If an asset discovery browser is not found, one will be downloaded.
await percy.start()
// [percy] Percy has started!
API Server
Starting a Percy
instance will start a local API server unless server
is false
. The server can
be found at http://localhost:5338/
or at the provided port
number.
- GET
/percy/healthcheck
– Responds with information about the running instance - GET
/percy/dom.js
– Responds with the@percy/dom
library - GET
/percy/idle
- Responds when the running instance is idle - POST
/percy/snapshot
– Calls#snapshot()
with provided snapshot options - POST
/percy/stop
- Remotely stops the runningPercy
instance
#stop([force])
Stopping a Percy
instance will wait for any pending snapshots, close the asset discovery browser,
close the local API server, and finalize the current Percy build. When uploads are deferred,
stopping the instance will also trigger processing of the upload queue. When force
is true
,
queues are cleared and closed to prevent queued snapshots from running.
await percy.stop()
// [percy] Processing 3 snapshots...
// [percy] Snapshot taken: Snapshot one
// [percy] Snapshot taken: Snapshot two
// [percy] Snapshot taken: Snapshot three
// [percy] Uploading 3 snapshots...
// [percy] Finalized build #1: https://percy.io/org/project/123
await percy.stop(true)
// [percy] Stopping percy...
// [percy] Finalized build #1: https://percy.io/org/project/123
#idle()
This method will resolve shortly after pending snapshots and uploads have completed and no more have started. Queued tasks are not considered pending unless they are actively running, so deferred uploads will not be awaited on with this method.
percy.snapshot(...);
percy.snapshot(...);
percy.snapshot(...);
await percy.idle()
// [percy] Snapshot taken: ...
// [percy] Snapshot taken: ...
// [percy] Snapshot taken: ...
#snapshot(options)
Performs asset discovery for a snapshot and queues uploading the snapshot to the associated Percy build. When an existing DOM snapshot is provided, it is served as the root resource during asset discovery. When no existing DOM snapshot is provided, a new one will be captured using any provided snapshot capture options.
// snapshots can be handled concurrently, no need to await
percy.snapshot({
name: 'Snapshot 1',
url: 'http://localhost:3000',
domSnapshot: domSnapshot,
clientInfo: 'my-sdk',
environmentInfo: 'my-lib'
...snapshotOptions
})
percy.snapshot({
name: 'Snapshot 2',
url: 'http://localhost:3000/',
...snapshotOptions,
// without a domSnapshot, capture options will be used to take one
waitForTimeout: 1000,
waitForSelector: '.done-loading',
execute: async () => {},
additionalSnapshots: [{
name: 'Snapshot 2.1',
execute: () => {},
...snapshotOptions
}]
})
Options
url
— Snapshot URL (required)name
— Snapshot namedomSnapshot
— Snapshot DOM stringclientInfo
— Additional client infoenvironmentInfo
— Additional environment infodiscovery
- Limited snapshot specific discovery optionsallowedHostnames
,requestHeaders
,authorization
,disableCache
,userAgent
Capture options can only be provided when domSnapshot
is missing.
waitForTimeout
— Milliseconds to wait before taking a snapshotwaitForSelector
— CSS selector to wait for before taking a snapshotexecute
— Function or function body to execute within the page before taking a snapshotadditionalSnapshots
— Array of additional sequential snapshots to take of the pagename
— Snapshot name (required if noprefix
orsuffix
)prefix
— Snapshot name prefix (required if noname
orsuffix
)suffix
— Snapshot name suffix (required if noname
orprefix
)waitForTimeout
,waitForSelector
,execute
— See above
Common snapshot options are also accepted and will override instance snapshot options. See instance options for common snapshot and discovery options.
Advanced
Download discovery browser on install
By default, the browser is only downloaded when asset discovery is started for the first time. This is because many features of the CLI do not require a browser at all, and automatically downloading a browser creates a much heavier footprint than needed for those features. However, if your CI caches dependencies after the install step, the browser will not be cached and will be downloaded every time Percy runs without it.
If the environment variable PERCY_POSTINSTALL_BROWSER
is present and truthy, then the browser will
be downloaded after the package is installed to allow it to be cached. You can also require
@percy/core/post-install
within another node module to trigger the browser download manually.
Skipping discovery browser download
If your CI comes with a Chromium binary pre-installed and you wish to skip Percy's own browser
installation, you can set the respective discovery.launchOptions.executable
config option. When
the executable at the provided path exists, the default download will be skipped and the provided
binary will be used instead. This option can also be set using the PERCY_BROWSER_EXECUTABLE
environment variable.
Warning! Percy is only tested against the browser it downloads automatically. When providing a custom browser executable, you may experience unexpected issues.