Playwright

Playwright has its own dedicated TestivAI SDK — @testivai/witness-playwright. Unlike other frameworks, Playwright does not use the CDP sidecar approach. The SDK integrates directly with Playwright's built-in browser control.

---

Prerequisites

• Node.js 18+
• @playwright/test installed in your project

npm install @playwright/test

---

1. Install the Playwright SDK

npm install @testivai/witness-playwright

No CLI required

Playwright uses a dedicated SDK, not the @testivai/witness-cdp CLI. Do not run testivai run with Playwright.

---

2. Authenticate

Get your API key from the TestivAI Dashboard and add it to your environment:

export TESTIVAI_API_KEY=your-api-key

Or add it to a .env file and load it in your Playwright config.

---

3. Configure Reporter

Add the TestivAI reporter to your playwright.config.ts:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: [
    ['html'], // Keep Playwright's HTML reporter
    ['@testivai/witness-playwright/reporter', {
      // Optional configuration
      debug: false, // Set to true for verbose logging
      compression: {
        compressUploads: true, // Enable compression for large payloads
        compressionThreshold: 5 * 1024 * 1024, // 5MB threshold
      }
    }]
  ],
  use: {
    // Your Playwright configuration
  },
});

Reporter Options

Option	Type	Default	Description
debug	boolean	false	Enable verbose logging. Can also be set via TESTIVAI_DEBUG=true
apiUrl	string	https://core-api.testiv.ai	Custom API endpoint URL
apiKey	string	process.env.TESTIVAI_API_KEY	API key (overrides environment variable)
compression	object	{}	Compression settings for uploads

---

4. Add Capture Calls

Import testivai from the SDK and call testivai.witness(page, testInfo, 'name') in your tests:

import { test } from '@playwright/test';
import { testivai } from '@testivai/witness-playwright';

test('homepage looks correct', async ({ page }, testInfo) => {
  await page.goto('http://localhost:3000');
  await testivai.witness(page, testInfo, 'homepage');
});

test('login page looks correct', async ({ page }, testInfo) => {
  await page.goto('http://localhost:3000/login');
  await testivai.witness(page, testInfo, 'login-page');
});

---

5. Full Working Example

import { test, expect } from '@playwright/test';
import { testivai } from '@testivai/witness-playwright';

test.describe('Visual Regression', () => {
  test('homepage', async ({ page }, testInfo) => {
    await page.goto('/');
    await testivai.witness(page, testInfo, 'homepage');
  });

  test('navigation state', async ({ page }, testInfo) => {
    await page.goto('/');
    await page.click('nav a[href="/about"]');
    await testivai.witness(page, testInfo, 'about-page');
  });

  test('mobile viewport', async ({ page }, testInfo) => {
    await page.setViewportSize({ width: 375, height: 812 });
    await page.goto('/');
    await testivai.witness(page, testInfo, 'homepage-mobile');
  });
});

---

6. Run

Run your tests normally with Playwright — no testivai run wrapper needed:

npx playwright test

---

CI/CD

GitHub Actions example:

- name: Install dependencies
  run: npm ci

- name: Install Playwright browsers
  run: npx playwright install --with-deps chromium

- name: Run visual tests
  run: npx playwright test
  env:
    TESTIVAI_API_KEY: ${{ secrets.TESTIVAI_API_KEY }}

---

What gets captured

Each testivai.witness() call captures the same 5-layer snapshot as the CDP SDK:

Layer	Data
Screenshot	Full-viewport PNG
DOM	Full HTML snapshot
CSS	Computed styles per element
Layout	Bounding boxes and positioning
Performance	Web Vitals and CDP metrics

---

How it works

The Playwright SDK uses Playwright's native page.screenshot(), page.evaluate(), and CDP session APIs directly — no external Chrome debugging port required. This makes it the most seamless integration for Playwright users.

→ See all captured layers

---

Version History

• v0.3.1 (Latest) - Fixed dist build (v0.3.0 shipped stale compiled code)
• v0.3.0 - Fixed reporter crash on .css.json files, added debug logging, unified format with CDP SDK
• v0.2.4 - Added performance metrics integration
• v0.2.0 - Added DOM analysis and CSS fingerprinting
• v0.1.13 - Initial public release