Skip to main content

Cypress

Add visual regression testing to your existing Cypress suite in under 5 minutes. No changes to your existing tests required — just add cy.witness('name') wherever you want a snapshot.

Prerequisites​

  • Node.js 18+
  • Chrome browser
  • Existing Cypress project (npm install cypress)

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:  › Cypress
? Where are your test files?   › cypress/e2e

The wizard generates three files:

FilePurpose
cypress/support/testivai-witness.jsAdds cy.witness() custom command
cypress/support/testivai-plugin.jsInjects --remote-debugging-port=9222 on Chrome launch
cypress/e2e/visual-example.cy.jsWorking example test

3. Authenticate​

npx testivai auth <your-api-key>

Get your API key from the TestivAI Dashboard.

4. Register the Plugin​

In your cypress.config.js, import and call the plugin inside setupNodeEvents:

const { defineConfig } = require('cypress');
const testivaiPlugin = require('./cypress/support/testivai-plugin');

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      testivaiPlugin(on, config);
      return config;
    },
  },
});

The plugin automatically adds --remote-debugging-port=9222 when Chrome launches. No manual Chrome configuration needed.

5. Add Capture Calls​

Import the witness helper in your support file or directly in a test:

// cypress/support/e2e.js  (or import in individual tests)
import './testivai-witness';

Then call cy.witness('name') at any point in your test:

it('homepage looks correct', () => {
  cy.visit('/');
  cy.witness('homepage');
});

it('login page looks correct', () => {
  cy.visit('/login');
  cy.witness('login-page');
});

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

// TestivAI Visual Regression Helper
Cypress.Commands.add('witness', (name) => {
  return cy.window().invoke('testivaiWitness', name);
});

6. Full Working Example​

The wizard generates this example at cypress/e2e/visual-example.cy.js:

// TestivAI Visual Regression Example
import '../support/testivai-witness';

describe('Visual Regression', () => {
  it('captures homepage', () => {
    cy.visit('/');
    cy.witness('homepage');
  });
});

7. Run​

testivai run "cypress run --browser chrome"

testivai run wraps your normal Cypress command, connects via CDP, and captures snapshots automatically.

CI/CD​

Add --headless for headless Chrome in CI:

testivai run "cypress run --browser chrome --headless"

For GitHub Actions:

- name: Run visual tests
  run: testivai run "cypress run --browser chrome --headless"
  env:
    TESTIVAI_API_KEY: ${{ secrets.TESTIVAI_API_KEY }}

How it works​

cy.witness('name') calls cy.window().invoke('testivaiWitness', name) — invoking the global function injected by the CDP SDK. The CDP SDK captures a full 5-layer snapshot (screenshot, DOM, CSS, layout, performance) and uploads it for analysis.

→ See how the CDP sidecar model works