tk-eye Pro

Visual regression testing tool. Captures baseline screenshots, compares pixel-by-pixel against new screenshots, and generates diff images highlighting changes. Powered by Playwright.

bash

npm install -g @tk-tis/tk-eye
npx playwright install chromium

Commands

capture — Create Baselines

Take screenshots of each route and store them as baseline references:

bash

tk-eye capture https://example.com --routes /,/about,/contact

compare — Check for Regressions

Take new screenshots and compare them against stored baselines:

bash

# Compare with default 5% threshold
tk-eye compare https://example.com --routes /,/about,/contact

# Stricter threshold of 3%
tk-eye compare https://example.com --routes /,/about,/contact --threshold 3

# JSON output
tk-eye compare https://example.com --routes /,/about --json

accept — Update Baselines

When changes are intentional, promote the current screenshot as the new baseline:

bash

tk-eye accept /about

list — View Stored Baselines

bash

tk-eye list
tk-eye list --json

Options

Flag	Description	Default
`--routes`	Comma-separated routes to capture/compare	`/`
`--dir`	Storage directory for baselines and diffs	`.tk-eye`
`--threshold`	Maximum allowed diff percentage (0-100)	`5`
`--browser`	Browser engine: `chromium`, `firefox`, `webkit`	`chromium`
`--json`	Output results as JSON	`false`
`--no-color`	Disable ANSI color codes	`false`

How It Works

Capture — Playwright launches a headless browser, navigates to each route at 1280x720 resolution, and saves PNG screenshots as baselines
Compare — New screenshots are taken and compared pixel-by-pixel against baselines using raw RGBA buffer comparison
Diff Image — Changed pixels are highlighted in red on a dimmed version of the current screenshot, saved as a diff image
Threshold — If any route exceeds the diff percentage threshold, the CLI exits with code 1

Storage Structure

text

.tk-eye/
  url-map.json              # URL hash -> original URL mapping
  baselines/
    {url-hash}/
      routes.json            # Route filename -> original route mapping
      _root_.png             # Screenshot for /
      about.png              # Screenshot for /about
  current/
    {url-hash}/              # Latest comparison screenshots
  diffs/
    {url-hash}/              # Diff images (red = changed pixels)

Tip

Add .tk-eye/current/ and .tk-eye/diffs/ to your .gitignore. Keep .tk-eye/baselines/ committed to track baseline changes in version control.

Exit Codes

Code	Meaning
`0`	All routes below the diff threshold (no regressions)
`1`	Regression detected (one or more routes exceed the threshold)

Programmatic Usage

javascript

const { captureBaseline, compare, acceptBaseline, listBaselines } = require('@tk-tis/tk-eye');

// Capture baselines
const captureResult = await captureBaseline('https://example.com', ['/', '/about'], {
  dir: '.tk-eye',
  browser: 'chromium',
});

// Compare against baselines
const compareResult = await compare('https://example.com', ['/', '/about'], {
  dir: '.tk-eye',
  threshold: 5,
  browser: 'chromium',
});

// Check results
compareResult.comparisons.forEach(c => {
  console.log(`${c.route}: ${c.diffPercent}% diff - ${c.status}`);
});
// Output:
//   /: 0.42% diff - pass
//   /about: 12.8% diff - fail

// Accept intentional changes
await acceptBaseline('/about', { dir: '.tk-eye' });

// List stored baselines
const baselines = await listBaselines({ dir: '.tk-eye' });

HTK-Cloud Integration

javascript

const { reportToHtkCloud } = require('@tk-tis/tk-eye/src/reporter');

const result = await compare(url, routes, options);
await reportToHtkCloud(result, {
  htkCloudUrl: 'https://htk-cloud-v4.enzu-agent.workers.dev',
  projectId: 'my-project',
});

Environment variables: HTK_CLOUD_URL, HTK_PROJECT_ID, HTK_API_KEY

Edit this page on GitHub