@testivai/witness-cdp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 TestivAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,405 @@
+# @testivai/witness-cdp
+
+Framework-agnostic visual regression testing SDK using Chrome DevTools Protocol.
+
+## Overview
+
+The TestivAI CDP SDK allows you to integrate visual regression testing into any test framework that can control Chrome/Chromium browsers. It works by connecting directly to the Chrome DevTools Protocol (CDP) and injecting a `window.testivaiWitness` function that triggers visual captures.
+
+## Installation
+
+```bash
+npm install -g @testivai/witness-cdp
+```
+
+## Quick Start
+
+1. **Initialize your project**
+   ```bash
+   npx testivai init
+   ```
+
+2. **Authenticate with your API key**
+   ```bash
+   npx testivai auth <your-api-key>
+   ```
+
+3. **Add visual captures to your tests**
+   ```javascript
+   // In your test code
+   await window.testivaiWitness('my-snapshot');
+   ```
+
+4. **Run your tests**
+   ```bash
+   # Make sure Chrome is running with remote debugging
+   chrome --remote-debugging-port=9222
+   
+   # Run your tests with TestivAI
+   testivai run "npm test"
+   ```
+
+## Framework Integration
+
+### Cypress
+
+Add this custom command to `cypress/support/commands.js`:
+
+```javascript
+// testivai-witness-cdp.js
+Cypress.Commands.add('witness', (name) => {
+  return cy.window().invoke('testivaiWitness', name);
+});
+```
+
+Use in your tests:
+
+```javascript
+it('should capture visual snapshot', () => {
+  cy.visit('/my-page');
+  cy.witness('my-snapshot');
+});
+```
+
+Run tests:
+```bash
+testivai run "cypress run"
+```
+
+### Selenium (Python)
+
+```python
+from selenium import webdriver
+
+def capture_snapshot(driver, name):
+    driver.execute_script(f"return window.testivaiWitness('{name}')")
+
+def test_visual_snapshot():
+    driver = webdriver.Chrome()
+    driver.get("http://localhost:3000")
+    capture_snapshot(driver, "my-snapshot")
+```
+
+Run tests:
+```bash
+testivai run "pytest tests/"
+```
+
+### Selenium (JavaScript)
+
+```javascript
+const { Builder, By } = require('selenium-webdriver');
+
+async function captureSnapshot(driver, name) {
+  await driver.executeScript(`return window.testivaiWitness('${name}')`);
+}
+
+it('should capture visual snapshot', async () => {
+  const driver = await new Builder().forBrowser('chrome').build();
+  await driver.get('http://localhost:3000');
+  await captureSnapshot(driver, 'my-snapshot');
+});
+```
+
+Run tests:
+```bash
+testivai run "npm test"
+```
+
+### WebdriverIO
+
+Add this custom command to your test setup:
+
+```javascript
+// In wdio.conf.js or test setup
+browser.addCommand('witness', function(name) {
+  return this.executeScript('return window.testivaiWitness(arguments[0])', name);
+});
+```
+
+Use in your tests:
+
+```javascript
+it('should capture visual snapshot', async () => {
+  await browser.url('/my-page');
+  await browser.witness('my-snapshot');
+});
+```
+
+Run tests:
+```bash
+testivai run "npx wdio"
+```
+
+## How It Works
+
+1. **CDP Connection**: The SDK connects to Chrome's DevTools Protocol (usually on port 9222)
+2. **Binding Injection**: Using `Runtime.addBinding`, it injects a native function `window.testivaiWitness`
+3. **Promise Wrapper**: A client-side script wraps the native binding in a Promise for async/await support
+4. **Capture Trigger**: When `window.testivaiWitness('name')` is called, it triggers:
+   - Screenshot capture
+   - DOM extraction
+   - Layout analysis
+   - Performance metrics
+5. **Batch Upload**: All captures are batched and uploaded to TestivAI for analysis
+
+## Configuration
+
+Create a `testivai.config.ts` file in your project root:
+
+```typescript
+import type { CdpConfig } from '@testivai/witness-cdp';
+
+const config: CdpConfig = {
+  // API key (set via TESTIVAI_API_KEY environment variable)
+  // apiKey: 'your-api-key-here',
+  
+  // Project ID from TestivAI dashboard
+  // projectId: 'your-project-id-here',
+  
+  // Chrome DevTools Protocol port
+  cdpPort: 9222,
+  
+  // Auto-launch Chrome if not running (experimental)
+  autoLaunch: false,
+  
+  // Chrome executable path (for auto-launch)
+  // chromePath: '/path/to/chrome',
+  
+  // Additional Chrome arguments
+  chromeArgs: [
+    '--no-sandbox',
+    '--disable-dev-shm-usage',
+    '--disable-gpu',
+  ],
+  
+  // Connection settings
+  connectionTimeout: 5000,
+  connectionRetries: 3,
+};
+
+export default config;
+```
+
+## CLI Commands
+
+### `npx testivai init`
+Initialize TestivAI in your project. Detects your framework and provides setup instructions.
+
+### `npx testivai auth <api-key>`
+Authenticate with your TestivAI API key. Get your key from the [dashboard](https://dashboard.testiv.ai).
+
+### `npx testivai run <command>`
+Run your test command with automatic visual capture.
+
+```bash
+npx testivai run "npm test"
+npx testivai run "cypress run"
+npx testivai run "pytest tests/"
+```
+
+Options:
+- `-p, --port <number>` - Specify CDP port (default: 9222)
+- `-b, --batch-id <id>` - Specify batch ID (auto-generated if not provided)
+
+### `npx testivai capture <name>`
+Capture a single snapshot without running tests.
+
+```bash
+npx testivai capture "my-snapshot" --format json
+```
+
+Options:
+- `-p, --port <number>` - Specify CDP port
+- `-o, --output <path>` - Output directory (default: .testivai/captures)
+- `-f, --format <format>` - Output format: json|png (default: json)
+
+## Chrome Setup
+
+### Manual Launch
+
+Launch Chrome with remote debugging enabled:
+
+```bash
+# macOS
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222
+
+# Windows
+"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
+
+# Linux
+google-chrome --remote-debugging-port=9222
+```
+
+### Common Chrome Arguments
+
+```bash
+chrome \
+  --remote-debugging-port=9222 \
+  --no-sandbox \
+  --disable-dev-shm-usage \
+  --disable-gpu \
+  --headless  # For CI environments
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: Visual Tests
+on: [push, pull_request]
+
+jobs:
+  visual:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          
+      - name: Install dependencies
+        run: npm ci
+        
+      - name: Install TestivAI CDP SDK
+        run: npm install -g @testivai/witness-cdp
+        
+      - name: Start Chrome
+        run: |
+          google-chrome \
+            --remote-debugging-port=9222 \
+            --no-sandbox \
+            --disable-dev-shm-usage \
+            --headless \
+            --disable-gpu &
+            
+      - name: Authenticate
+        run: testivai auth ${{ secrets.TESTIVAI_API_KEY }}
+        
+      - name: Run visual tests
+        run: testivai run "npm test"
+```
+
+### Jenkins
+
+```groovy
+pipeline {
+  agent any
+  
+  stages {
+    stage('Setup') {
+      steps {
+        sh 'npm ci'
+        sh 'npm install -g @testivai/witness-cdp'
+      }
+    }
+    
+    stage('Start Chrome') {
+      steps {
+        sh '''
+          google-chrome \
+            --remote-debugging-port=9222 \
+            --no-sandbox \
+            --disable-dev-shm-usage \
+            --headless &
+        '''
+      }
+    }
+    
+    stage('Visual Tests') {
+      steps {
+        withCredentials([string(credentialsId: 'testivai-api-key', variable: 'API_KEY')]) {
+          sh 'testivai auth $API_KEY'
+          sh 'testivai run "npm test"'
+        }
+      }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+### Chrome not found
+```
+❌ Chrome DevTools Protocol not found
+```
+
+**Solution**: Make sure Chrome is running with remote debugging:
+```bash
+chrome --remote-debugging-port=9222
+```
+
+### Connection timeout
+```
+❌ Failed to connect to CDP: Connection timeout
+```
+
+**Solution**: 
+1. Check if Chrome is running
+2. Verify the port number (default: 9222)
+3. Check for firewall issues
+
+### Tests hang after calling testivaiWitness
+**Solution**: The Promise wrapper might not be working. Check browser console for errors and ensure CDP is properly connected.
+
+### No snapshots captured
+**Solution**: 
+1. Verify `window.testivaiWitness` is available in your tests
+2. Check that the SDK is connected before running tests
+3. Enable verbose logging: `testivai run "npm test" --verbose`
+
+## Performance
+
+- **Package size**: ~270KB (no browser binaries included)
+- **Memory usage**: ~50MB additional overhead
+- **Capture time**: ~100-500ms per snapshot
+- **Upload time**: Depends on network and snapshot size
+
+## API Reference
+
+### CdpClient
+Main class for connecting to Chrome DevTools Protocol.
+
+```typescript
+import { CdpClient } from '@testivai/witness-cdp';
+
+const client = new CdpClient();
+await client.connect(9222);
+await client.send('Page.navigate', { url: 'https://example.com' });
+await client.disconnect();
+```
+
+### CdpCapture
+Handles screenshot and data capture.
+
+```typescript
+import { CdpCapture } from '@testivai/witness-cdp';
+
+const capture = new CdpCapture(client);
+const snapshot = await capture.captureSnapshot('my-snapshot');
+```
+
+### CdpBinding
+Manages the `window.testivaiWitness` binding.
+
+```typescript
+import { CdpBinding } from '@testivai/witness-cdp';
+
+const binding = new CdpBinding(client);
+await binding.setupBindings();
+const snapshots = binding.getSnapshots();
+```
+
+## License
+
+MIT
+
+## Support
+
+- Documentation: https://docs.testiv.ai/cdp
+- Issues: https://github.com/testivai/testivai-monorepo/issues
+- Email: support@testiv.ai

package/dist/__tests__/setup.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Jest test setup
+ */
+//# sourceMappingURL=setup.d.ts.map

package/dist/__tests__/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/__tests__/setup.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/__tests__/setup.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Jest test setup
+ */
+// Mock console methods to reduce noise in tests
+global.console = {
+    ...console,
+    // Uncomment to suppress console.log during tests
+    // log: jest.fn(),
+    // debug: jest.fn(),
+    // info: jest.fn(),
+    // warn: jest.fn(),
+    // error: jest.fn(),
+};
+// Set test timeout
+jest.setTimeout(10000);
+// Mock environment variables
+process.env.NODE_ENV = 'test';
+process.env.TESTIVAI_API_URL = 'http://localhost:3000';
+// Global test utilities
+global.mockFetch = jest.fn();
+// Mock fetch globally
+global.fetch = global.mockFetch;
+//# sourceMappingURL=setup.js.map

package/dist/__tests__/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../src/__tests__/setup.ts"],"names":[],"mappings":";AAAA;;GAEG;AAEH,gDAAgD;AAChD,MAAM,CAAC,OAAO,GAAG;IACf,GAAG,OAAO;IACV,iDAAiD;IACjD,kBAAkB;IAClB,oBAAoB;IACpB,mBAAmB;IACnB,mBAAmB;IACnB,oBAAoB;CACrB,CAAC;AAEF,mBAAmB;AACnB,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;AAEvB,6BAA6B;AAC7B,OAAO,CAAC,GAAG,CAAC,QAAQ,GAAG,MAAM,CAAC;AAC9B,OAAO,CAAC,GAAG,CAAC,gBAAgB,GAAG,uBAAuB,CAAC;AAEvD,wBAAwB;AACvB,MAAc,CAAC,SAAS,GAAG,IAAI,CAAC,EAAE,EAAE,CAAC;AAEtC,sBAAsB;AACrB,MAAc,CAAC,KAAK,GAAI,MAAc,CAAC,SAAS,CAAC"}

package/dist/bin/testivai.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=testivai.d.ts.map

package/dist/bin/testivai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testivai.d.ts","sourceRoot":"","sources":["../../src/bin/testivai.ts"],"names":[],"mappings":""}

package/dist/bin/testivai.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const chalk_1 = __importDefault(require("chalk"));
+const auth_1 = require("../commands/auth");
+const init_1 = require("../commands/init");
+const run_1 = require("../commands/run");
+const capture_1 = require("../commands/capture");
+const packageJson = require('../../package.json');
+const program = new commander_1.Command();
+// Display banner
+const showBanner = () => {
+    console.log();
+    console.log(chalk_1.default.cyan.bold('  TestivAI'));
+    console.log(chalk_1.default.gray('  Catch Visual Bugs Automatically'));
+    console.log(chalk_1.default.gray('  AI that catches real bugs, ignores the noise.'));
+    console.log();
+};
+program
+    .name('testivai')
+    .description('TestivAI CDP SDK - Framework-agnostic visual regression testing')
+    .version(packageJson.version, '-v, --version', 'Display version number')
+    .hook('preAction', () => {
+    if (!process.argv.includes('--quiet') && !process.argv.includes('-q')) {
+        showBanner();
+    }
+});
+// Global options
+program
+    .option('-v, --verbose', 'Enable verbose output')
+    .option('-q, --quiet', 'Suppress output (ideal for CI)')
+    .option('--debug', 'Enable debug mode');
+// Add commands
+program.addCommand(auth_1.authCommand);
+program.addCommand(init_1.initCommand);
+program.addCommand(run_1.runCommand);
+program.addCommand(capture_1.witnessCommand);
+// Parse arguments
+program.parse();
+// Show help if no command provided
+if (!process.argv.slice(2).length) {
+    program.outputHelp();
+}
+//# sourceMappingURL=testivai.js.map

package/dist/bin/testivai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testivai.js","sourceRoot":"","sources":["../../src/bin/testivai.ts"],"names":[],"mappings":";;;;;;AAEA,yCAAoC;AACpC,kDAA0B;AAC1B,2CAA+C;AAC/C,2CAA+C;AAC/C,yCAA6C;AAC7C,iDAAqD;AAErD,MAAM,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAElD,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;AAE9B,iBAAiB;AACjB,MAAM,UAAU,GAAG,GAAG,EAAE;IACtB,OAAO,CAAC,GAAG,EAAE,CAAC;IACd,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;IAC3C,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC,CAAC;IAC7D,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,IAAI,CAAC,iDAAiD,CAAC,CAAC,CAAC;IAC3E,OAAO,CAAC,GAAG,EAAE,CAAC;AAChB,CAAC,CAAC;AAEF,OAAO;KACJ,IAAI,CAAC,UAAU,CAAC;KAChB,WAAW,CAAC,iEAAiE,CAAC;KAC9E,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,eAAe,EAAE,wBAAwB,CAAC;KACvE,IAAI,CAAC,WAAW,EAAE,GAAG,EAAE;IACtB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACtE,UAAU,EAAE,CAAC;IACf,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,iBAAiB;AACjB,OAAO;KACJ,MAAM,CAAC,eAAe,EAAE,uBAAuB,CAAC;KAChD,MAAM,CAAC,aAAa,EAAE,gCAAgC,CAAC;KACvD,MAAM,CAAC,SAAS,EAAE,mBAAmB,CAAC,CAAC;AAE1C,eAAe;AACf,OAAO,CAAC,UAAU,CAAC,kBAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,kBAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,gBAAU,CAAC,CAAC;AAC/B,OAAO,CAAC,UAAU,CAAC,wBAAc,CAAC,CAAC;AAEnC,kBAAkB;AAClB,OAAO,CAAC,KAAK,EAAE,CAAC;AAEhB,mCAAmC;AACnC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAClC,OAAO,CAAC,UAAU,EAAE,CAAC;AACvB,CAAC"}

package/dist/cdp/binding.d.ts

@@ -0,0 +1,56 @@
+import { CdpClient } from './client';
+/**
+ * CDP Binding management
+ */
+export declare class CdpBinding {
+    private client;
+    private capture;
+    private snapshots;
+    private isBindingRegistered;
+    private pollInterval?;
+    private logger;
+    constructor(client: CdpClient, options?: {
+        debug?: boolean;
+    });
+    /**
+     * Set up the Runtime bindings
+     */
+    setupBindings(): Promise<void>;
+    /**
+     * Inject the client-side script into all pages
+     */
+    private injectClientScript;
+    /**
+     * Set up polling for capture requests
+     */
+    private setupEventListeners;
+    /**
+     * Handle a witness binding call
+     */
+    private handleWitnessCall;
+    /**
+     * Capture performance metrics using CDP Performance API
+     */
+    private capturePerformanceMetrics;
+    /**
+     * Send ACK to resolve the Promise
+     */
+    private sendAck;
+    /**
+     * Get all captured snapshots
+     */
+    getSnapshots(): any[];
+    /**
+     * Clear all captured snapshots
+     */
+    clearSnapshots(): void;
+    /**
+     * Check if bindings are registered
+     */
+    isRegistered(): boolean;
+    /**
+     * Clean up resources
+     */
+    cleanup(): void;
+}
+//# sourceMappingURL=binding.d.ts.map

package/dist/cdp/binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../src/cdp/binding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAoCrC;;GAEG;AACH,qBAAa,UAAU;IAOT,OAAO,CAAC,MAAM;IAN1B,OAAO,CAAC,OAAO,CAAa;IAC5B,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,YAAY,CAAC,CAAiB;IACtC,OAAO,CAAC,MAAM,CAAM;gBAEA,MAAM,EAAE,SAAS,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;IAOxE;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBpC;;OAEG;YACW,kBAAkB;IA2BhC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA8D3B;;OAEG;YACW,iBAAiB;IAwE/B;;OAEG;YACW,yBAAyB;IA4GvC;;OAEG;YACW,OAAO;IAWrB;;OAEG;IACH,YAAY,IAAI,GAAG,EAAE;IAIrB;;OAEG;IACH,cAAc,IAAI,IAAI;IAKtB;;OAEG;IACH,YAAY,IAAI,OAAO;IAIvB;;OAEG;IACH,OAAO,IAAI,IAAI;CAMhB"}