@percy/sdk-utils

What is @percy/sdk-utils?

@percy/sdk-utils is a utility package designed to assist with the integration of Percy visual testing into various SDKs. It provides common functionality and helpers that can be used to simplify the process of capturing and managing visual snapshots.

What are @percy/sdk-utils's main functionalities?

Snapshot Creation

This feature allows you to create visual snapshots of web pages. The `createSnapshot` function is used to capture the current state of a page and save it as a snapshot for visual comparison.

const { createSnapshot } = require('@percy/sdk-utils');

async function takeSnapshot(page, name) {
  await createSnapshot(page, name);
}

takeSnapshot(page, 'Home Page');

DOM Manipulation

This feature provides a way to serialize the DOM of a web page. The `serializeDOM` function can be used to capture the HTML structure of a page, which can then be used for visual testing or other purposes.

const { serializeDOM } = require('@percy/sdk-utils');

async function getSerializedDOM(page) {
  const dom = await page.evaluate(() => serializeDOM());
  return dom;
}

getSerializedDOM(page).then(dom => console.log(dom));

Asset Discovery

This feature helps in discovering assets on a web page. The `discoverAssets` function can be used to identify and list all the assets (like images, stylesheets, etc.) that are part of a page, which is useful for ensuring all necessary resources are captured during visual testing.

const { discoverAssets } = require('@percy/sdk-utils');

async function findAssets(page) {
  const assets = await discoverAssets(page);
  return assets;
}

findAssets(page).then(assets => console.log(assets));

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.

README

@percy/sdk-utils

Common Node SDK utils

Usage

log(level, message)

Logs colored output and stack traces based on the loglevel defined by the PERCY_LOGLEVEL environment variable.

const { log } = require('@percy/sdk-utils');

// logs unless loglevel is quiet or silent
log('info', 'foobar');
// [percy] foobar

// logs a red error message unless the loglevel is silent
log('error', 'bad');
// [percy] bad

// logs the stack trace when loglevel is debug
log('error', new Error('some error'));
// [percy] Error: some error
//     at example (/path/to/example.js:2:10)
//     at ...

// only logs when the loglevel is debug
log('debug', 'debug message');
// [percy] debug message

getInfo()

Returns information about any running Percy CLI server. Some information is only available after isPercyEnabled has been called.

const { getInfo } = require('@percy/sdk-utils');

let info = getInfo();

// CLI API address
info.cliAPI === (process.env.PERCY_CLI_API || 'http://localhost:5338/percy')

// CLI loglevel
info.loglevel === (process.env.PERCY_LOGLEVEL || 'info')

// CLI version parts (requires isPercyEnabled call)
info.version === (['1', '0', '0'] || undefined)

// CLI config options (requires isPercyEnabled call)
info.config === {}

isPercyEnabled()

Returns true or false if the Percy CLI API server is running. Calls the server's /healthcheck endpoint and populates information for getInfo. 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.

const { isPercyEnabled } = require('@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 CLI API server. The resulting string can be evaulated within a browser context to add the PercyDOM.serialize function to the global scope. Subsequent calls return the first cached result.

const { fetchPercyDOM } = require('@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 CLI API server.

const { postSnapshot } = require('@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: {}
});