Programmatic API

peek exports its core functions for use as a Node.js/Bun library. This is useful when you want to integrate peek into your own tooling, test suites, or automation scripts.

Installation

npm install peek
# or
bun add peek

Exports

import {
  snap,
  checkPage,
  createChecker,
  runChecks,
  formatResults,
  runSceneChecks,
} from 'peek';

snap(options)

Take a screenshot programmatically.

import { snap } from 'peek';

const result = await snap({
  url: 'http://localhost:3000',
  output: '/tmp/screenshot.png',   // optional
  viewport: '1920x1080',           // optional, default: '1280x720'
  fullPage: true,                  // optional, default: false
  wait: 1000,                      // optional, ms to wait after load
  waitUntil: 'networkidle2',       // optional, default: 'networkidle2'
  checks: true,                    // optional, run layout checks
  noPool: false,                   // optional, disable browser pooling
  setup: './login.ts',             // optional, path to setup script
});

console.log(result.path);          // Absolute path to screenshot
console.log(result.durationMs);    // Time taken in ms
console.log(result.checks);        // HealthResults (if checks: true)

SnapOptions

PropertyTypeDefaultDescription
urlstring-URL to screenshot
outputstringAuto-generatedOutput file path
viewportstring'1280x720'Viewport size
fullPagebooleanfalseCapture full scrollable page
waitnumber0Wait time after page load (ms)
waitUntilstring'networkidle2'Puppeteer waitUntil event
checksbooleanfalseRun layout checks
checksOnlystring[]AllOnly run specific checks
checksIgnorestring[]NoneIgnore selectors for checks
noPoolbooleanfalseDisable browser pooling
setupstringNonePath to setup script

SnapResult

PropertyTypeDescription
pathstringAbsolute path to screenshot file
targetstringURL that was screenshotted
viewport{ width, height }Viewport used
timestampstringISO timestamp
durationMsnumberTime taken
checksHealthResultsLayout check results (if enabled)

checkPage(page, config?)

Run layout checks on an existing Puppeteer Page object. This is the simplest way to integrate peek checks into existing Puppeteer scripts.

import puppeteer from 'puppeteer-core';
import { checkPage } from 'peek';

const browser = await puppeteer.launch({ executablePath: '/path/to/chrome' });
const page = await browser.newPage();
await page.goto('http://localhost:3000');

const results = await checkPage(page, {
  ignore: ['.skip-this'],
  checks: {
    touchTargets: { minWidth: 48, minHeight: 48 },
  },
});

console.log(results.summary);
// { passed: 5, errors: 0, warnings: 2 }

await browser.close();

createChecker(config)

Create a reusable checker with pre-configured settings.

import { createChecker } from 'peek';

const checker = createChecker({
  ignore: ['.ad-banner'],
  checks: {
    overflow: true,
    clickability: true,
    touchTargets: false,  // disabled
  },
  severity: {
    overflow: 'error',
  },
});

// Use it on multiple pages
const results1 = await checker.run(page1);
const results2 = await checker.run(page2);

runChecks(page, options?)

Lower-level check runner. Takes a Puppeteer Page and optional runner options.

import { runChecks } from 'peek';

const results = await runChecks(page, {
  config: {
    ignore: ['.banner'],
    checks: { overflow: true },
  },
  checks: ['overflow', 'clickability'],  // Only run these
});

formatResults(results, format?)

Format HealthResults into a string.

import { formatResults } from 'peek';

const text = formatResults(results, 'text');   // Human-readable
const json = formatResults(results, 'json');   // JSON string
const junit = formatResults(results, 'junit'); // JUnit XML

runSceneChecks(manifest, config?)

Run spatial checks on a scene manifest without a browser.

import { runSceneChecks } from 'peek';

const manifest = {
  room_width: 20,
  room_height: 15,
  player: { id: 1, name: 'Player', x: 0, y: 0 },
  npcs: [
    { id: 2, name: 'NPC1', kind: 'npc', x: 3, y: 2 },
  ],
  entities: [],
};

const results = runSceneChecks(manifest, {
  checks: {
    'entity-overlap': true,
    'entity-bounds': true,
    'entity-size': true,
    'entity-visibility': false,
  },
});

console.log(results.summary);

Type Exports

peek exports all its TypeScript types:

import type {
  SnapOptions,
  SnapResult,
  CheckConfig,
  ChecksConfig,
  HealthResults,
  Issue,
  Severity,
  ElementInfo,
  Check,
  CheckResult,
  CheckContext,
  SceneManifest,
  SceneEntity,
  SceneCheckConfig,
} from 'peek';
Built with Ptero