ClawdTest - Puppeteer SDK

Official Puppeteer SDK for ClawdTest Platform.

Installation

npm install @clawdtesting/puppeteer puppeteer

Quick Start

const puppeteer = require('puppeteer');
const { ClawdTest } = require('@clawdtesting/puppeteer');

// Initialize client
const clawdTest = new ClawdTest({
  apiKey: 'your-api-key',
  apiUrl: 'http://localhost:3001/api/v1',
  projectId: 'your-project-id',
});

(async () => {
  // Launch browser
  const browser = await puppeteer.launch();
  const page = await browser.newPage();

  // Navigate to page
  await page.goto('https://example.com');

  // Quick check (single screenshot)
  const result = await clawdTest.check(page, 'Homepage Test', 'Landing Page');
  
  console.log('Test result:', result.status); // 'passed', 'failed', or 'new'

  await browser.close();
})();

Advanced Usage

Session-based Testing

const session = await clawdTest.session(page, {
  testName: 'User Flow Test',
  viewport: { width: 1920, height: 1080 },
  baselineBranch: 'main',
});

// Take multiple screenshots
await page.goto('https://example.com');
await session.check('Homepage');

await page.click('#login-button');
await session.check('Login Modal');

await page.type('#username', '[email protected]');
await page.type('#password', 'password123');
await session.check('Login Form Filled');

await page.click('#submit');
await session.checkAfterNavigation('Dashboard');

// Complete session
const sessionResult = await session.close();

console.log('Session completed:', {
  status: sessionResult.status,
  totalSteps: sessionResult.totalSteps,
  passedSteps: sessionResult.passedSteps,
  failedSteps: sessionResult.failedSteps,
  newSteps: sessionResult.newSteps,
});

Screenshot Options

// Full page screenshot
await session.check({
  stepName: 'Full Page',
  fullPage: true,
});

// Specific element
await session.check({
  stepName: 'Header',
  selector: '#header',
});

// Custom clip region
await session.check({
  stepName: 'Hero Section',
  clip: { x: 0, y: 0, width: 1200, height: 600 },
});

// With metadata
await session.check({
  stepName: 'Product Page',
  metadata: {
    productId: '12345',
    category: 'electronics',
  },
});

Multiple Checks

const results = await session.checkMultiple([
  'Homepage',
  { stepName: 'Header', selector: '#header' },
  { stepName: 'Footer', selector: '#footer' },
  { stepName: 'Sidebar', selector: '.sidebar' },
]);

results.forEach((result) => {
  console.log(`${result.stepId}: ${result.status}`);
});

Wait for Elements

// Wait for selector before checking
await session.checkAfterSelector('Product List', '.product-grid');

// Wait for navigation before checking
await page.click('#next-page');
await session.checkAfterNavigation('Page 2');

Configuration

ClawdTestConfig

interface ClawdTestConfig {
  apiKey: string;              // Required: Your API key
  apiUrl?: string;             // Optional: API endpoint (default: http://localhost:3001/api/v1)
  projectId: string;           // Required: Project ID
  browserName?: string;        // Optional: Browser name (default: 'chromium')
  viewport?: {                 // Optional: Default viewport
    width: number;
    height: number;
  };
  baselineBranch?: string;     // Optional: Baseline branch (default: 'main')
}

SessionOptions

interface SessionOptions {
  testName: string;            // Required: Test name
  browserName?: string;        // Optional: Override browser name
  viewport?: {                 // Optional: Override viewport
    width: number;
    height: number;
  };
  baselineBranch?: string;     // Optional: Override baseline branch
}

CheckOptions

interface CheckOptions {
  stepName: string;            // Required: Step name
  fullPage?: boolean;          // Optional: Full page screenshot
  selector?: string;           // Optional: CSS selector for element
  clip?: {                     // Optional: Screenshot region
    x: number;
    y: number;
    width: number;
    height: number;
  };
  metadata?: Record<string, any>; // Optional: Custom metadata
}

API Reference

ClawdTest Class

constructor(config: ClawdTestConfig)

Create a new ClawdTest client.

async session(page: Page, options: SessionOptions): Promise<ClawdTestSession>

Create a new test session.

async check(page: Page, testName: string, stepName: string)

Quick check - creates session, takes screenshot, and closes session.

async getSession(sessionId: string)

Get session details.

ClawdTestSession Class

async check(stepNameOrOptions: string | CheckOptions): Promise<StepResult>

Take a screenshot and compare with baseline.

async checkMultiple(checks: Array<string | CheckOptions>): Promise<StepResult[]>

Check multiple elements in sequence.

async checkAfterNavigation(stepName: string, options?: Omit<CheckOptions, 'stepName'>): Promise<StepResult>

Wait for navigation and then check.

async checkAfterSelector(stepName: string, selector: string, options?: Omit<CheckOptions, 'stepName' | 'selector'>): Promise<StepResult>

Wait for selector and then check.

async close(): Promise<SessionResult>

Complete the session.

getSessionId(): string

Get current session ID.

getStepCount(): number

Get number of steps taken.

TypeScript Support

This SDK is written in TypeScript and includes type definitions.

import { ClawdTest, ClawdTestSession, StepResult } from '@clawdtesting/puppeteer';

Error Handling

try {
  const result = await session.check('Homepage');
  
  if (result.status === 'failed') {
    console.error('Visual regression detected!');
    console.log('Diff score:', result.diffScore);
    console.log('Diff image:', result.diffImageUrl);
  }
} catch (error) {
  console.error('Test failed:', error.message);
}

Examples

See the examples directory for more usage examples:

• Basic usage
• CI/CD integration
• Custom viewport testing
• Multi-page flows

License

MIT