@testivai/witness-playwright 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 # @testivai/witness-playwright
 
-**Status**: ✅ Production Ready | **Last Updated**: January 9, 2026
+**Status**: ✅ Production Ready | **Last Updated**: January 10, 2026
 
 **Project:** @testivai/witness-playwright (MVP - 1 Month Plan)
 
@@ -25,9 +25,10 @@ To use the reporter, you need to configure it in your `playwright.config.ts` fil
 ```bash
 # Create .env file
 echo "TESTIVAI_API_KEY=tstvai-your-key-here" > .env
-echo "TESTIVAI_API_URL=https://core-api-147980626268.us-central1.run.app" >> .env
 ```
 
+**Note:** The SDK automatically uses the production API URL. You only need to set `TESTIVAI_API_KEY`.
+
 ```typescript
 // playwright.config.ts
 import { defineConfig } from '@playwright/test';
@@ -72,6 +73,74 @@ test('my example test', async ({ page }, testInfo) => {
 npm install @testivai/witness-playwright
 ```
 
+## Performance Metrics
+
+**NEW**: Automatically capture page performance metrics and Core Web Vitals!
+
+### Basic Performance Capture (Enabled by Default)
+
+Every snapshot automatically captures:
+- **Core Web Vitals**: LCP, FCP, CLS
+- **Page Load Metrics**: DOM Content Loaded, Load Complete
+- **Navigation Timing**: Navigation start and timing data
+
+No configuration needed - it just works!
+
+### Optional Lighthouse Integration
+
+For comprehensive performance audits, enable Lighthouse:
+
+```typescript
+// testivai.config.ts
+export default {
+  performance: {
+    captureTimings: true,      // Basic timing (default: ON)
+    enableLighthouse: false,   // Lighthouse audit (default: OFF)
+    lighthouseThresholds: {
+      performance: 80,
+      accessibility: 90,
+      bestPractices: 80,
+      seo: 80
+    }
+  }
+};
+```
+
+### Per-Test Configuration
+
+Enable Lighthouse for specific tests:
+
+```typescript
+test('performance critical page', async ({ page }, testInfo) => {
+  await page.goto('https://example.com');
+  
+  await testivai.witness(page, testInfo, 'homepage', {
+    performance: {
+      enableLighthouse: true,
+      lighthouseThresholds: {
+        performance: 90
+      }
+    }
+  });
+});
+```
+
+### What Gets Captured
+
+**Basic Timing (Always Captured)**:
+- First Contentful Paint (FCP)
+- Largest Contentful Paint (LCP)
+- Cumulative Layout Shift (CLS)
+- DOM Content Loaded
+- Load Complete
+
+**Lighthouse (When Enabled)**:
+- Performance Score (0-100)
+- Accessibility Score (0-100)
+- Best Practices Score (0-100)
+- SEO Score (0-100)
+- Detailed Core Web Vitals
+
 ## 📊 Progress
 
-See [PROGRESS.md](./PROGRESS.md) for detailed development progress.
+See [progress.md](./progress.md) for detailed development progress.

package/dist/cli/init.js

@@ -126,9 +126,8 @@ async function createConfigFile() {
         console.log('📁 Config file:', configPath);
         console.log('');
         console.log('📖 Next steps:');
-        console.log('   1. Set up environment variables:');
+        console.log('   1. Set up your API key:');
         console.log('      TESTIVAI_API_KEY=tstvai-your-key-here');
-        console.log('      TESTIVAI_API_URL=https://core-api-147980626268.us-central1.run.app');
         console.log('');
         console.log('   2. Update your playwright.config.ts to use TestivAI reporter:');
         console.log('      reporter: [[\'@testivai/witness-playwright/reporter\']]');
@@ -137,6 +136,7 @@ async function createConfigFile() {
         console.log('   4. Run your tests: npx playwright test');
         console.log('');
         console.log('💡 Get your API key from: https://dashboard-147980626268.us-central1.run.app');
+        console.log('💡 The SDK automatically connects to the production API - no URL configuration needed!');
     }
     catch (error) {
         console.error('❌ Failed to create configuration file:', error);

package/dist/reporter.js

@@ -49,13 +49,14 @@ class TestivAIPlaywrightReporter {
         this.runId = null;
         this.tempDir = path.join(process.cwd(), '.testivai', 'temp');
         this.options = {
-            apiUrl: options.apiUrl || process.env.TESTIVAI_API_URL,
+            apiUrl: options.apiUrl || process.env.TESTIVAI_API_URL || 'https://core-api-147980626268.us-central1.run.app',
             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.');
+        if (!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
             return;
         }
@@ -105,7 +106,6 @@ class TestivAIPlaywrightReporter {
                 return;
             }
             const snapshots = [];
-            const filesToUpload = [];
             for (const jsonFile of jsonFiles) {
                 const metadataPath = path.join(this.tempDir, jsonFile);
                 const metadata = await fs.readJson(metadataPath);
@@ -119,6 +119,9 @@ class TestivAIPlaywrightReporter {
                 }
                 const firstSelector = layoutKeys[0];
                 const layoutData = metadata.layout[firstSelector];
+                // Read screenshot and encode to base64
+                const screenshotBuffer = await fs.readFile(screenshotPath);
+                const screenshotBase64 = screenshotBuffer.toString('base64');
                 const snapshotPayload = {
                     ...metadata,
                     dom: { html: await fs.readFile(domPath, 'utf-8') },
@@ -128,10 +131,10 @@ class TestivAIPlaywrightReporter {
                         width: layoutData.width,
                         height: layoutData.height
                     },
-                    testivaiConfig: metadata.testivaiConfig
+                    testivaiConfig: metadata.testivaiConfig,
+                    screenshotData: screenshotBase64 // Include base64-encoded screenshot
                 };
                 snapshots.push(snapshotPayload);
-                filesToUpload.push({ filePath: screenshotPath, contentType: 'image/png' });
             }
             const batchPayload = {
                 git: this.gitInfo,
@@ -140,20 +143,13 @@ class TestivAIPlaywrightReporter {
                 timestamp: Date.now(),
                 runId: this.runId,
             };
-            // Start batch and get upload URLs
+            // Start batch - screenshots are now included in the payload
             const startBatchResponse = await axios_1.default.post(`${this.options.apiUrl}/api/v1/ingest/start-batch`, batchPayload, {
                 headers: { 'X-API-KEY': this.options.apiKey },
             });
             console.log('Testivai Reporter: API Response:', JSON.stringify(startBatchResponse.data, null, 2));
             // Handle both snake_case and camelCase response formats
             const batchId = startBatchResponse.data.batch_id || startBatchResponse.data.batchId;
-            const uploadInstructions = startBatchResponse.data.upload_instructions || startBatchResponse.data.uploadInstructions;
-            // 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: { 'X-API-KEY': this.options.apiKey },

package/dist/snapshot.js

@@ -100,7 +100,90 @@ async function snapshot(page, testInfo, name, config) {
             };
         }
     }
-    // 4. Save metadata with configuration
+    // 4. Capture performance metrics (if enabled)
+    let performanceTimings;
+    let lighthouseResults;
+    const captureTimings = effectiveConfig.performance?.captureTimings ?? true; // Default: enabled
+    const enableLighthouse = effectiveConfig.performance?.enableLighthouse ?? false; // Default: disabled
+    // Capture basic timing metrics
+    if (captureTimings) {
+        try {
+            performanceTimings = await page.evaluate(() => {
+                // @ts-ignore - window is available in browser context
+                const perfData = window.performance;
+                const navigation = perfData.timing;
+                const paintEntries = perfData.getEntriesByType('paint');
+                const lcpEntries = perfData.getEntriesByType('largest-contentful-paint');
+                // Get First Contentful Paint
+                const fcpEntry = paintEntries.find((entry) => entry.name === 'first-contentful-paint');
+                // Get Largest Contentful Paint
+                const lcpEntry = lcpEntries.length > 0 ? lcpEntries[lcpEntries.length - 1] : null;
+                // Calculate Cumulative Layout Shift
+                let cls = 0;
+                const layoutShiftEntries = perfData.getEntriesByType('layout-shift');
+                layoutShiftEntries.forEach((entry) => {
+                    if (!entry.hadRecentInput) {
+                        cls += entry.value;
+                    }
+                });
+                return {
+                    navigationStart: navigation.navigationStart,
+                    domContentLoaded: navigation.domContentLoadedEventEnd - navigation.navigationStart,
+                    loadComplete: navigation.loadEventEnd - navigation.navigationStart,
+                    firstContentfulPaint: fcpEntry ? fcpEntry.startTime : undefined,
+                    largestContentfulPaint: lcpEntry ? lcpEntry.startTime : undefined,
+                    cumulativeLayoutShift: cls,
+                };
+            });
+        }
+        catch (err) {
+            console.warn('Failed to capture performance metrics:', err);
+        }
+    }
+    // Capture Lighthouse audit (if enabled)
+    if (enableLighthouse) {
+        try {
+            const { playAudit } = await Promise.resolve().then(() => __importStar(require('playwright-lighthouse')));
+            const thresholds = effectiveConfig.performance?.lighthouseThresholds || {};
+            const auditResult = await playAudit({
+                page,
+                port: 9222, // Required by playwright-lighthouse
+                thresholds: {
+                    performance: thresholds.performance || 0,
+                    accessibility: thresholds.accessibility || 0,
+                    'best-practices': thresholds.bestPractices || 0,
+                    seo: thresholds.seo || 0,
+                },
+                reports: {
+                    formats: {
+                        json: false, // Don't save report files
+                    },
+                },
+            });
+            // Extract key metrics from Lighthouse result
+            if (auditResult) {
+                const lhr = auditResult.lhr;
+                if (lhr) {
+                    lighthouseResults = {
+                        performance: lhr.categories?.performance?.score ? Math.round(lhr.categories.performance.score * 100) : undefined,
+                        accessibility: lhr.categories?.accessibility?.score ? Math.round(lhr.categories.accessibility.score * 100) : undefined,
+                        bestPractices: lhr.categories?.['best-practices']?.score ? Math.round(lhr.categories['best-practices'].score * 100) : undefined,
+                        seo: lhr.categories?.seo?.score ? Math.round(lhr.categories.seo.score * 100) : undefined,
+                        coreWebVitals: {
+                            lcp: lhr.audits?.['largest-contentful-paint']?.numericValue,
+                            fid: lhr.audits?.['max-potential-fid']?.numericValue,
+                            cls: lhr.audits?.['cumulative-layout-shift']?.numericValue,
+                        },
+                    };
+                }
+            }
+        }
+        catch (err) {
+            console.warn('Failed to run Lighthouse audit:', err);
+            console.warn('Make sure playwright-lighthouse is installed: npm install playwright-lighthouse');
+        }
+    }
+    // 5. Save metadata with configuration and performance data
     const metadataPath = path.join(outputDir, `${baseFilename}.json`);
     const metadata = {
         snapshotName,
@@ -117,6 +200,10 @@ async function snapshot(page, testInfo, name, config) {
         },
         layout,
         // Store the effective configuration for the reporter
-        testivaiConfig: effectiveConfig
+        testivaiConfig: effectiveConfig,
+        // Store performance metrics if captured
+        performanceTimings,
+        // Store Lighthouse results if captured
+        lighthouseResults
     });
 }

package/dist/types.d.ts

@@ -32,6 +32,62 @@ export interface AIConfig {
     /** Include AI reasoning in results (optional) */
     enableReasoning?: boolean;
 }
+/**
+ * Performance metrics configuration
+ */
+export interface PerformanceConfig {
+    /** Enable basic timing capture (default: true) */
+    captureTimings?: boolean;
+    /** Enable Lighthouse performance audit (default: false) */
+    enableLighthouse?: boolean;
+    /** Lighthouse performance thresholds (optional) */
+    lighthouseThresholds?: {
+        performance?: number;
+        accessibility?: number;
+        bestPractices?: number;
+        seo?: number;
+    };
+}
+/**
+ * Performance timing metrics
+ */
+export interface PerformanceTimings {
+    /** Navigation start time */
+    navigationStart?: number;
+    /** DOM content loaded time */
+    domContentLoaded?: number;
+    /** Page load complete time */
+    loadComplete?: number;
+    /** First contentful paint */
+    firstContentfulPaint?: number;
+    /** Largest contentful paint */
+    largestContentfulPaint?: number;
+    /** Time to interactive */
+    timeToInteractive?: number;
+    /** Total blocking time */
+    totalBlockingTime?: number;
+    /** Cumulative layout shift */
+    cumulativeLayoutShift?: number;
+}
+/**
+ * Lighthouse performance results
+ */
+export interface LighthouseResults {
+    /** Performance score (0-100) */
+    performance?: number;
+    /** Accessibility score (0-100) */
+    accessibility?: number;
+    /** Best practices score (0-100) */
+    bestPractices?: number;
+    /** SEO score (0-100) */
+    seo?: number;
+    /** Core Web Vitals */
+    coreWebVitals?: {
+        lcp?: number;
+        fid?: number;
+        cls?: number;
+    };
+}
 /**
  * Environment-specific configuration overrides
  */
@@ -60,6 +116,8 @@ export interface TestivAIProjectConfig {
     layout: LayoutConfig;
     /** AI analysis settings */
     ai: AIConfig;
+    /** Performance metrics settings (optional) */
+    performance?: PerformanceConfig;
     /** Environment-specific overrides (optional) */
     environments?: EnvironmentConfig;
 }
@@ -71,6 +129,8 @@ export interface TestivAIConfig {
     layout?: Partial<LayoutConfig>;
     /** AI settings (optional - overrides project defaults) */
     ai?: Partial<AIConfig>;
+    /** Performance settings (optional - overrides project defaults) */
+    performance?: Partial<PerformanceConfig>;
     /** Element selectors to capture (existing option) */
     selectors?: string[];
 }
@@ -127,6 +187,12 @@ export interface SnapshotPayload {
     };
     /** TestivAI configuration for this snapshot */
     testivaiConfig?: TestivAIConfig;
+    /** Base64-encoded screenshot data (PNG) */
+    screenshotData?: string;
+    /** Performance timing metrics (optional) */
+    performanceTimings?: PerformanceTimings;
+    /** Lighthouse results (optional) */
+    lighthouseResults?: LighthouseResults;
 }
 /**
  * Git information for batch context

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testivai/witness-playwright",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Playwright sensor for Testivai Visual Regression Test system",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -32,6 +32,7 @@
     "axios": "^1.6.0",
     "cross-fetch": "^4.0.0",
     "fs-extra": "^11.2.0",
+    "playwright-lighthouse": "^4.0.0",
     "simple-git": "^3.21.0"
   },
   "devDependencies": {

package/progress.md

@@ -661,11 +661,96 @@ The Playwright SDK provides two main components that are production-ready:
 
 ---
 
-**Last Updated**: January 9, 2026
+## Performance Metrics Integration (January 10, 2026)
+
+### Performance Monitoring ✅ COMPLETE
+
+**Goal**: Automatically capture page performance metrics and Core Web Vitals with optional Lighthouse integration.
+
+#### Changes Implemented
+
+1. **Basic Performance Capture** ✅
+   - Automatically captures performance timing metrics on every snapshot
+   - Enabled by default (`captureTimings: true`)
+   - Zero configuration needed for basic metrics
+   - Metrics captured:
+     - Navigation Start
+     - DOM Content Loaded
+     - Load Complete
+     - First Contentful Paint (FCP)
+     - Largest Contentful Paint (LCP)
+     - Cumulative Layout Shift (CLS)
+
+2. **Lighthouse Integration** ✅
+   - Added `playwright-lighthouse@4.0.0` dependency
+   - Optional full Lighthouse audit (OFF by default)
+   - Captures all 4 Lighthouse categories:
+     - Performance Score (0-100)
+     - Accessibility Score (0-100)
+     - Best Practices Score (0-100)
+     - SEO Score (0-100)
+   - Extracts Core Web Vitals from Lighthouse
+
+3. **Configuration** ✅
+   ```typescript
+   // In testivai.config.ts
+   export default {
+     performance: {
+       captureTimings: true,      // Basic timing (default: ON)
+       enableLighthouse: false,   // Lighthouse audit (default: OFF)
+       lighthouseThresholds: {
+         performance: 80,
+         accessibility: 90,
+         bestPractices: 80,
+         seo: 80
+       }
+     }
+   }
+   
+   // Per-test override
+   await testivai.witness(page, testInfo, 'test-name', {
+     performance: {
+       enableLighthouse: true
+     }
+   });
+   ```
+
+4. **Data Storage** ✅
+   - Performance data stored in `testivai_config.performanceTimings`
+   - Lighthouse results stored in `testivai_config.lighthouseResults`
+   - Flows through existing ingestion pipeline
+   - No database schema changes needed
+
+5. **Dashboard Display** ✅
+   - Core Web Vitals displayed with color coding:
+     - Green: Good (LCP < 2.5s, FCP < 1.8s, CLS < 0.1)
+     - Yellow: Needs Improvement
+     - Red: Poor
+   - Page Load metrics table
+   - Beautiful card-based UI
+
+#### Files Modified
+- `src/types.ts` - Added PerformanceConfig, PerformanceTimings, LighthouseResults
+- `src/snapshot.ts` - Implemented performance capture and Lighthouse integration
+- `package.json` - Added playwright-lighthouse dependency
+- `apps/dashboard/src/services/api.ts` - Added testivai_config to TestRun interface
+- `apps/dashboard/src/pages/TestRunDetailPage.tsx` - Performance metrics display
+
+#### Benefits
+- **Automatic Tracking**: Every test run captures performance metrics
+- **Core Web Vitals**: Track LCP, FCP, CLS automatically
+- **Optional Lighthouse**: Full audit when needed (OFF by default)
+- **Performance Regression Detection**: Compare metrics across test runs
+- **Zero Configuration**: Works out of the box with sensible defaults
+
+---
+
+**Last Updated**: January 10, 2026
 **Status**: 🎉 PUBLISHED TO NPM ✅ - Publicly available
-**NPM Package**: @testivai/witness-playwright@0.1.0
-**Core Features**: Evidence capture and batch upload fully functional
+**NPM Package**: @testivai/witness-playwright@0.1.2
+**Core Features**: Evidence capture, batch upload, and performance monitoring fully functional
 **Configuration**: ✅ COMPLETE - End-to-end flow working
+**Performance Metrics**: ✅ COMPLETE - Basic timing + optional Lighthouse
 **API Key Format**: tstvai-{secure-random-string}
 **Known Issues**: Minor UX improvements (retry logic, progress reporting)
 **Blocker**: None - All critical features implemented

package/src/cli/init.ts

@@ -96,9 +96,8 @@ async function createConfigFile(): Promise<void> {
     console.log('📁 Config file:', configPath);
     console.log('');
     console.log('📖 Next steps:');
-    console.log('   1. Set up environment variables:');
+    console.log('   1. Set up your API key:');
     console.log('      TESTIVAI_API_KEY=tstvai-your-key-here');
-    console.log('      TESTIVAI_API_URL=https://core-api-147980626268.us-central1.run.app');
     console.log('');
     console.log('   2. Update your playwright.config.ts to use TestivAI reporter:');
     console.log('      reporter: [[\'@testivai/witness-playwright/reporter\']]');
@@ -107,6 +106,7 @@ async function createConfigFile(): Promise<void> {
     console.log('   4. Run your tests: npx playwright test');
     console.log('');
     console.log('💡 Get your API key from: https://dashboard-147980626268.us-central1.run.app');
+    console.log('💡 The SDK automatically connects to the production API - no URL configuration needed!');
     
   } catch (error) {
     console.error('❌ Failed to create configuration file:', error);

package/src/reporter.ts

@@ -20,14 +20,15 @@ export class TestivAIPlaywrightReporter implements Reporter {
 
   constructor(options: TestivaiReporterOptions = {}) {
     this.options = {
-      apiUrl: options.apiUrl || process.env.TESTIVAI_API_URL,
+      apiUrl: options.apiUrl || process.env.TESTIVAI_API_URL || 'https://core-api-147980626268.us-central1.run.app',
       apiKey: options.apiKey || process.env.TESTIVAI_API_KEY,
     };
   }
 
   async onBegin(config: FullConfig, suite: Suite): Promise<void> {
-    if (!this.options.apiUrl || !this.options.apiKey) {
-      console.error('Testivai Reporter: API URL or API Key is not configured. Disabling reporter.');
+    if (!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
       return;
     }
@@ -85,7 +86,6 @@ export class TestivAIPlaywrightReporter implements Reporter {
       }
 
       const snapshots: SnapshotPayload[] = [];
-      const filesToUpload: { filePath: string, contentType: string }[] = [];
 
       for (const jsonFile of jsonFiles) {
         const metadataPath = path.join(this.tempDir, jsonFile);
@@ -103,6 +103,10 @@ export class TestivAIPlaywrightReporter implements Reporter {
         const firstSelector = layoutKeys[0];
         const layoutData = metadata.layout[firstSelector];
 
+        // Read screenshot and encode to base64
+        const screenshotBuffer = await fs.readFile(screenshotPath);
+        const screenshotBase64 = screenshotBuffer.toString('base64');
+
         const snapshotPayload: SnapshotPayload = {
           ...metadata,
           dom: { html: await fs.readFile(domPath, 'utf-8') },
@@ -112,11 +116,10 @@ export class TestivAIPlaywrightReporter implements Reporter {
             width: layoutData.width,
             height: layoutData.height
           },
-          testivaiConfig: metadata.testivaiConfig
+          testivaiConfig: metadata.testivaiConfig,
+          screenshotData: screenshotBase64  // Include base64-encoded screenshot
         };
         snapshots.push(snapshotPayload);
-
-        filesToUpload.push({ filePath: screenshotPath, contentType: 'image/png' });
       }
 
       const batchPayload: Omit<BatchPayload, 'batchId'> = {
@@ -127,7 +130,7 @@ export class TestivAIPlaywrightReporter implements Reporter {
         runId: this.runId,
       };
 
-      // Start batch and get upload URLs
+      // Start batch - screenshots are now included in the payload
       const startBatchResponse = await axios.post(`${this.options.apiUrl}/api/v1/ingest/start-batch`, batchPayload, {
         headers: { 'X-API-KEY': this.options.apiKey },
       });
@@ -136,17 +139,6 @@ export class TestivAIPlaywrightReporter implements Reporter {
       
       // Handle both snake_case and camelCase response formats
       const batchId = startBatchResponse.data.batch_id || startBatchResponse.data.batchId;
-      const uploadInstructions = startBatchResponse.data.upload_instructions || startBatchResponse.data.uploadInstructions;
-
-      // Upload files
-      const uploadPromises = filesToUpload.map((file, index) => {
-        const instruction = uploadInstructions[index];
-        return fs.readFile(file.filePath).then(buffer => 
-          axios.put(instruction.url, buffer, { headers: { 'Content-Type': file.contentType } })
-        );
-      });
-
-      await Promise.all(uploadPromises);
 
       // Finalize batch
       await axios.post(`${this.options.apiUrl}/api/v1/ingest/finish-batch/${batchId}`, {}, {

package/src/snapshot.ts

@@ -2,7 +2,7 @@ import { Page, TestInfo } from '@playwright/test';
 import * as fs from 'fs-extra';
 import * as path from 'path';
 import { URL } from 'url';
-import { SnapshotPayload, LayoutData, TestivAIConfig } from './types';
+import { SnapshotPayload, LayoutData, TestivAIConfig, PerformanceTimings, LighthouseResults } from './types';
 import { loadConfig, mergeTestConfig } from './config/loader';
 
 /**
@@ -80,7 +80,98 @@ export async function snapshot(
     }
   }
 
-  // 4. Save metadata with configuration
+  // 4. Capture performance metrics (if enabled)
+  let performanceTimings: PerformanceTimings | undefined;
+  let lighthouseResults: LighthouseResults | undefined;
+  
+  const captureTimings = effectiveConfig.performance?.captureTimings ?? true; // Default: enabled
+  const enableLighthouse = effectiveConfig.performance?.enableLighthouse ?? false; // Default: disabled
+  
+  // Capture basic timing metrics
+  if (captureTimings) {
+    try {
+      performanceTimings = await page.evaluate(() => {
+        // @ts-ignore - window is available in browser context
+        const perfData = window.performance;
+        const navigation = perfData.timing;
+        const paintEntries = perfData.getEntriesByType('paint');
+        const lcpEntries = perfData.getEntriesByType('largest-contentful-paint');
+        
+        // Get First Contentful Paint
+        const fcpEntry = paintEntries.find((entry: any) => entry.name === 'first-contentful-paint');
+        
+        // Get Largest Contentful Paint
+        const lcpEntry = lcpEntries.length > 0 ? lcpEntries[lcpEntries.length - 1] : null;
+        
+        // Calculate Cumulative Layout Shift
+        let cls = 0;
+        const layoutShiftEntries = perfData.getEntriesByType('layout-shift') as any[];
+        layoutShiftEntries.forEach((entry: any) => {
+          if (!entry.hadRecentInput) {
+            cls += entry.value;
+          }
+        });
+        
+        return {
+          navigationStart: navigation.navigationStart,
+          domContentLoaded: navigation.domContentLoadedEventEnd - navigation.navigationStart,
+          loadComplete: navigation.loadEventEnd - navigation.navigationStart,
+          firstContentfulPaint: fcpEntry ? fcpEntry.startTime : undefined,
+          largestContentfulPaint: lcpEntry ? (lcpEntry as any).startTime : undefined,
+          cumulativeLayoutShift: cls,
+        };
+      });
+    } catch (err) {
+      console.warn('Failed to capture performance metrics:', err);
+    }
+  }
+  
+  // Capture Lighthouse audit (if enabled)
+  if (enableLighthouse) {
+    try {
+      const { playAudit } = await import('playwright-lighthouse');
+      const thresholds = effectiveConfig.performance?.lighthouseThresholds || {};
+      
+      const auditResult = await playAudit({
+        page,
+        port: 9222, // Required by playwright-lighthouse
+        thresholds: {
+          performance: thresholds.performance || 0,
+          accessibility: thresholds.accessibility || 0,
+          'best-practices': thresholds.bestPractices || 0,
+          seo: thresholds.seo || 0,
+        },
+        reports: {
+          formats: {
+            json: false, // Don't save report files
+          },
+        },
+      });
+      
+      // Extract key metrics from Lighthouse result
+      if (auditResult) {
+        const lhr = (auditResult as any).lhr;
+        if (lhr) {
+          lighthouseResults = {
+            performance: lhr.categories?.performance?.score ? Math.round(lhr.categories.performance.score * 100) : undefined,
+            accessibility: lhr.categories?.accessibility?.score ? Math.round(lhr.categories.accessibility.score * 100) : undefined,
+            bestPractices: lhr.categories?.['best-practices']?.score ? Math.round(lhr.categories['best-practices'].score * 100) : undefined,
+            seo: lhr.categories?.seo?.score ? Math.round(lhr.categories.seo.score * 100) : undefined,
+            coreWebVitals: {
+              lcp: lhr.audits?.['largest-contentful-paint']?.numericValue,
+              fid: lhr.audits?.['max-potential-fid']?.numericValue,
+              cls: lhr.audits?.['cumulative-layout-shift']?.numericValue,
+            },
+          };
+        }
+      }
+    } catch (err) {
+      console.warn('Failed to run Lighthouse audit:', err);
+      console.warn('Make sure playwright-lighthouse is installed: npm install playwright-lighthouse');
+    }
+  }
+
+  // 5. Save metadata with configuration and performance data
   const metadataPath = path.join(outputDir, `${baseFilename}.json`);
   const metadata: Partial<SnapshotPayload> = {
     snapshotName,
@@ -98,6 +189,10 @@ export async function snapshot(
     },
     layout,
     // Store the effective configuration for the reporter
-    testivaiConfig: effectiveConfig
+    testivaiConfig: effectiveConfig,
+    // Store performance metrics if captured
+    performanceTimings,
+    // Store Lighthouse results if captured
+    lighthouseResults
   });
 }

package/src/types.ts

@@ -35,6 +35,65 @@ export interface AIConfig {
   enableReasoning?: boolean;
 }
 
+/**
+ * Performance metrics configuration
+ */
+export interface PerformanceConfig {
+  /** Enable basic timing capture (default: true) */
+  captureTimings?: boolean;
+  /** Enable Lighthouse performance audit (default: false) */
+  enableLighthouse?: boolean;
+  /** Lighthouse performance thresholds (optional) */
+  lighthouseThresholds?: {
+    performance?: number;
+    accessibility?: number;
+    bestPractices?: number;
+    seo?: number;
+  };
+}
+
+/**
+ * Performance timing metrics
+ */
+export interface PerformanceTimings {
+  /** Navigation start time */
+  navigationStart?: number;
+  /** DOM content loaded time */
+  domContentLoaded?: number;
+  /** Page load complete time */
+  loadComplete?: number;
+  /** First contentful paint */
+  firstContentfulPaint?: number;
+  /** Largest contentful paint */
+  largestContentfulPaint?: number;
+  /** Time to interactive */
+  timeToInteractive?: number;
+  /** Total blocking time */
+  totalBlockingTime?: number;
+  /** Cumulative layout shift */
+  cumulativeLayoutShift?: number;
+}
+
+/**
+ * Lighthouse performance results
+ */
+export interface LighthouseResults {
+  /** Performance score (0-100) */
+  performance?: number;
+  /** Accessibility score (0-100) */
+  accessibility?: number;
+  /** Best practices score (0-100) */
+  bestPractices?: number;
+  /** SEO score (0-100) */
+  seo?: number;
+  /** Core Web Vitals */
+  coreWebVitals?: {
+    lcp?: number;
+    fid?: number;
+    cls?: number;
+  };
+}
+
 /**
  * Environment-specific configuration overrides
  */
@@ -64,6 +123,8 @@ export interface TestivAIProjectConfig {
   layout: LayoutConfig;
   /** AI analysis settings */
   ai: AIConfig;
+  /** Performance metrics settings (optional) */
+  performance?: PerformanceConfig;
   /** Environment-specific overrides (optional) */
   environments?: EnvironmentConfig;
 }
@@ -76,6 +137,8 @@ export interface TestivAIConfig {
   layout?: Partial<LayoutConfig>;
   /** AI settings (optional - overrides project defaults) */
   ai?: Partial<AIConfig>;
+  /** Performance settings (optional - overrides project defaults) */
+  performance?: Partial<PerformanceConfig>;
   /** Element selectors to capture (existing option) */
   selectors?: string[];
 }
@@ -135,6 +198,12 @@ export interface SnapshotPayload {
   };
   /** TestivAI configuration for this snapshot */
   testivaiConfig?: TestivAIConfig;
+  /** Base64-encoded screenshot data (PNG) */
+  screenshotData?: string;
+  /** Performance timing metrics (optional) */
+  performanceTimings?: PerformanceTimings;
+  /** Lighthouse results (optional) */
+  lighthouseResults?: LighthouseResults;
 }
 
 /**