@testivai/witness-playwright 0.1.0

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,232 @@
+"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
+        };
+    }
+    return {
+        layout: {
+            ...projectConfig.layout,
+            ...testConfig.layout
+        },
+        ai: {
+            ...projectConfig.ai,
+            ...testConfig.ai
+        },
+        selectors: testConfig.selectors
+    };
+}
+/**
+ * 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 = {
+        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
+        },
+        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/index.d.ts

@@ -0,0 +1,7 @@
+import { snapshot } from './snapshot';
+export declare const testivai: {
+    witness: typeof snapshot;
+};
+export * from './types';
+export * from './reporter';
+export * from './ci';

package/dist/index.js

@@ -0,0 +1,24 @@
+"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.testivai = void 0;
+const snapshot_1 = require("./snapshot");
+exports.testivai = {
+    witness: snapshot_1.snapshot,
+};
+__exportStar(require("./types"), exports);
+__exportStar(require("./reporter"), exports);
+__exportStar(require("./ci"), exports);

package/dist/reporter-types.d.ts

@@ -0,0 +1,2 @@
+import type { Reporter, FullConfig, Suite, FullResult } from '@playwright/test/reporter';
+export type { Reporter, FullConfig, Suite, FullResult };

package/dist/reporter-types.js

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

package/dist/reporter.d.ts

@@ -0,0 +1,16 @@
+import { Reporter, FullConfig, Suite, FullResult } from './reporter-types';
+interface TestivaiReporterOptions {
+    apiUrl?: string;
+    apiKey?: string;
+}
+export declare class TestivAIPlaywrightReporter implements Reporter {
+    private options;
+    private gitInfo;
+    private browserInfo;
+    private runId;
+    private tempDir;
+    constructor(options?: TestivaiReporterOptions);
+    onBegin(config: FullConfig, suite: Suite): Promise<void>;
+    onEnd(result: FullResult): Promise<void>;
+}
+export {};

package/dist/reporter.js

@@ -0,0 +1,155 @@
+"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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestivAIPlaywrightReporter = void 0;
+const fs = __importStar(require("fs-extra"));
+const path = __importStar(require("path"));
+const simple_git_1 = __importDefault(require("simple-git"));
+const axios_1 = __importDefault(require("axios"));
+const ci_1 = require("./ci");
+class TestivAIPlaywrightReporter {
+    constructor(options = {}) {
+        this.gitInfo = null;
+        this.browserInfo = null;
+        this.runId = null;
+        this.tempDir = path.join(process.cwd(), '.testivai', 'temp');
+        this.options = {
+            apiUrl: options.apiUrl || process.env.TESTIVAI_API_URL,
+            apiKey: options.apiKey || process.env.TESTIVAI_API_KEY,
+        };
+    }
+    async onBegin(config, suite) {
+        if (!this.options.apiUrl || !this.options.apiKey) {
+            console.error('Testivai Reporter: API URL or API Key is not configured. Disabling reporter.');
+            this.options.apiUrl = undefined; // Disable reporter
+            return;
+        }
+        // 1. Clean temp directory
+        await fs.emptyDir(this.tempDir);
+        // 2. Capture Git metadata
+        try {
+            const git = (0, simple_git_1.default)();
+            const [branch, commit] = await Promise.all([
+                git.revparse(['--abbrev-ref', 'HEAD']),
+                git.revparse(['HEAD']),
+            ]);
+            this.gitInfo = { branch, commit };
+        }
+        catch (error) {
+            console.error('Testivai Reporter: Could not get Git information.', error);
+            this.gitInfo = { branch: 'unknown', commit: 'unknown' };
+        }
+        // 3. Capture Browser info from the first project
+        const project = suite.suites[0]?.project();
+        if (project) {
+            this.browserInfo = {
+                name: project.use.browserName || 'unknown',
+                version: 'unknown', // Playwright does not easily expose browser version
+                viewportWidth: project.use.viewport?.width || 0,
+                viewportHeight: project.use.viewport?.height || 0,
+                userAgent: project.use.userAgent || 'unknown',
+                os: 'unknown',
+            };
+        }
+        // 4. Get CI Run ID
+        this.runId = (0, ci_1.getCiRunId)();
+        if (this.runId) {
+            console.log(`Testivai Reporter: Detected CI environment. Run ID: ${this.runId}`);
+        }
+    }
+    async onEnd(result) {
+        if (!this.options.apiUrl) {
+            return; // Reporter is disabled
+        }
+        console.log('Testivai Reporter: Test run finished. Preparing to upload evidence...');
+        try {
+            const snapshotFiles = await fs.readdir(this.tempDir);
+            const jsonFiles = snapshotFiles.filter(f => f.endsWith('.json'));
+            if (jsonFiles.length === 0) {
+                console.log('Testivai Reporter: No snapshots found to upload.');
+                return;
+            }
+            const snapshots = [];
+            const filesToUpload = [];
+            for (const jsonFile of jsonFiles) {
+                const metadataPath = path.join(this.tempDir, jsonFile);
+                const metadata = await fs.readJson(metadataPath);
+                const domPath = metadata.files.dom;
+                const screenshotPath = metadata.files.screenshot;
+                const snapshotPayload = {
+                    ...metadata,
+                    dom: { html: await fs.readFile(domPath, 'utf-8') },
+                    layout: metadata.layout,
+                    testivaiConfig: metadata.testivaiConfig
+                };
+                snapshots.push(snapshotPayload);
+                filesToUpload.push({ filePath: screenshotPath, contentType: 'image/png' });
+            }
+            const batchPayload = {
+                git: this.gitInfo,
+                browser: this.browserInfo,
+                snapshots,
+                timestamp: Date.now(),
+                runId: this.runId,
+            };
+            // Start batch and get upload URLs
+            const startBatchResponse = await axios_1.default.post(`${this.options.apiUrl}/api/v1/ingest/start-batch`, batchPayload, {
+                headers: { 'Authorization': `Bearer ${this.options.apiKey}` },
+            });
+            const { batchId, uploadInstructions } = startBatchResponse.data;
+            // Upload files
+            const uploadPromises = filesToUpload.map((file, index) => {
+                const instruction = uploadInstructions[index];
+                return fs.readFile(file.filePath).then(buffer => axios_1.default.put(instruction.url, buffer, { headers: { 'Content-Type': file.contentType } }));
+            });
+            await Promise.all(uploadPromises);
+            // Finalize batch
+            await axios_1.default.post(`${this.options.apiUrl}/api/v1/ingest/finish-batch/${batchId}`, {}, {
+                headers: { 'Authorization': `Bearer ${this.options.apiKey}` },
+            });
+            console.log(`Testivai Reporter: Successfully uploaded ${snapshots.length} snapshots with Batch ID: ${batchId}`);
+            // Clean up temp files
+            await fs.emptyDir(this.tempDir);
+            console.log('Testivai Reporter: Cleaned up temporary evidence files.');
+        }
+        catch (error) {
+            console.error('Testivai Reporter: An error occurred during the onEnd hook:', error);
+        }
+    }
+}
+exports.TestivAIPlaywrightReporter = TestivAIPlaywrightReporter;

package/dist/snapshot.d.ts

@@ -0,0 +1,12 @@
+import { Page, TestInfo } from '@playwright/test';
+import { TestivAIConfig } from './types';
+/**
+ * Captures a snapshot of the page, including a screenshot, DOM, and layout data.
+ * The evidence is stored in a temporary directory for the reporter to process later.
+ *
+ * @param page The Playwright Page object.
+ * @param testInfo The Playwright TestInfo object, passed from the test.
+ * @param name An optional unique name for the snapshot. If not provided, a name is generated from the URL.
+ * @param config Optional TestivAI configuration for this snapshot (overrides project defaults).
+ */
+export declare function snapshot(page: Page, testInfo: TestInfo, name?: string, config?: TestivAIConfig): Promise<void>;

package/dist/snapshot.js

@@ -0,0 +1,122 @@
+"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.snapshot = snapshot;
+const fs = __importStar(require("fs-extra"));
+const path = __importStar(require("path"));
+const url_1 = require("url");
+const loader_1 = require("./config/loader");
+/**
+ * Generates a safe filename from a URL.
+ * @param pageUrl The URL of the page.
+ * @returns A sanitized string suitable for a filename.
+ */
+function getSnapshotNameFromUrl(pageUrl) {
+    // Handle data URIs, which are common in test environments
+    if (pageUrl.startsWith('data:')) {
+        return 'snapshot';
+    }
+    try {
+        const url = new url_1.URL(pageUrl);
+        const pathName = url.pathname.substring(1).replace(/\//g, '_'); // remove leading slash and replace others
+        return pathName || 'home';
+    }
+    catch (error) {
+        // Fallback for invalid URLs
+        return 'snapshot';
+    }
+}
+/**
+ * Captures a snapshot of the page, including a screenshot, DOM, and layout data.
+ * The evidence is stored in a temporary directory for the reporter to process later.
+ *
+ * @param page The Playwright Page object.
+ * @param testInfo The Playwright TestInfo object, passed from the test.
+ * @param name An optional unique name for the snapshot. If not provided, a name is generated from the URL.
+ * @param config Optional TestivAI configuration for this snapshot (overrides project defaults).
+ */
+async function snapshot(page, testInfo, name, config) {
+    // Load project configuration and merge with test-specific overrides
+    const projectConfig = await (0, loader_1.loadConfig)();
+    const effectiveConfig = (0, loader_1.mergeTestConfig)(projectConfig, config);
+    const outputDir = path.join(process.cwd(), '.testivai', 'temp');
+    await fs.ensureDir(outputDir);
+    const snapshotName = name || getSnapshotNameFromUrl(page.url());
+    const timestamp = Date.now();
+    const safeName = snapshotName.replace(/[^a-z0-9]/gi, '_').toLowerCase();
+    const baseFilename = `${timestamp}_${safeName}`;
+    // 1. Capture full-page screenshot
+    const screenshotPath = path.join(outputDir, `${baseFilename}.png`);
+    await page.screenshot({ path: screenshotPath, fullPage: true });
+    // 2. Dump full-page DOM
+    const domPath = path.join(outputDir, `${baseFilename}.html`);
+    const htmlContent = await page.content();
+    await fs.writeFile(domPath, htmlContent);
+    // 3. Extract bounding boxes for requested selectors
+    const selectors = effectiveConfig.selectors ?? ['body'];
+    const layout = {};
+    for (const selector of selectors) {
+        const element = page.locator(selector).first();
+        const boundingBox = await element.boundingBox();
+        if (boundingBox) {
+            layout[selector] = {
+                ...boundingBox,
+                top: boundingBox.y,
+                left: boundingBox.x,
+                right: boundingBox.x + boundingBox.width,
+                bottom: boundingBox.y + boundingBox.height,
+            };
+        }
+    }
+    // 4. Save metadata with configuration
+    const metadataPath = path.join(outputDir, `${baseFilename}.json`);
+    const metadata = {
+        snapshotName,
+        testName: testInfo.title,
+        timestamp,
+        url: page.url(),
+        viewport: page.viewportSize() || undefined,
+    };
+    await fs.writeJson(metadataPath, {
+        ...metadata,
+        files: {
+            screenshot: screenshotPath,
+            dom: domPath,
+        },
+        layout,
+        // Store the effective configuration for the reporter
+        testivaiConfig: effectiveConfig
+    });
+}