@testivai/witness-playwright 1.1.0 → 1.1.2

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,133 @@
+# @testivai/witness-playwright
+
+Official Playwright adapter for TestivAI visual regression testing.
+
+## Installation
+
+```bash
+npm install -D @testivai/witness-playwright
+```
+
+## Quick Start (Local Mode — Free)
+
+1. **Initialize your project**
+   ```bash
+   npx testivai init
+   # Select "Local Mode" when prompted
+   ```
+
+2. **Add the reporter to your Playwright config**
+   ```typescript
+   // playwright.config.ts
+   import { defineConfig } from '@playwright/test';
+
+   export default defineConfig({
+     reporter: [
+       ['line'],
+       ['@testivai/witness-playwright/reporter', {
+         // No API key needed for local mode!
+       }]
+     ],
+   });
+   ```
+
+3. **Capture snapshots in your tests**
+   ```typescript
+   import { test, expect } from '@playwright/test';
+   import { snapshot } from '@testivai/witness-playwright';
+
+   test('homepage visual', async ({ page }, testInfo) => {
+     await page.goto('https://example.com');
+     await snapshot(page, testInfo, 'homepage');
+   });
+   ```
+
+4. **Run your tests**
+   ```bash
+   npx playwright test
+   ```
+
+5. **View the report**
+   Open `visual-report/index.html` in your browser.
+
+6. **Approve changes**
+   ```bash
+   npx testivai approve --all
+   ```
+
+## Configuration
+
+### Local Mode (Default)
+
+No configuration needed! Just run `npx testivai init` and select "Local Mode".
+
+### Cloud Mode
+
+For team dashboards and collaboration:
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  reporter: [
+    ['line'],
+    ['@testivai/witness-playwright/reporter', {
+      apiKey: process.env.TESTIVAI_API_KEY,
+    }]
+  ],
+});
+```
+
+## API Reference
+
+### `snapshot(page, testInfo, name?, config?)`
+
+Capture a visual snapshot of the current page.
+
+```typescript
+import { snapshot } from '@testivai/witness-playwright';
+
+// Basic usage
+await snapshot(page, testInfo, 'my-snapshot');
+
+// With custom config
+await snapshot(page, testInfo, 'checkout-page', {
+  threshold: 0.05,  // 5% difference tolerance
+  fullPage: true,   // Capture full page
+});
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: Visual Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - run: npx playwright install chromium
+      - run: npx playwright test
+      - uses: testivai/testivai-action@v1
+        if: always()
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          report-dir: visual-report
+```
+
+## License
+
+MIT
+
+## Support
+
+- Documentation: https://github.com/mcbuddy/testivai-oss/tree/main/packages/playwright
+- Issues: https://github.com/mcbuddy/testivai-oss/issues
+- Website: https://testiv.ai

package/dist/reporter.d.ts

@@ -14,6 +14,7 @@ export declare class TestivAIPlaywrightReporter implements Reporter {
     private ciInfo;
     private tempDir;
     private compressionHelper;
+    private localMode;
     constructor(options?: TestivaiReporterOptions);
     onBegin(config: FullConfig, suite: Suite): Promise<void>;
     onEnd(result: FullResult): Promise<void>;

package/dist/reporter.js

@@ -43,6 +43,22 @@ const simple_git_1 = __importDefault(require("simple-git"));
 const axios_1 = __importDefault(require("axios"));
 const ci_1 = require("./ci");
 const common_1 = require("@testivai/common");
+/**
+ * Check if local mode is configured by looking for .testivai/config.json with mode: 'local'
+ */
+function isLocalMode() {
+    try {
+        const configPath = path.join(process.cwd(), '.testivai', 'config.json');
+        if (!fs.existsSync(configPath)) {
+            return false;
+        }
+        const config = fs.readJsonSync(configPath);
+        return config.mode === 'local';
+    }
+    catch {
+        return false;
+    }
+}
 class TestivAIPlaywrightReporter {
     constructor(options = {}) {
         this.gitInfo = null;
@@ -50,6 +66,7 @@ class TestivAIPlaywrightReporter {
         this.runId = null;
         this.ciInfo = null;
         this.tempDir = path.join(process.cwd(), '.testivai', 'temp');
+        this.localMode = false;
         this.options = {
             apiUrl: options.apiUrl || process.env.TESTIVAI_API_URL || 'https://core-api.testiv.ai',
             apiKey: options.apiKey || process.env.TESTIVAI_API_KEY,
@@ -60,7 +77,16 @@ class TestivAIPlaywrightReporter {
         this.compressionHelper = new common_1.CompressionHelper(this.options.compression);
     }
     async onBegin(config, suite) {
-        if (!this.options.apiKey) {
+        // Check for local mode first
+        this.localMode = isLocalMode();
+        if (this.localMode) {
+            process.env.TESTIVAI_MODE = 'local';
+            if (this.options.debug) {
+                console.log('Testivai Reporter: [DEBUG] Local mode detected, skipping API key validation');
+            }
+        }
+        // API key is only required in cloud mode
+        if (!this.localMode && !this.options.apiKey) {
             console.error('Testivai Reporter: API Key is not configured. Disabling reporter.');
             console.error('Set TESTIVAI_API_KEY environment variable or pass apiKey in reporter options.');
             this.options.apiUrl = undefined; // Disable reporter
@@ -106,6 +132,37 @@ class TestivAIPlaywrightReporter {
     async onEnd(result) {
         // Wrap entire reporter logic in try-catch to prevent crashes
         try {
+            // ── Local mode: generate HTML report instead of uploading ─────────────────
+            if (this.localMode) {
+                if (this.options.debug) {
+                    console.log('Testivai Reporter: [DEBUG] Local mode - generating visual report...');
+                }
+                // Dynamic import of @testivai/witness/report for local mode
+                const { generateReport } = await Promise.resolve().then(() => __importStar(require('@testivai/witness/report')));
+                // Load local config for report settings
+                const localConfigPath = path.join(process.cwd(), '.testivai', 'config.json');
+                const localConfig = fs.existsSync(localConfigPath)
+                    ? fs.readJsonSync(localConfigPath)
+                    : { threshold: 0.1, reportDir: 'visual-report', autoOpen: false };
+                const reportData = generateReport({
+                    projectRoot: process.cwd(),
+                    reportDir: localConfig.reportDir || 'visual-report',
+                    threshold: localConfig.threshold,
+                    autoOpen: localConfig.autoOpen,
+                });
+                // Print summary
+                const { summary } = reportData;
+                console.log(`\n  ═══ TestivAI Visual Report ═══`);
+                console.log(`  Total: ${summary.total}  |  Passed: ${summary.passed}  |  Changed: ${summary.changed}  |  New: ${summary.newSnapshots}`);
+                if (summary.changed > 0 || summary.newSnapshots > 0) {
+                    console.log(`\n  To approve: npx testivai approve --all`);
+                }
+                if (this.options.debug) {
+                    console.log(`Testivai Reporter: [DEBUG] Report generated at ${path.join(process.cwd(), localConfig.reportDir || 'visual-report')}`);
+                }
+                return;
+            }
+            // ── Cloud mode: upload to TestivAI API ────────────────────────────────────
             if (!this.options.apiUrl) {
                 return; // Reporter is disabled
             }
@@ -185,7 +242,8 @@ class TestivAIPlaywrightReporter {
                         bottom: layoutData.y + layoutData.height
                     },
                     testivaiConfig: metadata.testivaiConfig,
-                    screenshotData: screenshotBase64
+                    screenshotData: screenshotBase64,
+                    performanceMetrics: metadata.performanceMetrics
                 };
                 snapshots.push(snapshotPayload);
             }

package/dist/snapshot.js

@@ -72,6 +72,8 @@ function getSnapshotNameFromUrl(pageUrl) {
  * @param config Optional TestivAI configuration for this snapshot (overrides project defaults).
  */
 async function snapshot(page, testInfo, name, config) {
+    // Check for local mode - only capture screenshots, skip heavy data
+    const isLocalMode = process.env.TESTIVAI_MODE === 'local';
     // Load project configuration and merge with test-specific overrides
     const projectConfig = await (0, loader_1.loadConfig)();
     const effectiveConfig = (0, loader_1.mergeTestConfig)(projectConfig, config);
@@ -80,7 +82,8 @@ async function snapshot(page, testInfo, name, config) {
         console.log('[TestivAI] Config:', {
             projectConfig,
             testConfig: config,
-            effectiveConfig
+            effectiveConfig,
+            isLocalMode
         });
     }
     const outputDir = path.join(process.cwd(), '.testivai', 'temp');
@@ -307,171 +310,179 @@ async function snapshot(page, testInfo, name, config) {
             await page.screenshot({ path: screenshotPath, fullPage: true });
         }
     }
-    // 2. Dump page structure (HTML)
+    // 2. Dump page structure (HTML) - skip in local mode
     // @renamed: domPath → structurePath (IP protection)
-    const structurePath = path.join(outputDir, `${baseFilename}.html`);
-    const htmlContent = await page.content();
-    await fs.writeFile(structurePath, htmlContent);
-    // 2.5. Capture computed styles using browser session
+    let structurePath = '';
+    if (!isLocalMode) {
+        structurePath = path.join(outputDir, `${baseFilename}.html`);
+        const htmlContent = await page.content();
+        await fs.writeFile(structurePath, htmlContent);
+    }
+    // 2.5. Capture computed styles using browser session - skip in local mode
     // @renamed: cssPath → stylesPath (IP protection)
-    const stylesPath = path.join(outputDir, `${baseFilename}.css.json`);
-    try {
-        const browserSession = await page.context().newCDPSession(page);
-        // Enable DOM and CSS domains
-        await browserSession.send('DOM.enable');
-        await browserSession.send('CSS.enable');
-        // Get all elements and their computed styles
-        const computedStyles = {};
-        // Visual properties we care about
-        const visualProperties = [
-            'color', 'background-color', 'background-image',
-            'font-size', 'font-weight', 'font-family',
-            'width', 'height', 'padding', 'margin',
-            'border', 'border-radius', 'box-shadow',
-            'display', 'position', 'top', 'left', 'right', 'bottom',
-            'transform', 'opacity', 'visibility', 'z-index'
-        ];
-        // Execute script to get all elements with unique identifiers
-        const elementsData = await browserSession.send('Runtime.evaluate', {
-            expression: `
-        (function() {
-          // Helper to get stable CSS selector path for an element
-          function getElementPath(element) {
-            if (element.id) {
-              return '#' + element.id;
-            }
-            
-            const path = [];
-            let current = element;
-            
-            while (current && current !== document.body) {
-              let selector = current.tagName.toLowerCase();
-              
-              // Add up to 3 CSS classes for better uniqueness
-              // e.g., button.button.primary-button instead of just button.button
-              if (current.className && typeof current.className === 'string') {
-                const classes = current.className.trim().split(/\\s+/).filter(Boolean);
-                const maxClasses = Math.min(classes.length, 3);
-                for (let c = 0; c < maxClasses; c++) {
-                  selector += '.' + classes[c];
-                }
+    let stylesPath = '';
+    if (!isLocalMode) {
+        stylesPath = path.join(outputDir, `${baseFilename}.css.json`);
+        try {
+            const browserSession = await page.context().newCDPSession(page);
+            // Enable DOM and CSS domains
+            await browserSession.send('DOM.enable');
+            await browserSession.send('CSS.enable');
+            // Get all elements and their computed styles
+            const computedStyles = {};
+            // Visual properties we care about
+            const visualProperties = [
+                'color', 'background-color', 'background-image',
+                'font-size', 'font-weight', 'font-family',
+                'width', 'height', 'padding', 'margin',
+                'border', 'border-radius', 'box-shadow',
+                'display', 'position', 'top', 'left', 'right', 'bottom',
+                'transform', 'opacity', 'visibility', 'z-index'
+            ];
+            // Execute script to get all elements with unique identifiers
+            const elementsData = await browserSession.send('Runtime.evaluate', {
+                expression: `
+          (function() {
+            // Helper to get stable CSS selector path for an element
+            function getElementPath(element) {
+              if (element.id) {
+                return '#' + element.id;
               }
-              
-              // Get nth-child position for uniqueness
-              if (current.parentNode) {
-                const siblings = Array.from(current.parentNode.children);
-                const sameTagSiblings = siblings.filter(s => s.tagName === current.tagName);
-                if (sameTagSiblings.length > 1) {
-                  const index = sameTagSiblings.indexOf(current) + 1;
-                  selector += \`:nth-of-type(\${index})\`;
+
+              const path = [];
+              let current = element;
+
+              while (current && current !== document.body) {
+                let selector = current.tagName.toLowerCase();
+
+                // Add up to 3 CSS classes for better uniqueness
+                // e.g., button.button.primary-button instead of just button.button
+                if (current.className && typeof current.className === 'string') {
+                  const classes = current.className.trim().split(/\\s+/).filter(Boolean);
+                  const maxClasses = Math.min(classes.length, 3);
+                  for (let c = 0; c < maxClasses; c++) {
+                    selector += '.' + classes[c];
+                  }
+                }
+
+                // Get nth-child position for uniqueness
+                if (current.parentNode) {
+                  const siblings = Array.from(current.parentNode.children);
+                  const sameTagSiblings = siblings.filter(s => s.tagName === current.tagName);
+                  if (sameTagSiblings.length > 1) {
+                    const index = sameTagSiblings.indexOf(current) + 1;
+                    selector += \`:nth-of-type(\${index})\`;
+                  }
                 }
+
+                path.unshift(selector);
+                current = current.parentElement;
               }
-              
-              path.unshift(selector);
-              current = current.parentElement;
+
+              return path.join(' > ');
             }
-            
-            return path.join(' > ');
-          }
-          
-          const elements = document.querySelectorAll('*');
-          const result = [];
-          elements.forEach((el, index) => {
-            const selectorPath = getElementPath(el);
-            const tagName = el.tagName.toLowerCase();
-            const className = el.className || '';
-            result.push({ 
-              selectorPath, 
-              tagName, 
-              className, 
-              index 
+
+            const elements = document.querySelectorAll('*');
+            const result = [];
+            elements.forEach((el, index) => {
+              const selectorPath = getElementPath(el);
+              const tagName = el.tagName.toLowerCase();
+              const className = el.className || '';
+              result.push({
+                selectorPath,
+                tagName,
+                className,
+                index
+              });
             });
-          });
-          return result;
-        })()
-      `,
-            returnByValue: true
-        });
-        if (elementsData.result.value) {
-            const elements = elementsData.result.value;
-            // Get computed styles for each element (sample first 100 to avoid performance issues)
-            const sampleSize = Math.min(elements.length, 100);
-            for (let i = 0; i < sampleSize; i++) {
-                const element = elements[i];
-                try {
-                    const styleResult = await browserSession.send('Runtime.evaluate', {
-                        expression: `
-              (function() {
-                const el = document.querySelectorAll('*')[${element.index}];
-                if (!el) return null;
-                const styles = window.getComputedStyle(el);
-                const result = {};
-                ${JSON.stringify(visualProperties)}.forEach(prop => {
-                  result[prop] = styles.getPropertyValue(prop);
-                });
-                return result;
-              })()
-            `,
-                        returnByValue: true
-                    });
-                    if (styleResult.result.value) {
-                        // Use stable selector path as element ID instead of unstable index
-                        // Deduplicate: if key already exists, append numeric suffix to prevent overwriting
-                        let uniqueKey = element.selectorPath;
-                        if (computedStyles[uniqueKey]) {
-                            let suffix = 2;
-                            while (computedStyles[`${element.selectorPath}[${suffix}]`]) {
-                                suffix++;
+            return result;
+          })()
+        `,
+                returnByValue: true
+            });
+            if (elementsData.result.value) {
+                const elements = elementsData.result.value;
+                // Get computed styles for each element (sample first 100 to avoid performance issues)
+                const sampleSize = Math.min(elements.length, 100);
+                for (let i = 0; i < sampleSize; i++) {
+                    const element = elements[i];
+                    try {
+                        const styleResult = await browserSession.send('Runtime.evaluate', {
+                            expression: `
+                (function() {
+                  const el = document.querySelectorAll('*')[${element.index}];
+                  if (!el) return null;
+                  const styles = window.getComputedStyle(el);
+                  const result = {};
+                  ${JSON.stringify(visualProperties)}.forEach(prop => {
+                    result[prop] = styles.getPropertyValue(prop);
+                  });
+                  return result;
+                })()
+              `,
+                            returnByValue: true
+                        });
+                        if (styleResult.result.value) {
+                            // Use stable selector path as element ID instead of unstable index
+                            // Deduplicate: if key already exists, append numeric suffix to prevent overwriting
+                            let uniqueKey = element.selectorPath;
+                            if (computedStyles[uniqueKey]) {
+                                let suffix = 2;
+                                while (computedStyles[`${element.selectorPath}[${suffix}]`]) {
+                                    suffix++;
+                                }
+                                uniqueKey = `${element.selectorPath}[${suffix}]`;
                             }
-                            uniqueKey = `${element.selectorPath}[${suffix}]`;
+                            computedStyles[uniqueKey] = styleResult.result.value;
                         }
-                        computedStyles[uniqueKey] = styleResult.result.value;
                     }
-                }
-                catch (err) {
-                    // Skip elements that fail
-                    continue;
+                    catch (err) {
+                        // Skip elements that fail
+                        continue;
+                    }
                 }
             }
+            // Disable domains and close session
+            await browserSession.send('CSS.disable');
+            await browserSession.send('DOM.disable');
+            await browserSession.detach();
+            // Save computed styles to file
+            await fs.writeJson(stylesPath, {
+                computed_styles: computedStyles,
+                timestamp: Date.now(),
+                sample_size: Object.keys(computedStyles).length
+            });
+            if (process.env.TESTIVAI_DEBUG === 'true') {
+                console.log(`[TestivAI] Captured ${Object.keys(computedStyles).length} element styles`);
+            }
         }
-        // Disable domains and close session
-        await browserSession.send('CSS.disable');
-        await browserSession.send('DOM.disable');
-        await browserSession.detach();
-        // Save computed styles to file
-        await fs.writeJson(stylesPath, {
-            computed_styles: computedStyles,
-            timestamp: Date.now(),
-            sample_size: Object.keys(computedStyles).length
-        });
-        if (process.env.TESTIVAI_DEBUG === 'true') {
-            console.log(`[TestivAI] Captured ${Object.keys(computedStyles).length} element styles`);
+        catch (error) {
+            console.warn('[TestivAI] Failed to capture CSS via browser session:', error);
+            // Continue without CSS data
         }
     }
-    catch (error) {
-        console.warn('[TestivAI] Failed to capture CSS via browser session:', error);
-        // Continue without CSS data
-    }
-    // 3. Extract bounding boxes for requested selectors
+    // 3. Extract bounding boxes for requested selectors - skip in local mode
     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,
-            };
+    if (!isLocalMode) {
+        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. Capture performance metrics using browser session (if enabled)
+    // 4. Capture performance metrics using browser session (if enabled) - skip in local mode
     let performanceMetrics = undefined;
     const metricsEnabled = effectiveConfig.performanceMetrics?.enabled ?? true; // Default: enabled
-    if (metricsEnabled) {
+    if (metricsEnabled && !isLocalMode) {
         try {
             // Get browser session from Playwright page
             const browserSession = await page.context().newCDPSession(page);
@@ -568,10 +579,10 @@ async function snapshot(page, testInfo, name, config) {
             console.warn('Failed to capture performance metrics:', err);
         }
     }
-    // 5. Structure analysis is now handled on the backend
+    // 5. Structure analysis is now handled on the backend - skip in local mode
     // The SDK just captures the HTML and sends it with the configuration
     // @renamed: domAnalysis → structureAnalysis (IP protection)
-    const structureAnalysis = undefined; // Will be populated by backend
+    const structureAnalysis = isLocalMode ? undefined : undefined; // Will be populated by backend
     // 6. Save metadata with configuration and performance data
     const metadataPath = path.join(outputDir, `${baseFilename}.json`);
     const metadata = {

package/dist/types.d.ts

@@ -291,6 +291,8 @@ export interface SnapshotPayload {
     screenshotData?: string;
     /** Performance timing metrics (optional) */
     performanceTimings?: PerformanceTimings;
+    /** Performance metrics from browser Performance.getMetrics (optional) */
+    performanceMetrics?: any;
     /** Lighthouse results (optional) */
     lighthouseResults?: LighthouseResults;
     /**