@clawdtesting/puppeteer 1.0.0

package/README.md

@@ -0,0 +1,257 @@
+# ClawdTest - Puppeteer SDK
+
+Official Puppeteer SDK for ClawdTest Platform.
+
+## Installation
+
+```bash
+npm install @clawdtesting/puppeteer puppeteer
+```
+
+## Quick Start
+
+```javascript
+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
+
+```javascript
+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', 'user@example.com');
+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
+
+```javascript
+// 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
+
+```javascript
+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
+
+```javascript
+// 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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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.
+
+```typescript
+import { ClawdTest, ClawdTestSession, StepResult } from '@clawdtesting/puppeteer';
+```
+
+## Error Handling
+
+```javascript
+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](./examples) directory for more usage examples:
+- Basic usage
+- CI/CD integration
+- Custom viewport testing
+- Multi-page flows
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,27 @@
+import { Page } from 'puppeteer';
+import { ClawdTestConfig, SessionOptions } from './types';
+import { ClawdTestSession } from './session';
+export declare class ClawdTest {
+    private apiClient;
+    private config;
+    constructor(config: ClawdTestConfig);
+    /**
+     * Create a new test session
+     */
+    session(page: Page, options: SessionOptions): Promise<ClawdTestSession>;
+    /**
+     * Quick check - creates session, takes screenshot, and closes session
+     */
+    check(page: Page, testName: string, stepName: string): Promise<{
+        sessionResult: import("./types").SessionResult;
+        stepId: string;
+        status: "passed" | "failed" | "new";
+        diffScore: number;
+        isNew: boolean;
+        diffImageUrl: string | null;
+    }>;
+    /**
+     * Get session details
+     */
+    getSession(sessionId: string): Promise<any>;
+}

package/dist/client.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClawdTest = void 0;
+const axios_1 = __importDefault(require("axios"));
+const session_1 = require("./session");
+class ClawdTest {
+    constructor(config) {
+        this.config = {
+            apiUrl: config.apiUrl || 'http://localhost:3001/api/v1',
+            apiKey: config.apiKey,
+            projectId: config.projectId,
+            browserName: config.browserName || 'chromium',
+            viewport: config.viewport || { width: 1280, height: 720 },
+            baselineBranch: config.baselineBranch || 'main',
+        };
+        this.apiClient = axios_1.default.create({
+            baseURL: this.config.apiUrl,
+            headers: {
+                'x-api-key': this.config.apiKey,
+                'Content-Type': 'application/json',
+            },
+        });
+    }
+    /**
+     * Create a new test session
+     */
+    async session(page, options) {
+        const sessionOptions = {
+            browserName: options.browserName || this.config.browserName,
+            viewport: options.viewport || this.config.viewport,
+            baselineBranch: options.baselineBranch || this.config.baselineBranch,
+        };
+        const response = await this.apiClient.post('/sessions', {
+            projectId: this.config.projectId,
+            testName: options.testName,
+            browserName: sessionOptions.browserName,
+            viewport: sessionOptions.viewport,
+            baselineBranch: sessionOptions.baselineBranch,
+        });
+        const { sessionId } = response.data;
+        return new session_1.ClawdTestSession(sessionId, page, this.apiClient, sessionOptions.viewport);
+    }
+    /**
+     * Quick check - creates session, takes screenshot, and closes session
+     */
+    async check(page, testName, stepName) {
+        const session = await this.session(page, { testName });
+        const result = await session.check(stepName);
+        const sessionResult = await session.close();
+        return {
+            ...result,
+            sessionResult,
+        };
+    }
+    /**
+     * Get session details
+     */
+    async getSession(sessionId) {
+        const response = await this.apiClient.get(`/sessions/${sessionId}`);
+        return response.data;
+    }
+}
+exports.ClawdTest = ClawdTest;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { ClawdTest } from './client';
+export { ClawdTestSession } from './session';
+export * from './types';

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClawdTestSession = exports.ClawdTest = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "ClawdTest", { enumerable: true, get: function () { return client_1.ClawdTest; } });
+var session_1 = require("./session");
+Object.defineProperty(exports, "ClawdTestSession", { enumerable: true, get: function () { return session_1.ClawdTestSession; } });
+__exportStar(require("./types"), exports);

package/dist/session.d.ts

@@ -0,0 +1,42 @@
+import { Page } from 'puppeteer';
+import { AxiosInstance } from 'axios';
+import { CheckOptions, StepResult, SessionResult } from './types';
+export declare class ClawdTestSession {
+    private sessionId;
+    private page;
+    private apiClient;
+    private viewport;
+    private stepCount;
+    constructor(sessionId: string, page: Page, apiClient: AxiosInstance, viewport: {
+        width: number;
+        height: number;
+    });
+    /**
+     * Take a screenshot and compare with baseline
+     */
+    check(stepNameOrOptions: string | CheckOptions): Promise<StepResult>;
+    /**
+     * Check multiple elements in sequence
+     */
+    checkMultiple(checks: Array<string | CheckOptions>): Promise<StepResult[]>;
+    /**
+     * Wait for navigation and then check
+     */
+    checkAfterNavigation(stepName: string, options?: Omit<CheckOptions, 'stepName'>): Promise<StepResult>;
+    /**
+     * Wait for selector and then check
+     */
+    checkAfterSelector(stepName: string, selector: string, options?: Omit<CheckOptions, 'stepName' | 'selector'>): Promise<StepResult>;
+    /**
+     * Complete the session
+     */
+    close(): Promise<SessionResult>;
+    /**
+     * Get current session ID
+     */
+    getSessionId(): string;
+    /**
+     * Get number of steps taken
+     */
+    getStepCount(): number;
+}

package/dist/session.js

@@ -0,0 +1,107 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClawdTestSession = void 0;
+const form_data_1 = __importDefault(require("form-data"));
+class ClawdTestSession {
+    constructor(sessionId, page, apiClient, viewport) {
+        this.stepCount = 0;
+        this.sessionId = sessionId;
+        this.page = page;
+        this.apiClient = apiClient;
+        this.viewport = viewport;
+    }
+    /**
+     * Take a screenshot and compare with baseline
+     */
+    async check(stepNameOrOptions) {
+        const options = typeof stepNameOrOptions === 'string'
+            ? { stepName: stepNameOrOptions }
+            : stepNameOrOptions;
+        // Set viewport
+        await this.page.setViewport(this.viewport);
+        // Take screenshot
+        let screenshot;
+        if (options.selector) {
+            const element = await this.page.$(options.selector);
+            if (!element) {
+                throw new Error(`Element not found: ${options.selector}`);
+            }
+            screenshot = await element.screenshot({ encoding: 'binary' });
+        }
+        else if (options.clip) {
+            screenshot = await this.page.screenshot({
+                clip: options.clip,
+                encoding: 'binary',
+            });
+        }
+        else {
+            screenshot = await this.page.screenshot({
+                fullPage: options.fullPage || false,
+                encoding: 'binary',
+            });
+        }
+        // Upload screenshot to API
+        const formData = new form_data_1.default();
+        formData.append('stepName', options.stepName);
+        formData.append('screenshot', screenshot, {
+            filename: `${options.stepName}.png`,
+            contentType: 'image/png',
+        });
+        if (options.metadata) {
+            formData.append('metadata', JSON.stringify(options.metadata));
+        }
+        const response = await this.apiClient.post(`/sessions/${this.sessionId}/steps`, formData, {
+            headers: formData.getHeaders(),
+        });
+        this.stepCount++;
+        return response.data;
+    }
+    /**
+     * Check multiple elements in sequence
+     */
+    async checkMultiple(checks) {
+        const results = [];
+        for (const check of checks) {
+            const result = await this.check(check);
+            results.push(result);
+        }
+        return results;
+    }
+    /**
+     * Wait for navigation and then check
+     */
+    async checkAfterNavigation(stepName, options) {
+        await this.page.waitForNavigation({ waitUntil: 'networkidle0' });
+        return this.check({ stepName, ...options });
+    }
+    /**
+     * Wait for selector and then check
+     */
+    async checkAfterSelector(stepName, selector, options) {
+        await this.page.waitForSelector(selector);
+        return this.check({ stepName, selector, ...options });
+    }
+    /**
+     * Complete the session
+     */
+    async close() {
+        const response = await this.apiClient.post(`/sessions/${this.sessionId}/complete`);
+        return response.data;
+    }
+    /**
+     * Get current session ID
+     */
+    getSessionId() {
+        return this.sessionId;
+    }
+    /**
+     * Get number of steps taken
+     */
+    getStepCount() {
+        return this.stepCount;
+    }
+}
+exports.ClawdTestSession = ClawdTestSession;

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+export interface ClawdTestConfig {
+    apiKey: string;
+    apiUrl?: string;
+    projectId: string;
+    browserName?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    baselineBranch?: string;
+}
+export interface SessionOptions {
+    testName: string;
+    browserName?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    baselineBranch?: string;
+}
+export interface StepResult {
+    stepId: string;
+    status: 'passed' | 'failed' | 'new';
+    diffScore: number;
+    isNew: boolean;
+    diffImageUrl: string | null;
+}
+export interface SessionResult {
+    sessionId: string;
+    status: 'passed' | 'failed' | 'unresolved';
+    totalSteps: number;
+    passedSteps: number;
+    failedSteps: number;
+    newSteps: number;
+}
+export interface CheckOptions {
+    stepName: string;
+    fullPage?: boolean;
+    selector?: string;
+    clip?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    metadata?: Record<string, any>;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/examples/basic.js

@@ -0,0 +1,50 @@
+const puppeteer = require('puppeteer');
+const { ClawdTest } = require('../dist');
+
+async function basicExample() {
+  // Initialize ClawdTest client
+  const clawdTest = new ClawdTest({
+    apiKey: process.env.CLAWDTEST_API_KEY || 'your-api-key',
+    apiUrl: process.env.CLAWDTEST_API_URL || 'http://localhost:3001/api/v1',
+    projectId: process.env.CLAWDTEST_PROJECT_ID || 'your-project-id',
+  });
+
+  // Launch browser
+  const browser = await puppeteer.launch({
+    headless: true,
+  });
+
+  const page = await browser.newPage();
+
+  try {
+    // Navigate to page
+    await page.goto('https://example.com');
+
+    // Quick check
+    const result = await clawdTest.check(
+      page,
+      'Example.com Test',
+      'Homepage',
+    );
+
+    console.log('✓ Test completed');
+    console.log('  Status:', result.status);
+    console.log('  Diff Score:', result.diffScore);
+
+    if (result.status === 'failed') {
+      console.log('  Diff Image:', result.diffImageUrl);
+    }
+
+    // Exit with error code if test failed
+    if (result.sessionResult.status === 'failed') {
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error('✗ Test failed:', error.message);
+    process.exit(1);
+  } finally {
+    await browser.close();
+  }
+}
+
+basicExample();

package/examples/session.js

@@ -0,0 +1,72 @@
+const puppeteer = require('puppeteer');
+const { ClawdTest } = require('../dist');
+
+async function sessionExample() {
+  const clawdTest = new ClawdTest({
+    apiKey: process.env.CLAWDTEST_API_KEY || 'your-api-key',
+    apiUrl: process.env.CLAWDTEST_API_URL || 'http://localhost:3001/api/v1',
+    projectId: process.env.CLAWDTEST_PROJECT_ID || 'your-project-id',
+  });
+
+  const browser = await puppeteer.launch({ headless: true });
+  const page = await browser.newPage();
+
+  try {
+    // Create session
+    const session = await clawdTest.session(page, {
+      testName: 'Multi-Step User Flow',
+      viewport: { width: 1920, height: 1080 },
+    });
+
+    console.log('Session created:', session.getSessionId());
+
+    // Step 1: Homepage
+    await page.goto('https://example.com');
+    let result = await session.check('Homepage');
+    console.log('Step 1 - Homepage:', result.status);
+
+    // Step 2: Scroll to section
+    await page.evaluate(() => window.scrollTo(0, 500));
+    result = await session.check({
+      stepName: 'Middle Section',
+      metadata: { scrollY: 500 },
+    });
+    console.log('Step 2 - Middle Section:', result.status);
+
+    // Step 3: Check specific element
+    result = await session.check({
+      stepName: 'Main Content',
+      selector: 'main',
+    });
+    console.log('Step 3 - Main Content:', result.status);
+
+    // Step 4: Full page
+    result = await session.check({
+      stepName: 'Full Page',
+      fullPage: true,
+    });
+    console.log('Step 4 - Full Page:', result.status);
+
+    // Complete session
+    const sessionResult = await session.close();
+
+    console.log('\n✓ Session completed');
+    console.log('  Total Steps:', sessionResult.totalSteps);
+    console.log('  Passed:', sessionResult.passedSteps);
+    console.log('  Failed:', sessionResult.failedSteps);
+    console.log('  New:', sessionResult.newSteps);
+    console.log('  Status:', sessionResult.status);
+
+    // Exit with error code if any failures
+    if (sessionResult.status === 'failed') {
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error('✗ Test failed:', error.message);
+    process.exit(1);
+  } finally {
+    await browser.close();
+  }
+}
+
+sessionExample();

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@clawdtesting/puppeteer",
+  "version": "1.0.0",
+  "description": "Visual Testing SDK for Puppeteer",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "jest",
+    "prepublish": "npm run build"
+  },
+  "keywords": [
+    "visual-testing",
+    "puppeteer",
+    "screenshot",
+    "regression-testing"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "puppeteer": "^21.9.0",
+    "axios": "^1.6.5",
+    "form-data": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@types/puppeteer": "^7.0.4",
+    "typescript": "^5.3.3",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1"
+  },
+  "peerDependencies": {
+    "puppeteer": "^21.0.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,78 @@
+import axios, { AxiosInstance } from 'axios';
+import { Page } from 'puppeteer';
+import { ClawdTestConfig, SessionOptions } from './types';
+import { ClawdTestSession } from './session';
+
+export class ClawdTest {
+  private apiClient: AxiosInstance;
+  private config: Required<ClawdTestConfig>;
+
+  constructor(config: ClawdTestConfig) {
+    this.config = {
+      apiUrl: config.apiUrl || 'http://localhost:3001/api/v1',
+      apiKey: config.apiKey,
+      projectId: config.projectId,
+      browserName: config.browserName || 'chromium',
+      viewport: config.viewport || { width: 1280, height: 720 },
+      baselineBranch: config.baselineBranch || 'main',
+    };
+
+    this.apiClient = axios.create({
+      baseURL: this.config.apiUrl,
+      headers: {
+        'x-api-key': this.config.apiKey,
+        'Content-Type': 'application/json',
+      },
+    });
+  }
+
+  /**
+   * Create a new test session
+   */
+  async session(page: Page, options: SessionOptions): Promise<ClawdTestSession> {
+    const sessionOptions = {
+      browserName: options.browserName || this.config.browserName,
+      viewport: options.viewport || this.config.viewport,
+      baselineBranch: options.baselineBranch || this.config.baselineBranch,
+    };
+
+    const response = await this.apiClient.post('/sessions', {
+      projectId: this.config.projectId,
+      testName: options.testName,
+      browserName: sessionOptions.browserName,
+      viewport: sessionOptions.viewport,
+      baselineBranch: sessionOptions.baselineBranch,
+    });
+
+    const { sessionId } = response.data;
+
+    return new ClawdTestSession(
+      sessionId,
+      page,
+      this.apiClient,
+      sessionOptions.viewport,
+    );
+  }
+
+  /**
+   * Quick check - creates session, takes screenshot, and closes session
+   */
+  async check(page: Page, testName: string, stepName: string) {
+    const session = await this.session(page, { testName });
+    const result = await session.check(stepName);
+    const sessionResult = await session.close();
+
+    return {
+      ...result,
+      sessionResult,
+    };
+  }
+
+  /**
+   * Get session details
+   */
+  async getSession(sessionId: string) {
+    const response = await this.apiClient.get(`/sessions/${sessionId}`);
+    return response.data;
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { ClawdTest } from './client';
+export { ClawdTestSession } from './session';
+export * from './types';

package/src/session.ts

@@ -0,0 +1,147 @@
+import { Page } from 'puppeteer';
+import { AxiosInstance } from 'axios';
+import FormData from 'form-data';
+import { CheckOptions, StepResult, SessionResult } from './types';
+
+export class ClawdTestSession {
+  private sessionId: string;
+  private page: Page;
+  private apiClient: AxiosInstance;
+  private viewport: { width: number; height: number };
+  private stepCount: number = 0;
+
+  constructor(
+    sessionId: string,
+    page: Page,
+    apiClient: AxiosInstance,
+    viewport: { width: number; height: number },
+  ) {
+    this.sessionId = sessionId;
+    this.page = page;
+    this.apiClient = apiClient;
+    this.viewport = viewport;
+  }
+
+  /**
+   * Take a screenshot and compare with baseline
+   */
+  async check(
+    stepNameOrOptions: string | CheckOptions,
+  ): Promise<StepResult> {
+    const options: CheckOptions =
+      typeof stepNameOrOptions === 'string'
+        ? { stepName: stepNameOrOptions }
+        : stepNameOrOptions;
+
+    // Set viewport
+    await this.page.setViewport(this.viewport);
+
+    // Take screenshot
+    let screenshot: Buffer;
+
+    if (options.selector) {
+      const element = await this.page.$(options.selector);
+      if (!element) {
+        throw new Error(`Element not found: ${options.selector}`);
+      }
+      screenshot = await element.screenshot({ encoding: 'binary' }) as Buffer;
+    } else if (options.clip) {
+      screenshot = await this.page.screenshot({
+        clip: options.clip,
+        encoding: 'binary',
+      }) as Buffer;
+    } else {
+      screenshot = await this.page.screenshot({
+        fullPage: options.fullPage || false,
+        encoding: 'binary',
+      }) as Buffer;
+    }
+
+    // Upload screenshot to API
+    const formData = new FormData();
+    formData.append('stepName', options.stepName);
+    formData.append('screenshot', screenshot, {
+      filename: `${options.stepName}.png`,
+      contentType: 'image/png',
+    });
+
+    if (options.metadata) {
+      formData.append('metadata', JSON.stringify(options.metadata));
+    }
+
+    const response = await this.apiClient.post(
+      `/sessions/${this.sessionId}/steps`,
+      formData,
+      {
+        headers: formData.getHeaders(),
+      },
+    );
+
+    this.stepCount++;
+
+    return response.data as StepResult;
+  }
+
+  /**
+   * Check multiple elements in sequence
+   */
+  async checkMultiple(
+    checks: Array<string | CheckOptions>,
+  ): Promise<StepResult[]> {
+    const results: StepResult[] = [];
+
+    for (const check of checks) {
+      const result = await this.check(check);
+      results.push(result);
+    }
+
+    return results;
+  }
+
+  /**
+   * Wait for navigation and then check
+   */
+  async checkAfterNavigation(
+    stepName: string,
+    options?: Omit<CheckOptions, 'stepName'>,
+  ): Promise<StepResult> {
+    await this.page.waitForNavigation({ waitUntil: 'networkidle0' });
+    return this.check({ stepName, ...options });
+  }
+
+  /**
+   * Wait for selector and then check
+   */
+  async checkAfterSelector(
+    stepName: string,
+    selector: string,
+    options?: Omit<CheckOptions, 'stepName' | 'selector'>,
+  ): Promise<StepResult> {
+    await this.page.waitForSelector(selector);
+    return this.check({ stepName, selector, ...options });
+  }
+
+  /**
+   * Complete the session
+   */
+  async close(): Promise<SessionResult> {
+    const response = await this.apiClient.post(
+      `/sessions/${this.sessionId}/complete`,
+    );
+    return response.data as SessionResult;
+  }
+
+  /**
+   * Get current session ID
+   */
+  getSessionId(): string {
+    return this.sessionId;
+  }
+
+  /**
+   * Get number of steps taken
+   */
+  getStepCount(): number {
+    return this.stepCount;
+  }
+}

package/src/types.ts

@@ -0,0 +1,51 @@
+export interface ClawdTestConfig {
+  apiKey: string;
+  apiUrl?: string;
+  projectId: string;
+  browserName?: string;
+  viewport?: {
+    width: number;
+    height: number;
+  };
+  baselineBranch?: string;
+}
+
+export interface SessionOptions {
+  testName: string;
+  browserName?: string;
+  viewport?: {
+    width: number;
+    height: number;
+  };
+  baselineBranch?: string;
+}
+
+export interface StepResult {
+  stepId: string;
+  status: 'passed' | 'failed' | 'new';
+  diffScore: number;
+  isNew: boolean;
+  diffImageUrl: string | null;
+}
+
+export interface SessionResult {
+  sessionId: string;
+  status: 'passed' | 'failed' | 'unresolved';
+  totalSteps: number;
+  passedSteps: number;
+  failedSteps: number;
+  newSteps: number;
+}
+
+export interface CheckOptions {
+  stepName: string;
+  fullPage?: boolean;
+  selector?: string;
+  clip?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  metadata?: Record<string, any>;
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.spec.ts"]
+}