@percy/sdk-utils

@percy/sdk-utils

Common JavaScript SDK utils

• Usage
  • logger()
  • percy
  • isPercyEnabled()
  • postSnapshot()
  • request

Usage

logger([debug])

This function is a direct export of @percy/logger.

percy

This object contains information about the local Percy environment and is updated when isPercyEnabled is called for the first time.

import { percy } from '@percy/sdk-utils'

// reflects/updates process.env.PERCY_SERVER_ADDRESS
percy.address === 'http://localhost:5338'

// updated after isPercyEnabled() is called
percy.enabled === true|false
percy.version.major === 1
percy.version.minor === 2
percy.version.patch === 3
percy.version.toString() === '1.2.3'
percy.config === {} // .percy.yml config

// updated after fetchPercyDOM() is called
percy.domScript === fs.readFile(require.resolve('@percy/dom'))

isPercyEnabled()

Returns true or false if the Percy CLI API server is running. Calls the server's /healthcheck endpoint and populates information for the percy property. The result of this function is cached and subsequent calls will return the first cached result. If the healthcheck fails, will log a message unless the CLI loglevel is quiet or silent.

import { isPercyEnabled } from '@percy/sdk-utils'

// CLI API not running
await isPercyEnabled() === false
// [percy] Percy is not running, disabling snapshots

// CLI API is running
await isPercyEnabled() === true

fetchPercyDOM()

Fetches and returns the @percy/dom serialization script hosted by the local Percy API server. The resulting string can be evaluated within a browser context to add the PercyDOM.serialize function to the global scope. Subsequent calls return the first cached result.

import { fetchPercyDOM } from '@percy/sdk-utils'

let script = await fetchPercyDOM()

// selenium-webdriver
driver.executeScript(script)
// webdriverio
browser.execute(script)
// puppeteer
page.evaluate(script)
// protractor
browser.executeScript(script)
// etc...

postSnapshot(options)

Posts snapshot options to the local Percy API server.

import { postSnapshot } from '@percy/sdk-utils'

await postSnapshot({
  // required
  name: 'Snapshot Name',
  url: 'http://localhost:8000/',
  domSnapshot: 'result from PercyDOM.serialize()'
  // optional
  environmentInfo: ['<lib>/<version>', '<lang>/<version>'],
  clientInfo: '<sdk>/<version>',
  widths: [475, 1280],
  minHeight: 1024,
  enableJavaScript: false,
  requestHeaders: {}
})

request(url[, options])

Sends a request to the local Percy API server. Used internally by the other SDK utils.

import { request } from '@percy/sdk-utils'

await request('/percy/idle')
await request('/percy/stop')

request.fetch(url, options)

The underlying implementation of the request() util. For Node environments, http.request is used; for browser environments, window.fetch is used. Can be overridden by the SDK's framework to work around CORS/CSP issues.

The returned object must contain the following normalized properties from the request response: status, statusText, headers, body

import { request } from '@percy/sdk-utils'

// Cypress SDK example
request.fetch = async function fetch(url, options) {
  options = { url, retryOnNetworkFailure: false, ...options }
  return Cypress.backend('http:request', options)
}

Similar packages

Other packages similar to @percy/sdk-utils

puppeteer

Puppeteer is a Node library which provides a high-level API to control Chrome or Chromium over the DevTools Protocol. It can be used for taking screenshots, generating PDFs, and automating web page interactions. While Puppeteer can capture screenshots, it does not provide the same level of integration with visual testing tools like Percy.

cypress

Cypress is a JavaScript end-to-end testing framework that allows you to write tests for web applications. It includes features for taking screenshots and recording videos of tests. However, it is primarily focused on functional testing rather than visual testing, and does not offer the same utilities for integrating with visual testing services like Percy.

webdriverio

WebdriverIO is a test automation framework that allows you to run tests based on the WebDriver protocol and Appium. It supports taking screenshots and has plugins for visual regression testing, but it requires additional setup and configuration compared to the out-of-the-box utilities provided by @percy/sdk-utils.