Skip to content

Latest commit

 

History

History

core

Folders and files

README.md

pixelpact-core

Measure what a reference page actually looks like, store it as a contract, then hold an implementation to that contract.

Most visual testing compares a screenshot against an older screenshot of the same thing. pixelpact compares an implementation against a reference: the design you are rebuilding, the site you are migrating, the page your new framework has to reproduce. The contract is measured, not written by hand, so "it looks right" becomes a number.

Install

npm install pixelpact-core
npm install playwright        # peer dependency
npx playwright install chromium

playwright is a peer dependency and is imported lazily. Reading, validating and formatting contracts works without a browser installed.

Quick start

import { check, extract, formatCheckReport, writeContract } from 'pixelpact-core'

const contract = await extract({
  url: 'https://reference.example',
  selector: 'main',
  screenshotDir: './pixelpact',
})
await writeContract('./pixelpact/contract.json', contract)

const report = await check(contract, { url: 'http://localhost:3000' })
process.stdout.write(formatCheckReport(report, { color: true }))
process.exitCode = report.ok ? 0 : 1

What is measured

For every visible element under the root selector, at every viewport:

  • the bounding box, in CSS pixels relative to the document
  • around seventy computed properties: colour, typography, spacing, borders, radii, shadows, layout, transforms, transitions and animations
  • the hover and focus states, by actually hovering and focusing the element and recording only the declarations that changed
  • the ::before and ::after pseudo elements when they render content
  • the CSS custom properties declared on :root, and every @keyframes rule
  • a screenshot per viewport, when screenshotDir is set

Figma as a source

A contract can also come from a Figma file, read over the REST API. No browser is launched and nothing is rendered locally.

import { extractFromFigma, check, writeContract } from 'pixelpact-core'

const contract = await extractFromFigma({
  url: 'https://www.figma.com/design/<file-key>/Site?node-id=1-23',
  token: process.env.FIGMA_TOKEN,   // this is the default
  screenshotDir: './pixelpact',
})
await writeContract('./pixelpact/figma.contract.json', contract)

const report = await check(contract, { url: 'http://localhost:3000' })

The token is a Figma personal access token with file content read access, created under Settings, Security, Personal access tokens. extractFromFigma reads FIGMA_TOKEN unless you pass one.

Matching is different, and this is the whole story

A Figma layer has no CSS selector, so a Figma contract cannot be matched by path or by tag name. A layer type says nothing about which HTML element implements it, so pixelpact does not guess. Matching runs on the layer name.

Give the layer a name in Figma, then put the same name in the markup:

<a class="btn btn-primary" data-contract="Hero/CTA">Start free</a>

Every layer without a matching data-contract is reported as missing rather than skipped. When a check finds no match at all, the report prints the reason and what to do about it; figmaMatchHint(report) returns the same sentence for a tool that formats its own output.

What a layer contributes

Figma Contract
layer name contractId, the only thing matching uses
node id selector, written figma:1:23 as a display label
node type tag, lowercased: frame, text, instance
absoluteBoundingBox box, translated so the root frame sits at 0, 0
solid fill background-color, or color on a text layer
stroke and strokeWeight the four border widths, border-top-style, border-top-color
cornerRadius, rectangleCornerRadii the four radius longhands
drop shadow box-shadow
opacity below 1 opacity
text style font family, size, weight, line height, letter spacing, alignment, transform
auto layout display: flex, direction, gap, the four paddings, align-items, justify-content
colour styles tokens, keyed by the style name

Only properties the layer actually carries are written. A gradient or image fill has no single CSS colour, so the property is left out and the layer is named in contract.warnings. A value that is not in the contract is never asserted, which is the point: an empty assertion is honest, a guessed one fails an implementation that is correct.

Hidden layers, and everything under them, are skipped. Hover, focus and pseudo element states are absent, because Figma has none to read, so a check against a Figma contract never reports them.

Side by side, section by section

check returns properties and diff returns one percentage for a whole page. Neither says where the page is wrong. side splits both pages into sections, pairs them by position, and writes one image per pair: the reference on the left, the implementation on the right, both at the same scale, the differing pixels boxed in red, and a header carrying the section, the width and the percentage.

import { formatSideReport, side } from 'pixelpact-core'

const report = await side({
  referenceUrl: 'https://reference.example',
  targetUrl: 'http://localhost:3000',
  outDir: './pixelpact/side',
  widths: [1440, 390],
})

process.stdout.write(formatSideReport(report, { color: true }))
process.exitCode = report.ok ? 0 : 1
pixelpact side  FAILED
  reference https://reference.example
  target    http://localhost:3000
  widths    1440px, 390px
  sections  5 passed, 1 failed of 6 (threshold 0.5%)

#   SECTION  WIDTH   VERDICT  DIFF
01  hero     1440px  PASS     0.000%
02  pricing  1440px  FAIL     1.193%
  ./pixelpact/side/1440/02-pricing.png
03  contact  1440px  PASS     0.000%

Sections are the visible element children of sectionsSelector, or of main when the page has one and body otherwise. Each one is named after its id, then its first heading, then its position, and that name is both the slug in the report and the file name of the image.

Pairing is by position. When the two pages disagree on how many sections they have, the surplus is counted in unmatched and named in warnings rather than paired with a guess: a report that invented a counterpart would show a picture of one section under the name of another. ok is true when every compared section is inside threshold and nothing was left unmatched.

Run one section at a time with only, by index or by part of its slug:

await side({ referenceUrl, targetUrl, outDir: './side', only: 'pricing' })

API

Function What it does
extract(options) Measure a reference page and return a Contract
extractFromFigma(options) Read a Figma file over the REST API and return a Contract
parseFigmaUrl(input) Read the file key and node id out of a figma.com url
isFigmaUrl(input) True when a string is a figma.com url with a file key
figmaMatchHint(report) The data-contract advice, when a Figma check matched nothing
check(contract, options) Compare a live implementation against the contract
diff(contract, options) Compare the implementation to the reference screenshot, pixel by pixel
side(options) Compare two live pages section by section and compose one image per section
parseContract(input) Validate unknown data as a contract
readContract(path) Read and validate a contract from disk
writeContract(path, contract) Validate and write a contract as JSON
formatCheckReport(report, options) Render a check report as an aligned table
formatDiffReport(report, options) Render a diff report as a few lines
formatSideReport(report, options) Render a side by side report as one row per section
DEFAULT_VIEWPORTS desktop 1440x900, tablet 768x1024, mobile 390x844

Options

Every browser backed entry point accepts the browser options: headless, channel, executablePath, locale, timezone, userAgent, stealth, wait, dismissOverlays and timeout. Defaults are portable: locale en-US, time zone UTC, and the browser's own user agent.

extract adds selector, viewports, maxElements, maxStates, masks, freezeAnimations, fullPage and screenshotDir. check adds viewport, selector, tolerance and maxStates. diff adds viewport, selector, threshold, masks and outDir. side takes referenceUrl, targetUrl and outDir instead of url, and adds widths, sectionsSelector, only, threshold, minSectionHeight, columnWidth and masks. Its outDir has no default: the composed images are the product of the run, so the caller says where they go.

extractFromFigma launches no browser, so none of the browser options apply to it. It takes url, token, nodeId, viewportName, maxElements, screenshotDir, scale and onProgress.

Configuration is arguments only. Nothing is read from a config file, from the current working directory or from the environment, with two exceptions: executablePath falls back to PIXELPACT_CHROMIUM, so a machine that already has a browser does not have to download another, and the Figma token falls back to FIGMA_TOKEN, so a secret never has to be written into a script.

check and diff inherit locale, timezone, wait, stealth, dismissOverlays and userAgent from the contract unless you pass your own. Those settings decide what a page renders, and measuring the implementation under different ones produces failures that have nothing to do with its CSS. Machine settings such as headless, channel and timeout are never inherited.

Progress

The library never prints. Pass onProgress to follow a long run:

await extract({
  url: 'https://reference.example',
  onProgress: (event) => process.stderr.write(`${event.phase}: ${event.message}\n`),
})

Reading a check report

pixelpact check  FAILED
  target    http://localhost:3000
  reference https://reference.example
  viewport  desktop 1440x900
  elements  128 matched, 2 missing of 130
  checks    2841 passed, 19 failed (99.3% of 2860)

deviations (19)
SELECTOR                    PROPERTY     EXPECTED           ACTUAL             DIFF
main > section > h2         font-size    32px               28px               4px
nav > a:nth-of-type(2)      hover.color  rgb(0, 90, 200)    rgb(0, 0, 0)       76.5 (color)

formatCheckReport takes color (default false, ANSI codes emitted by the library itself) and limit (default 20 rows, then a line counting the rest).

How elements are matched

An implementation rarely has the same DOM as its reference, so matching runs in three passes, most trustworthy first:

  1. data-contract="..." on both sides. Add the attribute where you want a guaranteed match.
  2. An identical CSS path.
  3. The same tag carrying the same text.

An element that answers to none of the three is reported as missing. A Figma contract uses the first pass only, for the reason given above.

Tolerances

  • Lengths pass within tolerance pixels, default 1.
  • Box dimensions also pass within one percent of the expected size: a pixel on a 24px button matters, a pixel on a 1440px hero is rounding.
  • Colours are compared by perceived distance, not by string. A difference above roughly 2 is visible side by side and is reported. A difference in alpha is always reported.
  • width and height are compared from the bounding box only, so a mismatch is never reported twice.
  • The transform of an element that animates forever is skipped: it is a reading of a moment, not a promise.

Pixel diffing

diff needs a reference screenshot, so the contract must have been extracted with screenshotDir. If the contract declares a root selector, that selector has to exist in the implementation too: comparing a whole page against a shot of one section produces a number that measures nothing, so it fails instead.

Output goes to outDir, which defaults to the system temp directory.

Errors

Every error thrown on purpose extends PixelpactError and carries a code.

Class Code When
ContractError ERR_CONTRACT The contract is missing, unreadable, invalid, or lacks what a step needs
BrowserUnavailableError ERR_BROWSER playwright is not installed, or no browser could be launched
BlockedPageError ERR_BLOCKED The page answered with a bot challenge and nothing could be measured
TargetNotFoundError ERR_TARGET A url would not load, or a selector matched nothing
FigmaError ERR_FIGMA The Figma url, token, file key or node id is wrong, or the API refused

Determinism

Two runs of the same page should produce the same numbers, so the browser is launched with a fixed sRGB colour profile and hinting disabled, the locale and time zone are always set, animations are frozen before a screenshot, and the page is scrolled and decoded before it is captured. Hover states are read after the element's own transition has finished rather than after a fixed delay, which is what keeps a 250ms fade from being sampled mid flight.

License

MIT