@testivai/witness-playwright 1.0.0

package/dist/structureAnalyzer.js

@@ -0,0 +1,288 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeStructure = analyzeStructure;
+exports.compareStructureAnalysis = compareStructureAnalysis;
+/**
+ * Default configuration for structure analysis
+ * @renamed Was DEFAULT_CONFIG in domAnalyzer.ts — renamed to conceal internal layer terminology (IP protection)
+ */
+const DEFAULT_CONFIG = {
+    enableFingerprint: true,
+    enableStructure: true,
+    enableSemantic: true,
+    ignoreAttributes: [
+        'data-testid',
+        'data-reactid',
+        'data-reactroot',
+        'ng-version',
+        'ng-version',
+        'ng-reflect-router-outlet',
+        'data-ng-version',
+        'style', // Inline styles change often
+        'class', // CSS classes can be dynamic
+    ],
+    ignoreElements: [
+        'script',
+        'style',
+        'noscript',
+        'meta',
+        'link',
+        'title',
+    ],
+    ignoreContentPatterns: [
+        /\d{4}-\d{2}-\d{2}/, // Dates
+        /\d{1,2}:\d{2}(:\d{2})?/, // Times
+        /\b\d{4}\b/, // Years
+        /\b\d+\b/, // Pure numbers
+        /uuid-/i, // UUIDs
+        /_\d+/, // Number suffixes
+        /\$\d+\.?\d*/, // Currency
+    ],
+};
+/**
+ * Analyzes page structure and generates fingerprint
+ * @renamed Was `analyzeDOM` — renamed to conceal internal layer terminology (IP protection)
+ */
+async function analyzeStructure(page, config = {}) {
+    const finalConfig = { ...DEFAULT_CONFIG, ...config };
+    return await page.evaluate((cfg) => {
+        // Helper functions
+        const normalizeSelector = (el) => {
+            let selector = el.nodeName.toLowerCase();
+            // Add ID if present and not a dynamic ID
+            if (el.id && !cfg.ignoreAttributes.includes('id')) {
+                // Skip if ID looks dynamic
+                if (!/^(ember|react|ng|vue|_)/.test(el.id)) {
+                    selector += `#${el.id}`;
+                }
+            }
+            // Add meaningful classes only
+            if (el.className && !cfg.ignoreAttributes.includes('class')) {
+                const classes = el.className.toString()
+                    .split(' ')
+                    .filter((c) => c &&
+                    !/^(ember|react|ng|vue|css|active|hover|focus)/.test(c) &&
+                    !c.includes('_') &&
+                    !/\d/.test(c))
+                    .slice(0, 3); // Limit to 3 most meaningful classes
+                if (classes.length > 0) {
+                    selector += `.${classes.join('.')}`;
+                }
+            }
+            return selector;
+        };
+        const getElementPath = (el, maxDepth = 10) => {
+            const path = [];
+            let current = el;
+            let depth = 0;
+            while (current && current.nodeType === Node.ELEMENT_NODE && depth < maxDepth) {
+                path.unshift(normalizeSelector(current));
+                current = current.parentElement;
+                depth++;
+            }
+            return path.join(' > ');
+        };
+        const shouldIgnoreElement = (el) => {
+            return cfg.ignoreElements.includes(el.nodeName.toLowerCase());
+        };
+        const shouldIgnoreAttribute = (attr) => {
+            return cfg.ignoreAttributes.includes(attr.toLowerCase());
+        };
+        const shouldIgnoreContent = (content) => {
+            return cfg.ignoreContentPatterns.some((pattern) => pattern.test(content));
+        };
+        const normalizeText = (text) => {
+            if (!text)
+                return '';
+            // Replace ignored patterns with placeholders
+            let normalized = text.trim();
+            cfg.ignoreContentPatterns.forEach((pattern) => {
+                normalized = normalized.replace(pattern, '[DYNAMIC]');
+            });
+            // Normalize whitespace
+            normalized = normalized.replace(/\s+/g, ' ');
+            return normalized;
+        };
+        // Get all meaningful elements
+        const allElements = Array.from(document.querySelectorAll('*'))
+            .filter(el => !shouldIgnoreElement(el));
+        const analysis = {};
+        // 1. Generate fingerprint
+        if (cfg.enableFingerprint) {
+            const paths = allElements.map((el) => {
+                const path = getElementPath(el);
+                const text = normalizeText(el.textContent || '');
+                const attrs = [];
+                // Add important attributes
+                for (const attr of el.attributes) {
+                    if (!shouldIgnoreAttribute(attr.name) && attr.value) {
+                        attrs.push(`${attr.name}="${attr.value}"`);
+                    }
+                }
+                return `${path}${text ? `|${text}` : ''}${attrs.length ? `|${attrs.join(',')}` : ''}`;
+            });
+            // Create hash from sorted paths
+            const sortedPaths = paths.sort().join('|||');
+            analysis.fingerprint = btoa(sortedPaths).substring(0, 32);
+        }
+        // 2. Structural analysis
+        if (cfg.enableStructure) {
+            const elementTypes = {};
+            let maxDepth = 0;
+            allElements.forEach((el) => {
+                const tag = el.nodeName.toLowerCase();
+                elementTypes[tag] = (elementTypes[tag] || 0) + 1;
+                // Calculate depth
+                let depth = 0;
+                let current = el;
+                while (current.parentElement) {
+                    depth++;
+                    current = current.parentElement;
+                }
+                maxDepth = Math.max(maxDepth, depth);
+            });
+            analysis.structure = {
+                totalElements: allElements.length,
+                elementTypes,
+                maxDepth,
+                interactiveElements: {
+                    buttons: document.querySelectorAll('button').length,
+                    inputs: document.querySelectorAll('input').length,
+                    links: document.querySelectorAll('a[href]').length,
+                    forms: document.querySelectorAll('form').length,
+                },
+            };
+        }
+        // 3. Semantic analysis
+        if (cfg.enableSemantic) {
+            const headings = {};
+            for (let i = 1; i <= 6; i++) {
+                headings[`h${i}`] = document.querySelectorAll(`h${i}`).length;
+            }
+            analysis.semantic = {
+                headings,
+                landmarks: {
+                    hasHeader: !!document.querySelector('header'),
+                    hasNav: !!document.querySelector('nav'),
+                    hasMain: !!document.querySelector('main'),
+                    hasFooter: !!document.querySelector('footer'),
+                    hasAside: !!document.querySelector('aside'),
+                },
+                lists: {
+                    ordered: document.querySelectorAll('ol').length,
+                    unordered: document.querySelectorAll('ul').length,
+                },
+                tables: document.querySelectorAll('table').length,
+                images: document.querySelectorAll('img').length,
+            };
+        }
+        // 4. Component analysis (framework-agnostic)
+        const components = {};
+        allElements.forEach((el) => {
+            // Try various component detection strategies
+            const componentName = el.getAttribute('data-testid')?.replace(/-/g, '') ||
+                el.getAttribute('data-component') ||
+                el.getAttribute('data-testid') ||
+                el.className?.toString().match(/(\w+Container|\w+Component|\w+Page|\w+Card|\w+Modal)/i)?.[1];
+            if (componentName && componentName.length > 2) {
+                if (!components[componentName]) {
+                    components[componentName] = [];
+                }
+                const attrs = {};
+                for (const attr of el.attributes) {
+                    if (!shouldIgnoreAttribute(attr.name) && attr.value) {
+                        attrs[attr.name] = attr.value;
+                    }
+                }
+                components[componentName].push({
+                    selector: getElementPath(el),
+                    text: normalizeText(el.textContent || '').substring(0, 100),
+                    attributes: attrs,
+                });
+            }
+        });
+        if (Object.keys(components).length > 0) {
+            analysis.components = components;
+        }
+        return analysis;
+    }, finalConfig);
+}
+/**
+ * Compare two structure analyses and identify changes
+ * @renamed Was `compareDOMAnalysis` — renamed to conceal internal layer terminology (IP protection)
+ */
+function compareStructureAnalysis(baseline, current) {
+    const changes = [];
+    // Compare fingerprints
+    if (baseline.fingerprint && current.fingerprint) {
+        if (baseline.fingerprint !== current.fingerprint) {
+            changes.push({
+                type: 'fingerprint',
+                severity: 'high',
+                description: 'Page structure has changed',
+                details: {
+                    baseline: baseline.fingerprint,
+                    current: current.fingerprint,
+                },
+            });
+        }
+    }
+    // Compare structure
+    if (baseline.structure && current.structure) {
+        if (baseline.structure.totalElements !== current.structure.totalElements) {
+            changes.push({
+                type: 'structure',
+                severity: 'medium',
+                description: `Element count changed from ${baseline.structure.totalElements} to ${current.structure.totalElements}`,
+            });
+        }
+        // Check for new/removed element types
+        const baselineTypes = Object.keys(baseline.structure.elementTypes);
+        const currentTypes = Object.keys(current.structure.elementTypes);
+        const removed = baselineTypes.filter(t => !currentTypes.includes(t));
+        const added = currentTypes.filter(t => !baselineTypes.includes(t));
+        if (removed.length > 0) {
+            changes.push({
+                type: 'structure',
+                severity: 'medium',
+                description: `Removed element types: ${removed.join(', ')}`,
+            });
+        }
+        if (added.length > 0) {
+            changes.push({
+                type: 'structure',
+                severity: 'medium',
+                description: `Added element types: ${added.join(', ')}`,
+            });
+        }
+    }
+    // Compare semantic structure
+    if (baseline.semantic && current.semantic) {
+        // Check heading changes
+        const baselineHeadings = baseline.semantic.headings;
+        const currentHeadings = current.semantic.headings;
+        for (const level in baselineHeadings) {
+            if (baselineHeadings[level] !== currentHeadings[level]) {
+                changes.push({
+                    type: 'semantic',
+                    severity: 'low',
+                    description: `${level} count changed from ${baselineHeadings[level]} to ${currentHeadings[level]}`,
+                });
+            }
+        }
+        // Check landmark changes
+        const baselineLandmarks = baseline.semantic.landmarks;
+        const currentLandmarks = current.semantic.landmarks;
+        for (const landmark in baselineLandmarks) {
+            if (baselineLandmarks[landmark] !==
+                currentLandmarks[landmark]) {
+                changes.push({
+                    type: 'semantic',
+                    severity: 'medium',
+                    description: `Landmark ${landmark} ${baselineLandmarks[landmark] ? 'removed' : 'added'}`,
+                });
+            }
+        }
+    }
+    return changes;
+}

package/dist/types.d.ts

@@ -0,0 +1,368 @@
+/**
+ * Types for Testivai Witness Playwright SDK
+ *
+ * Defines the data shapes for evidence collection:
+ * - SnapshotPayload: DOM + Layout data for a single snapshot
+ * - BatchPayload: Git + Browser info + collection of snapshots
+ * - TestivAIConfig: Configuration for visual analysis behavior
+ */
+/**
+ * Layout configuration for visual analysis
+ */
+export interface LayoutConfig {
+    /** Sensitivity level: 0-4 scale (0=strict/precise, 4=very lenient) */
+    sensitivity: number;
+    /** Base pixel tolerance for layout differences */
+    tolerance: number;
+    /** Per-selector tolerance overrides (optional) */
+    selectorTolerances?: Record<string, number>;
+    /** Use relative tolerance for large elements (optional) */
+    useRelativeTolerance?: boolean;
+    /** Percentage multiplier for relative tolerance (optional) */
+    relativeTolerance?: number;
+}
+/**
+ * AI configuration for visual analysis
+ */
+export interface AIConfig {
+    /** Sensitivity level: 0-4 scale (0=conservative, 4=aggressive) */
+    sensitivity: number;
+    /** Minimum confidence threshold for AI_BUG verdict (0.0-1.0) */
+    confidence: number;
+    /** Include AI reasoning in results (optional) */
+    enableReasoning?: boolean;
+}
+/**
+ * Performance metrics configuration
+ */
+export interface PerformanceMetricsConfig {
+    /** Enable performance metrics capture (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Structure analysis configuration
+ * Controls how page structure (HTML elements, hierarchy, semantics) is analyzed.
+ * @renamed Was `DOMAnalysisConfig` — renamed to conceal internal layer terminology (IP protection)
+ */
+export interface StructureAnalysisConfig {
+    /** Enable fingerprint generation (default: true) */
+    enableFingerprint?: boolean;
+    /** Enable structural analysis (default: true) */
+    enableStructure?: boolean;
+    /** Enable semantic analysis (default: true) */
+    enableSemantic?: boolean;
+    /** Attributes to ignore in analysis */
+    ignoreAttributes?: string[];
+    /** Elements to ignore completely */
+    ignoreElements?: string[];
+    /** Content patterns to ignore */
+    ignoreContentPatterns?: RegExp[];
+}
+/**
+ * Structure fingerprint and analysis result
+ * Contains the structural analysis of a page: element fingerprint, hierarchy info, and semantic structure.
+ * @renamed Was `DOMAnalysis` — renamed to conceal internal layer terminology (IP protection)
+ */
+export interface StructureAnalysis {
+    /** Fast hash of normalized DOM structure */
+    fingerprint?: string;
+    /** Structural information about the DOM */
+    structure?: {
+        totalElements: number;
+        elementTypes: Record<string, number>;
+        maxDepth: number;
+        interactiveElements: {
+            buttons: number;
+            inputs: number;
+            links: number;
+            forms: number;
+        };
+    };
+    /** Semantic structure information */
+    semantic?: {
+        headings: Record<string, number>;
+        landmarks: {
+            hasHeader: boolean;
+            hasNav: boolean;
+            hasMain: boolean;
+            hasFooter: boolean;
+            hasAside: boolean;
+        };
+        lists: {
+            ordered: number;
+            unordered: number;
+        };
+        tables: number;
+        images: number;
+    };
+    /** Component analysis (if detectable) */
+    components?: Record<string, Array<{
+        selector: string;
+        text: string;
+        attributes: Record<string, string>;
+    }>>;
+}
+/**
+ * Structure change information
+ * Describes a detected change in page structure between baseline and current.
+ * @renamed Was `DOMChange` — renamed to conceal internal layer terminology (IP protection)
+ */
+export interface StructureChange {
+    type: 'fingerprint' | 'structure' | 'semantic' | 'component';
+    severity: 'low' | 'medium' | 'high';
+    description: string;
+    details?: any;
+}
+/**
+ * Performance timing metrics
+ * @deprecated Use performanceMetrics with CDP Performance.getMetrics instead
+ */
+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
+ * @deprecated Lighthouse has been removed. Use performanceMetrics with CDP Performance.getMetrics instead
+ */
+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
+ */
+export interface EnvironmentConfig {
+    /** Configuration for CI environments */
+    ci?: {
+        layout?: Partial<LayoutConfig>;
+        ai?: Partial<AIConfig>;
+    };
+    /** Configuration for development environments */
+    development?: {
+        layout?: Partial<LayoutConfig>;
+        ai?: Partial<AIConfig>;
+    };
+    /** Configuration for production environments */
+    production?: {
+        layout?: Partial<LayoutConfig>;
+        ai?: Partial<AIConfig>;
+    };
+}
+/**
+ * Complete TestivAI project configuration
+ */
+export interface TestivAIProjectConfig {
+    /** API key for authentication */
+    apiKey?: string;
+    /** API endpoint URL (defaults to production) */
+    apiUrl?: string;
+    /** Layout analysis settings */
+    layout: LayoutConfig;
+    /** AI analysis settings */
+    ai: AIConfig;
+    /** Performance metrics settings (optional) */
+    performanceMetrics?: PerformanceMetricsConfig;
+    /**
+     * Structure analysis settings (optional)
+     * @renamed Was `dom` — renamed to conceal internal layer terminology (IP protection)
+     */
+    structure?: StructureAnalysisConfig;
+    /** Environment-specific overrides (optional) */
+    environments?: EnvironmentConfig;
+}
+/**
+ * Per-test configuration overrides
+ */
+export interface TestivAIConfig {
+    /** Layout settings (optional - overrides project defaults) */
+    layout?: Partial<LayoutConfig>;
+    /** AI settings (optional - overrides project defaults) */
+    ai?: Partial<AIConfig>;
+    /** Performance settings (optional - overrides project defaults) */
+    performanceMetrics?: Partial<PerformanceMetricsConfig>;
+    /**
+     * Structure analysis settings (optional - overrides project defaults)
+     * @renamed Was `dom` — renamed to conceal internal layer terminology (IP protection)
+     */
+    structure?: Partial<StructureAnalysisConfig>;
+    /** Element selectors to capture (existing option) */
+    selectors?: string[];
+    /** Use Chrome DevTools Protocol for full-page capture (default: true - use CDP, set to false for scroll-and-stitch) */
+    useCDP?: boolean;
+}
+/**
+ * Layout/Bounding box data for an element
+ */
+export interface LayoutData {
+    /** X coordinate */
+    x: number;
+    /** Y coordinate */
+    y: number;
+    /** Width */
+    width: number;
+    /** Height */
+    height: number;
+    /** Top position */
+    top: number;
+    /** Left position */
+    left: number;
+    /** Right position */
+    right: number;
+    /** Bottom position */
+    bottom: number;
+}
+/**
+ * Page structure snapshot data (HTML content)
+ * @renamed Was `DOMData` — renamed to conceal internal layer terminology (IP protection)
+ */
+export interface StructureData {
+    /** Serialized HTML of the element */
+    html: string;
+    /** Computed styles (optional) */
+    styles?: Record<string, string>;
+}
+/**
+ * Computed styles data for visual comparison
+ * @renamed Was `CSSData` — renamed to conceal internal layer terminology (IP protection)
+ */
+export interface StylesData {
+    /** Computed styles keyed by element selector path */
+    computed_styles: Record<string, Record<string, string>>;
+}
+/**
+ * Snapshot payload for a single evidence capture
+ */
+export interface SnapshotPayload {
+    /**
+     * Page structure data (HTML content)
+     * @renamed Was `dom` — renamed to conceal internal layer terminology (IP protection)
+     */
+    structure: StructureData;
+    /**
+     * Computed styles data (optional)
+     * @renamed Was `css` — renamed to conceal internal layer terminology (IP protection)
+     */
+    styles?: StylesData;
+    /** Layout/bounding box data */
+    layout: LayoutData;
+    /** Timestamp when snapshot was taken */
+    timestamp: number;
+    /** Test name or identifier */
+    testName: string;
+    /** Snapshot name or identifier */
+    snapshotName: string;
+    /** URL of the page when snapshot was taken */
+    url?: string;
+    /** Viewport dimensions */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** 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;
+    /**
+     * Structure analysis results (optional)
+     * @renamed Was `domAnalysis` — renamed to conceal internal layer terminology (IP protection)
+     */
+    structureAnalysis?: StructureAnalysis;
+}
+/**
+ * Git information for batch context
+ */
+export interface GitInfo {
+    /** Current branch name */
+    branch: string;
+    /** Current commit hash */
+    commit: string;
+    /** Repository URL (optional) */
+    repository?: string;
+    /** Commit message (optional) */
+    message?: string;
+    /** Author name (optional) */
+    author?: string;
+}
+/**
+ * Browser context information
+ */
+export interface BrowserInfo {
+    /** Browser name (chromium, firefox, webkit) */
+    name: string;
+    /** Browser version */
+    version: string;
+    /** Viewport width */
+    viewportWidth: number;
+    /** Viewport height */
+    viewportHeight: number;
+    /** User agent string */
+    userAgent: string;
+    /** Operating system */
+    os?: string;
+    /** Device type (desktop, mobile, tablet) */
+    device?: string;
+}
+/**
+ * CI environment information for integration feedback (e.g., GitHub commit statuses, PR comments).
+ * Mirrors CiInfo from ci.ts for payload serialization.
+ */
+export interface CiInfoPayload {
+    /** CI provider name (e.g., 'github_actions', 'gitlab_ci', 'circleci') */
+    provider: string;
+    /** Pull/Merge request number (if available) */
+    prNumber?: number;
+    /** URL to the CI run (if available) */
+    runUrl?: string;
+    /** CI build/run identifier */
+    buildId?: string;
+}
+/**
+ * Batch payload containing all evidence for a test run
+ */
+export interface BatchPayload {
+    /** Git information */
+    git: GitInfo;
+    /** Browser context information */
+    browser: BrowserInfo;
+    /** Collection of snapshots */
+    snapshots: SnapshotPayload[];
+    /** Batch ID (generated) */
+    batchId: string;
+    /** Timestamp when batch was created */
+    timestamp: number;
+    /** Unique identifier for a CI/CD run, to group sharded jobs */
+    runId?: string | null;
+    /** CI environment information for integration feedback (optional) */
+    ci?: CiInfoPayload | null;
+}

package/dist/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Types for Testivai Witness Playwright SDK
+ *
+ * Defines the data shapes for evidence collection:
+ * - SnapshotPayload: DOM + Layout data for a single snapshot
+ * - BatchPayload: Git + Browser info + collection of snapshots
+ * - TestivAIConfig: Configuration for visual analysis behavior
+ */
+Object.defineProperty(exports, "__esModule", { value: true });