Skip to main content

Puppeteer

Add visual regression testing to your existing Puppeteer test suite. The witness(page, name) helper wraps Puppeteer's page.evaluate() to capture snapshots via the CDP SDK.

Prerequisites​

  • Node.js 18+
  • puppeteer installed in your project
npm install puppeteer

1. Install the CLI​

npm install -g @testivai/witness-cdp

2. Run the Setup Wizard​

npx testivai init

Select when prompted:

? Select your language:        › JavaScript / TypeScript
? Select your test framework:  › Puppeteer
? Where are your test files?   › tests

The wizard generates two files:

FilePurpose
testivai-witness.jswitness(page, name) helper function
tests/visual-example.test.jsWorking example test

3. Authenticate​

npx testivai auth <your-api-key>

Get your API key from the TestivAI Dashboard.

4. Chrome Setup​

Pass --remote-debugging-port=9222 in your puppeteer.launch() args:

const browser = await puppeteer.launch({
  args: ['--remote-debugging-port=9222'],
});
tip

Puppeteer controls Chrome directly, so --remote-debugging-port=9222 is added to the launch args — not ChromeOptions like in Selenium.

5. Add Capture Calls​

Import witness from the generated helper and call it after navigating:

const puppeteer = require('puppeteer');
const { witness } = require('../testivai-witness');

const browser = await puppeteer.launch({ args: ['--remote-debugging-port=9222'] });
const page = await browser.newPage();

await page.goto('http://localhost:3000');
await witness(page, 'homepage');

await page.goto('http://localhost:3000/login');
await witness(page, 'login-page');

The generated helper file (testivai-witness.js):

// TestivAI Visual Regression Helper
async function witness(page, name) {
  return page.evaluate((n) => window.testivaiWitness(n), name);
}
module.exports = { witness };

6. Full Working Example​

The wizard generates this example at tests/visual-example.test.js:

// TestivAI Visual Regression Example
const puppeteer = require('puppeteer');
const { witness } = require('../testivai-witness');

describe('Visual Regression', () => {
  let browser, page;

  beforeAll(async () => {
    browser = await puppeteer.launch({ args: ['--remote-debugging-port=9222'] });
    page = await browser.newPage();
  });

  afterAll(async () => await browser.close());

  it('captures homepage', async () => {
    await page.goto('http://localhost:3000');
    await witness(page, 'homepage');
  });
});

7. Run​

testivai run "npx jest tests/"

CI/CD​

Add --headless, --no-sandbox, and --disable-dev-shm-usage for CI:

const browser = await puppeteer.launch({
  args: [
    '--remote-debugging-port=9222',
    '--headless',
    '--no-sandbox',
    '--disable-dev-shm-usage',
  ],
});

GitHub Actions example:

- name: Run visual tests
  run: testivai run "npx jest tests/"
  env:
    TESTIVAI_API_KEY: ${{ secrets.TESTIVAI_API_KEY }}

How it works​

witness(page, name) uses Puppeteer's page.evaluate() to call window.testivaiWitness(name) — the global function injected by the CDP SDK. The SDK captures a full 5-layer snapshot and uploads it for analysis.

→ See how the CDP sidecar model works