@testivai/witness-playwright 1.0.0

package/dist/cli/init.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createConfigFile = createConfigFile;
+const fs = __importStar(require("fs-extra"));
+const path = __importStar(require("path"));
+/**
+ * Basic CLI init script for TestivAI Playwright SDK
+ * Creates a testivai.config.ts file with sensible defaults
+ */
+const DEFAULT_CONFIG = `/**
+ * TestivAI Configuration File
+ * 
+ * This file configures how TestivAI analyzes visual differences in your tests.
+ * 
+ * Layout Settings:
+ * - sensitivity: 0-4 scale (0=strict/precise, 4=very lenient)
+ * - tolerance: Base pixel tolerance for layout differences
+ * 
+ * AI Settings:
+ * - sensitivity: 0-4 scale (0=conservative, 4=aggressive)
+ * - confidence: 0.0-1.0 scale (minimum confidence required for AI_BUG verdict)
+ * 
+ * Custom Configuration Examples:
+ * 
+ * // For strict testing (critical components):
+ * export default {
+ *   layout: { sensitivity: 0, tolerance: 0.5 },
+ *   ai: { sensitivity: 0, confidence: 0.9 }
+ * };
+ * 
+ * // For lenient testing (dynamic content):
+ * export default {
+ *   layout: { sensitivity: 4, tolerance: 3.0 },
+ *   ai: { sensitivity: 3, confidence: 0.6 }
+ * };
+ * 
+ * // Per-selector tolerances (advanced):
+ * export default {
+ *   layout: { 
+ *     sensitivity: 2, 
+ *     tolerance: 1.0,
+ *     selectorTolerances: {
+ *       '.carousel': 4.0,      // Carousel components shift
+ *       '.dropdown': 2.0,      // Dropdowns can vary
+ *       '.tooltip': 5.0,       // Tooltips are highly variable
+ *       '.submit-button': 0.5  // Critical buttons need precision
+ *     }
+ *   },
+ *   ai: { sensitivity: 2, confidence: 0.7 }
+ * };
+ * 
+ * // Environment-specific overrides:
+ * export default {
+ *   layout: { sensitivity: 2, tolerance: 1.0 },
+ *   ai: { sensitivity: 2, confidence: 0.7 },
+ *   environments: {
+ *     ci: {
+ *       layout: { sensitivity: 1, tolerance: 0.5 },  // Stricter in CI
+ *       ai: { sensitivity: 1, confidence: 0.8 }
+ *     },
+ *     development: {
+ *       layout: { sensitivity: 3, tolerance: 2.0 },  // More lenient locally
+ *       ai: { sensitivity: 3, confidence: 0.6 }
+ *     }
+ *   }
+ * };
+ */
+
+export default {
+  // Your TestivAI API key - get this from the dashboard after creating a project
+  apiKey: process.env.TESTIVAI_API_KEY || '',
+  
+  // API endpoint - automatically points to production
+  apiUrl: process.env.TESTIVAI_API_URL || 'https://core-api.testiv.ai',
+  
+  layout: {
+    sensitivity: 2,        // Balanced sensitivity (0-4 scale)
+    tolerance: 1.0,        // 1 pixel base tolerance
+  },
+  ai: {
+    sensitivity: 2,        // Balanced AI analysis (0-4 scale)
+    confidence: 0.7,       // 70% confidence required for AI_BUG
+  }
+};
+`;
+async function createConfigFile() {
+    const configPath = path.join(process.cwd(), 'testivai.config.ts');
+    // Check if config already exists
+    if (await fs.pathExists(configPath)) {
+        console.log('❌ TestivAI config already exists at:', configPath);
+        console.log('   Delete it first if you want to regenerate it.');
+        process.exit(1);
+    }
+    try {
+        // Create the config file
+        await fs.writeFile(configPath, DEFAULT_CONFIG, 'utf8');
+        console.log('✅ TestivAI configuration created successfully!');
+        console.log('📁 Config file:', configPath);
+        console.log('');
+        console.log('📖 Next steps:');
+        console.log('   1. Set up your API key:');
+        console.log('      TESTIVAI_API_KEY=tstvai-your-key-here');
+        console.log('');
+        console.log('   2. Update your playwright.config.ts to use TestivAI reporter:');
+        console.log('      reporter: [[\'@testivai/witness-playwright/reporter\']]');
+        console.log('');
+        console.log('   3. Review and customize testivai.config.ts');
+        console.log('   4. Run your tests: npx playwright test');
+        console.log('');
+        console.log('💡 Get your API key from: https://dashboard.testiv.ai');
+        console.log('💡 The SDK automatically connects to the production API - no URL configuration needed!');
+    }
+    catch (error) {
+        console.error('❌ Failed to create configuration file:', error);
+        process.exit(1);
+    }
+}
+// Main execution
+if (require.main === module) {
+    createConfigFile().catch(error => {
+        console.error('❌ CLI init failed:', error);
+        process.exit(1);
+    });
+}

package/dist/config/loader.d.ts

@@ -0,0 +1,29 @@
+import { TestivAIProjectConfig, TestivAIConfig } from '../types';
+/**
+ * Load TestivAI configuration from file system
+ * Supports both .ts and .js config files
+ *
+ * @returns Promise<TestivAIProjectConfig> The loaded configuration or defaults
+ */
+export declare function loadConfig(): Promise<TestivAIProjectConfig>;
+/**
+ * Merge per-test configuration with project configuration
+ *
+ * @param projectConfig The project-level configuration
+ * @param testConfig Optional per-test configuration overrides
+ * @returns TestivAIConfig The effective configuration for this test
+ */
+export declare function mergeTestConfig(projectConfig: TestivAIProjectConfig, testConfig?: TestivAIConfig): TestivAIConfig;
+/**
+ * Detect current environment (CI, development, production)
+ *
+ * @returns string The detected environment
+ */
+export declare function detectEnvironment(): string;
+/**
+ * Apply environment-specific overrides to configuration
+ *
+ * @param config The base configuration
+ * @returns TestivAIProjectConfig Configuration with environment overrides applied
+ */
+export declare function applyEnvironmentOverrides(config: TestivAIProjectConfig): TestivAIProjectConfig;

package/dist/config/loader.js

@@ -0,0 +1,251 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+exports.mergeTestConfig = mergeTestConfig;
+exports.detectEnvironment = detectEnvironment;
+exports.applyEnvironmentOverrides = applyEnvironmentOverrides;
+const fs = __importStar(require("fs-extra"));
+const path = __importStar(require("path"));
+/**
+ * Default configuration when no config file is found
+ */
+const DEFAULT_CONFIG = {
+    layout: {
+        sensitivity: 2, // Balanced sensitivity (0-4 scale)
+        tolerance: 1.0, // 1 pixel base tolerance
+    },
+    ai: {
+        sensitivity: 2, // Balanced AI analysis (0-4 scale)
+        confidence: 0.7, // 70% confidence required for AI_BUG
+    }
+};
+/**
+ * Load TestivAI configuration from file system
+ * Supports both .ts and .js config files
+ *
+ * @returns Promise<TestivAIProjectConfig> The loaded configuration or defaults
+ */
+async function loadConfig() {
+    // Try TypeScript config first, then JavaScript
+    const tsConfigPath = path.join(process.cwd(), 'testivai.config.ts');
+    const jsConfigPath = path.join(process.cwd(), 'testivai.config.js');
+    try {
+        let configPath;
+        let configModule;
+        // Check for TypeScript config
+        if (await fs.pathExists(tsConfigPath)) {
+            configPath = tsConfigPath;
+        }
+        else if (await fs.pathExists(jsConfigPath)) {
+            configPath = jsConfigPath;
+        }
+        else {
+            console.log('⚠️  No testivai.config.ts or testivai.config.js found, using defaults');
+            return DEFAULT_CONFIG;
+        }
+        // Load configuration based on file type
+        if (configPath.endsWith('.js')) {
+            // For .js files, use require to get CommonJS module
+            // Clear require cache to ensure fresh load
+            delete require.cache[require.resolve(configPath)];
+            configModule = require(configPath);
+        }
+        else {
+            // For .ts files, use dynamic import (ES module)
+            configModule = await Promise.resolve(`${configPath}`).then(s => __importStar(require(s)));
+        }
+        const config = configModule.default || configModule;
+        // Validate and merge with defaults
+        return validateAndMergeConfig(config);
+    }
+    catch (error) {
+        console.warn('⚠️  Failed to load testivai config, using defaults:', error);
+        return DEFAULT_CONFIG;
+    }
+}
+/**
+ * Merge per-test configuration with project configuration
+ *
+ * @param projectConfig The project-level configuration
+ * @param testConfig Optional per-test configuration overrides
+ * @returns TestivAIConfig The effective configuration for this test
+ */
+function mergeTestConfig(projectConfig, testConfig) {
+    if (!testConfig) {
+        return {
+            layout: projectConfig.layout,
+            ai: projectConfig.ai,
+            // @renamed: dom → structure (IP protection)
+            structure: projectConfig.structure,
+            performanceMetrics: projectConfig.performanceMetrics
+        };
+    }
+    return {
+        layout: {
+            ...projectConfig.layout,
+            ...testConfig.layout
+        },
+        ai: {
+            ...projectConfig.ai,
+            ...testConfig.ai
+        },
+        // @renamed: dom → structure (IP protection)
+        structure: {
+            ...projectConfig.structure,
+            ...testConfig.structure
+        },
+        performanceMetrics: {
+            ...projectConfig.performanceMetrics,
+            ...testConfig.performanceMetrics
+        },
+        selectors: testConfig.selectors,
+        useCDP: testConfig.useCDP
+    };
+}
+/**
+ * Detect current environment (CI, development, production)
+ *
+ * @returns string The detected environment
+ */
+function detectEnvironment() {
+    // Check for common CI environment variables
+    if (process.env.CI || process.env.CONTINUOUS_INTEGRATION) {
+        return 'ci';
+    }
+    // Check for production indicators
+    if (process.env.NODE_ENV === 'production') {
+        return 'production';
+    }
+    // Default to development
+    return 'development';
+}
+/**
+ * Apply environment-specific overrides to configuration
+ *
+ * @param config The base configuration
+ * @returns TestivAIProjectConfig Configuration with environment overrides applied
+ */
+function applyEnvironmentOverrides(config) {
+    const environment = detectEnvironment();
+    if (!config.environments) {
+        return config;
+    }
+    // Type-safe environment override access
+    let envOverrides;
+    switch (environment) {
+        case 'ci':
+            envOverrides = config.environments.ci;
+            break;
+        case 'development':
+            envOverrides = config.environments.development;
+            break;
+        case 'production':
+            envOverrides = config.environments.production;
+            break;
+    }
+    if (!envOverrides) {
+        return config;
+    }
+    return {
+        layout: {
+            ...config.layout,
+            ...envOverrides.layout
+        },
+        ai: {
+            ...config.ai,
+            ...envOverrides.ai
+        },
+        environments: config.environments // Keep the original environments config
+    };
+}
+/**
+ * Validate configuration values and merge with defaults
+ *
+ * @param config The configuration to validate
+ * @returns TestivAIProjectConfig Validated configuration
+ */
+function validateAndMergeConfig(config) {
+    // Guard against null/undefined config
+    if (!config) {
+        console.warn('⚠️  Config is null or undefined, using defaults');
+        return DEFAULT_CONFIG;
+    }
+    // Basic validation
+    const validatedConfig = {
+        // API configuration with production default
+        apiKey: config.apiKey,
+        apiUrl: config.apiUrl || 'https://core-api.testiv.ai',
+        layout: {
+            sensitivity: validateRange(config.layout?.sensitivity ?? DEFAULT_CONFIG.layout.sensitivity, 0, 4, 'layout.sensitivity', DEFAULT_CONFIG.layout.sensitivity),
+            tolerance: validateRange(config.layout?.tolerance ?? DEFAULT_CONFIG.layout.tolerance, 0, 100, 'layout.tolerance', DEFAULT_CONFIG.layout.tolerance),
+            selectorTolerances: config.layout?.selectorTolerances,
+            useRelativeTolerance: config.layout?.useRelativeTolerance,
+            relativeTolerance: config.layout?.relativeTolerance
+        },
+        ai: {
+            sensitivity: validateRange(config.ai?.sensitivity ?? DEFAULT_CONFIG.ai.sensitivity, 0, 4, 'ai.sensitivity', DEFAULT_CONFIG.ai.sensitivity),
+            confidence: validateRange(config.ai?.confidence ?? DEFAULT_CONFIG.ai.confidence, 0, 1, 'ai.confidence', DEFAULT_CONFIG.ai.confidence),
+            enableReasoning: config.ai?.enableReasoning
+        },
+        // @renamed: dom → structure (IP protection)
+        structure: config.structure, // Pass through structure analysis configuration as-is
+        performanceMetrics: config.performanceMetrics, // Pass through performance metrics configuration as-is
+        environments: config.environments
+    };
+    return applyEnvironmentOverrides(validatedConfig);
+}
+/**
+ * Validate that a number is within the expected range
+ *
+ * @param value The value to validate
+ * @param min Minimum allowed value
+ * @param max Maximum allowed value
+ * @param field Field name for error messages
+ * @param defaultValue Default value to use when validation fails
+ * @returns number The validated value
+ */
+function validateRange(value, min, max, field, defaultValue) {
+    const numValue = Number(value);
+    if (isNaN(numValue)) {
+        console.warn(`⚠️  Invalid ${field}: ${value}, using default: ${defaultValue}`);
+        return defaultValue;
+    }
+    if (numValue < min || numValue > max) {
+        console.warn(`⚠️  ${field} must be between ${min} and ${max}, got ${numValue}, using default: ${defaultValue}`);
+        return defaultValue;
+    }
+    return numValue;
+}

package/dist/domAnalyzer.d.ts

@@ -0,0 +1,10 @@
+import { Page } from '@playwright/test';
+import { DOMAnalysisConfig, DOMAnalysis, DOMChange } from './types';
+/**
+ * Analyzes DOM structure and generates fingerprint
+ */
+export declare function analyzeDOM(page: Page, config?: DOMAnalysisConfig): Promise<DOMAnalysis>;
+/**
+ * Compare two DOM analyses and identify changes
+ */
+export declare function compareDOMAnalysis(baseline: DOMAnalysis, current: DOMAnalysis): DOMChange[];