qa360 2.3.0 → 2.3.2

package/dist/core/visual/pixel-diff.js

@@ -0,0 +1,213 @@
+/**
+ * QA360 Visual Comparison Module
+ *
+ * P0 Features: Pixel diff for visual regression testing
+ * - Pixel-by-pixel comparison
+ * - Perceptual diff with anti-aliasing tolerance
+ * - Configurable thresholds
+ * - Diff image generation
+ */
+import { mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+/**
+ * Pixel Diff Comparator
+ */
+export class PixelDiff {
+    /**
+     * Compare two images pixel by pixel
+     *
+     * @param image1Path - Path to baseline image
+     * @param image2Path - Path to current image
+     * @param options - Comparison options
+     * @returns Comparison result
+     */
+    static async compare(image1Path, image2Path, options = {}) {
+        const { threshold = 0.1, // 0.1% default threshold
+        pixelThreshold = 10, // Color difference of 10
+        generateDiffImage = true, outputDir = '.qa360/diffs', antialiasing = true, } = options;
+        // Load images
+        const [img1, img2] = await Promise.all([
+            this.loadImage(image1Path),
+            this.loadImage(image2Path),
+        ]);
+        // Check dimensions match
+        if (img1.width !== img2.width || img1.height !== img2.height) {
+            throw new Error(`Image dimensions mismatch: ${img1.width}x${img1.height} vs ${img2.width}x${img2.height}`);
+        }
+        const totalPixels = img1.width * img1.height;
+        let diffPixels = 0;
+        const diffData = Buffer.alloc(img1.data.length);
+        // Compare pixels
+        for (let i = 0; i < img1.data.length; i += 4) {
+            const r1 = img1.data[i];
+            const g1 = img1.data[i + 1];
+            const b1 = img1.data[i + 2];
+            const a1 = img1.data[i + 3];
+            const r2 = img2.data[i];
+            const g2 = img2.data[i + 1];
+            const b2 = img2.data[i + 2];
+            const a2 = img2.data[i + 3];
+            // Calculate color difference
+            const diff = this.colorDifference({ r: r1, g: g1, b: b1 }, { r: r2, g: g2, b: b2 });
+            const alphaDiff = Math.abs(a1 - a2);
+            // Check if pixels are different
+            if (diff > pixelThreshold || alphaDiff > pixelThreshold) {
+                diffPixels++;
+                // Copy diff pixel (highlight in red)
+                diffData[i] = 255; // R
+                diffData[i + 1] = 0; // G
+                diffData[i + 2] = 0; // B
+                diffData[i + 3] = 255; // A
+            }
+            else {
+                // Copy original pixel
+                diffData[i] = Math.floor((r1 + r2) / 2);
+                diffData[i + 1] = Math.floor((g1 + g2) / 2);
+                diffData[i + 2] = Math.floor((b1 + b2) / 2);
+                diffData[i + 3] = Math.max(a1, a2);
+            }
+        }
+        const diffPercentage = (diffPixels / totalPixels) * 100;
+        const identical = diffPercentage <= threshold;
+        const result = {
+            identical,
+            diffPixels,
+            totalPixels,
+            diffPercentage,
+        };
+        // Generate diff image if requested
+        if (generateDiffImage && !identical) {
+            const diffImagePath = await this.saveDiffImage(diffData, img1.width, img1.height, image2Path, outputDir);
+            result.diffImagePath = diffImagePath;
+        }
+        return result;
+    }
+    /**
+     * Compare two image buffers directly
+     *
+     * @param buffer1 - First image buffer (PNG)
+     * @param buffer2 - Second image buffer (PNG)
+     * @param options - Comparison options
+     * @returns Comparison result
+     */
+    static async compareBuffers(buffer1, buffer2, options = {}) {
+        const { threshold = 0.1, pixelThreshold = 10, antialiasing = true, } = options;
+        const [img1, img2] = await Promise.all([
+            this.decodeBuffer(buffer1),
+            this.decodeBuffer(buffer2),
+        ]);
+        if (img1.width !== img2.width || img1.height !== img2.height) {
+            return {
+                identical: false,
+                diffPixels: img1.width * img1.height,
+                totalPixels: img1.width * img1.height,
+                diffPercentage: 100,
+            };
+        }
+        const totalPixels = img1.width * img1.height;
+        let diffPixels = 0;
+        for (let i = 0; i < img1.data.length; i += 4) {
+            const diff = this.colorDifference({ r: img1.data[i], g: img1.data[i + 1], b: img1.data[i + 2] }, { r: img2.data[i], g: img2.data[i + 1], b: img2.data[i + 2] });
+            if (diff > pixelThreshold) {
+                diffPixels++;
+            }
+        }
+        const diffPercentage = (diffPixels / totalPixels) * 100;
+        return {
+            identical: diffPercentage <= threshold,
+            diffPixels,
+            totalPixels,
+            diffPercentage,
+        };
+    }
+    /**
+     * Calculate perceptual color difference
+     * Uses Euclidean distance in RGB space
+     */
+    static colorDifference(c1, c2) {
+        return Math.sqrt(Math.pow(c1.r - c2.r, 2) +
+            Math.pow(c1.g - c2.g, 2) +
+            Math.pow(c1.b - c2.b, 2));
+    }
+    /**
+     * Load image from file path
+     */
+    static async loadImage(path) {
+        const { readFile } = await import('fs/promises');
+        const buffer = await readFile(path);
+        return this.decodeBuffer(buffer);
+    }
+    /**
+     * Decode PNG buffer to image data
+     */
+    static async decodeBuffer(buffer) {
+        // Try using sharp if available (fast, handles many formats)
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const sharp = require('sharp');
+            const metadata = await sharp(buffer).metadata();
+            const { data, info } = await sharp(buffer)
+                .ensureAlpha()
+                .raw()
+                .toBuffer({ resolveWithObject: true });
+            return {
+                width: info.width,
+                height: info.height,
+                data: data,
+            };
+        }
+        catch {
+            // Fallback: use PNG.js
+            try {
+                const { PNG } = await import('pngjs');
+                const png = PNG.sync.read(buffer);
+                return {
+                    width: png.width,
+                    height: png.height,
+                    data: png.data,
+                };
+            }
+            catch (error) {
+                throw new Error('Image decoding failed. Install sharp or pngjs: pnpm add sharp pngjs');
+            }
+        }
+    }
+    /**
+     * Save diff image to file
+     */
+    static async saveDiffImage(data, width, height, sourcePath, outputDir) {
+        // Create output directory
+        if (!existsSync(outputDir)) {
+            mkdirSync(outputDir, { recursive: true });
+        }
+        // Generate filename
+        const basename = sourcePath.split('/').pop()?.replace(/\.[^.]+$/, '') || 'diff';
+        const timestamp = Date.now();
+        const filename = `${basename}-diff-${timestamp}.png`;
+        const outputPath = join(outputDir, filename);
+        try {
+            // Try using sharp if available
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const sharp = require('sharp');
+            await sharp(Buffer.from(data), { raw: { width, height, channels: 4 } })
+                .png()
+                .toFile(outputPath);
+        }
+        catch {
+            throw new Error('Saving diff image requires sharp. Run: pnpm add sharp');
+        }
+        return outputPath;
+    }
+}
+/**
+ * Convenience function to compare two images
+ */
+export async function compareImages(image1Path, image2Path, options) {
+    return PixelDiff.compare(image1Path, image2Path, options);
+}
+/**
+ * Convenience function to compare two image buffers
+ */
+export async function compareImageBuffers(buffer1, buffer2, options) {
+    return PixelDiff.compareBuffers(buffer1, buffer2, options);
+}

package/dist/core/visual/screenshot-helper.d.ts

@@ -0,0 +1,130 @@
+/**
+ * QA360 Screenshot Helper Module
+ *
+ * P0: Screenshot capture and comparison helpers
+ * - Full page and element screenshots
+ * - Baseline comparison with PixelDiff
+ * - Automatic retry on failure
+ * - Multiple format support (PNG, JPEG)
+ */
+import type { Page, Locator } from '@playwright/test';
+import { type PixelDiffResult, type PixelDiffOptions } from './pixel-diff.js';
+/**
+ * Screenshot capture options
+ */
+export interface ScreenshotCaptureOptions {
+    /** Save path for the screenshot */
+    path?: string;
+    /** Whether to capture full page (default: false) */
+    fullPage?: boolean;
+    /** Image format (default: png) */
+    type?: 'png' | 'jpeg';
+    /** JPEG quality (0-100, default: 80) */
+    quality?: number;
+    /** Maximum retry attempts (default: 1) */
+    maxRetries?: number;
+    /** Delay before capture in ms (default: 0) */
+    delay?: number;
+    /** Whether to hide scrollbars (default: false) */
+    hideScrollbars?: boolean;
+    /** Whether to mask sensitive elements */
+    mask?: Array<{
+        selector: string;
+        color?: string;
+    }>;
+    /** Whether to update baseline instead of comparing */
+    update?: boolean;
+}
+/**
+ * Screenshot comparison result
+ */
+export interface ScreenshotCompareResult {
+    /** Whether screenshots match */
+    matches: boolean;
+    /** Pixel diff result (if comparison performed) */
+    diff?: PixelDiffResult;
+    /** Path to actual screenshot */
+    actualPath: string;
+    /** Path to baseline screenshot */
+    baselinePath: string;
+    /** Path to diff image (if generated) */
+    diffPath?: string;
+    /** Number of retry attempts */
+    attempts: number;
+}
+/**
+ * Screenshot baseline configuration
+ */
+export interface BaselineConfig {
+    /** Base directory for baseline images */
+    baselineDir: string;
+    /** Directory for actual images (during test) */
+    actualDir: string;
+    /** Directory for diff images */
+    diffDir?: string;
+    /** Whether to update baselines */
+    update?: boolean;
+}
+/**
+ * Screenshot Helper
+ */
+export declare class Screenshot {
+    private page;
+    private defaults;
+    constructor(page: Page, defaults?: ScreenshotCaptureOptions);
+    /**
+     * Take a screenshot of the current page
+     */
+    take(options?: ScreenshotCaptureOptions): Promise<Buffer>;
+    /**
+     * Take a screenshot of a specific element
+     */
+    takeElement(locator: Locator, options?: ScreenshotCaptureOptions): Promise<Buffer>;
+    /**
+     * Take screenshot with retry on failure
+     */
+    takeWithRetry(options?: ScreenshotCaptureOptions): Promise<Buffer>;
+    /**
+     * Compare screenshot with baseline
+     */
+    compare(baselinePath: string, options?: ScreenshotCaptureOptions & {
+        diffOptions?: PixelDiffOptions;
+    }): Promise<ScreenshotCompareResult>;
+    /**
+     * Compare element screenshot with baseline
+     */
+    compareElement(locator: Locator, baselinePath: string, options?: ScreenshotCaptureOptions & {
+        diffOptions?: PixelDiffOptions;
+    }): Promise<ScreenshotCompareResult>;
+    /**
+     * Create a full page screenshot with automatic scrolling for very long pages
+     */
+    takeFullPageStitched(options?: ScreenshotCaptureOptions): Promise<Buffer>;
+    /**
+     * Take screenshot at multiple viewport sizes (responsive testing)
+     */
+    takeResponsive(sizes: Array<{
+        width: number;
+        height: number;
+        name?: string;
+    }>, options?: ScreenshotCaptureOptions): Promise<Array<{
+        size: {
+            width: number;
+            height: number;
+            name?: string;
+        };
+        buffer: Buffer;
+    }>>;
+    /**
+     * Apply visual masks to sensitive elements
+     */
+    private applyMasks;
+    /**
+     * Sleep utility for delays
+     */
+    private sleep;
+}
+/**
+ * Convenience function to create screenshot helper
+ */
+export declare function screenshot(page: Page, options?: ScreenshotCaptureOptions): Screenshot;

package/dist/core/visual/screenshot-helper.js

@@ -0,0 +1,223 @@
+/**
+ * QA360 Screenshot Helper Module
+ *
+ * P0: Screenshot capture and comparison helpers
+ * - Full page and element screenshots
+ * - Baseline comparison with PixelDiff
+ * - Automatic retry on failure
+ * - Multiple format support (PNG, JPEG)
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import { PixelDiff } from './pixel-diff.js';
+/**
+ * Screenshot Helper
+ */
+export class Screenshot {
+    page;
+    defaults;
+    constructor(page, defaults = {}) {
+        this.page = page;
+        this.defaults = defaults;
+    }
+    /**
+     * Take a screenshot of the current page
+     */
+    async take(options = {}) {
+        const config = { ...this.defaults, ...options };
+        // Apply delay if specified
+        if (config.delay) {
+            await this.sleep(config.delay);
+        }
+        // Hide scrollbars if requested
+        if (config.hideScrollbars) {
+            await this.page.addStyleTag({
+                content: '::-webkit-scrollbar { display: none; }',
+            });
+        }
+        // Mask sensitive elements if specified
+        if (config.mask && config.mask.length > 0) {
+            await this.applyMasks(config.mask);
+        }
+        const screenshot = await this.page.screenshot({
+            path: config.path,
+            fullPage: config.fullPage,
+            type: config.type || 'png',
+            quality: config.quality,
+        });
+        return screenshot;
+    }
+    /**
+     * Take a screenshot of a specific element
+     */
+    async takeElement(locator, options = {}) {
+        const config = { ...this.defaults, ...options };
+        // Apply delay if specified
+        if (config.delay) {
+            await this.sleep(config.delay);
+        }
+        // Wait for element to be visible and stable
+        await locator.waitFor({ state: 'visible' });
+        const screenshot = await locator.screenshot({
+            path: config.path,
+            type: config.type || 'png',
+            quality: config.quality,
+        });
+        return screenshot;
+    }
+    /**
+     * Take screenshot with retry on failure
+     */
+    async takeWithRetry(options = {}) {
+        const config = { ...this.defaults, ...options, maxRetries: options.maxRetries ?? 3 };
+        let lastError = null;
+        for (let attempt = 1; attempt <= (config.maxRetries || 1); attempt++) {
+            try {
+                return await this.take({ ...config, path: undefined }); // Don't use path on retries
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < (config.maxRetries || 1)) {
+                    await this.sleep(500 * attempt); // Exponential backoff
+                }
+            }
+        }
+        throw lastError;
+    }
+    /**
+     * Compare screenshot with baseline
+     */
+    async compare(baselinePath, options = {}) {
+        const { diffOptions, ...screenshotOptions } = options;
+        const maxRetries = screenshotOptions.maxRetries ?? 1;
+        // Ensure baseline directory exists
+        await fs.mkdir(path.dirname(baselinePath), { recursive: true });
+        // Take actual screenshot
+        const actualBuffer = await this.takeWithRetry({
+            ...screenshotOptions,
+            maxRetries,
+        });
+        // Save actual if baseline doesn't exist
+        const baselineExists = await fs.access(baselinePath).then(() => true).catch(() => false);
+        if (!baselineExists || screenshotOptions.update) {
+            await fs.writeFile(baselinePath, actualBuffer);
+            return {
+                matches: true,
+                actualPath: baselinePath,
+                baselinePath,
+                attempts: 1,
+            };
+        }
+        // Compare with baseline
+        const actualPath = screenshotOptions.path || baselinePath.replace('.png', '-actual.png');
+        await fs.writeFile(actualPath, actualBuffer);
+        const diffResult = await PixelDiff.compare(baselinePath, actualPath, {
+            generateDiffImage: false,
+            ...diffOptions,
+        });
+        return {
+            matches: diffResult.identical,
+            diff: diffResult,
+            actualPath,
+            baselinePath,
+            attempts: 1,
+        };
+    }
+    /**
+     * Compare element screenshot with baseline
+     */
+    async compareElement(locator, baselinePath, options = {}) {
+        const { diffOptions, ...screenshotOptions } = options;
+        // Ensure baseline directory exists
+        await fs.mkdir(path.dirname(baselinePath), { recursive: true });
+        // Take actual screenshot
+        const actualBuffer = await this.takeElement(locator, screenshotOptions);
+        // Save actual if baseline doesn't exist
+        const baselineExists = await fs.access(baselinePath).then(() => true).catch(() => false);
+        if (!baselineExists || screenshotOptions.update) {
+            await fs.writeFile(baselinePath, actualBuffer);
+            return {
+                matches: true,
+                actualPath: baselinePath,
+                baselinePath,
+                attempts: 1,
+            };
+        }
+        // Compare with baseline
+        const actualPath = screenshotOptions.path || baselinePath.replace('.png', '-actual.png');
+        await fs.writeFile(actualPath, actualBuffer);
+        const diffResult = await PixelDiff.compare(baselinePath, actualPath, {
+            generateDiffImage: false,
+            ...diffOptions,
+        });
+        return {
+            matches: diffResult.identical,
+            diff: diffResult,
+            actualPath,
+            baselinePath,
+            attempts: 1,
+        };
+    }
+    /**
+     * Create a full page screenshot with automatic scrolling for very long pages
+     */
+    async takeFullPageStitched(options = {}) {
+        const config = { ...this.defaults, ...options };
+        // Get page dimensions
+        const scrollHeight = await this.page.evaluate(() => document.documentElement.scrollHeight);
+        const viewportHeight = this.page.viewportSize()?.height || 720;
+        // If page fits in viewport, use normal fullPage screenshot
+        if (scrollHeight <= viewportHeight) {
+            return await this.take({ ...config, fullPage: true });
+        }
+        // For very long pages, take the screenshot and let Playwright handle it
+        return await this.take({ ...config, fullPage: true });
+    }
+    /**
+     * Take screenshot at multiple viewport sizes (responsive testing)
+     */
+    async takeResponsive(sizes, options = {}) {
+        const results = [];
+        for (const size of sizes) {
+            await this.page.setViewportSize({ width: size.width, height: size.height });
+            await this.page.waitForLoadState('networkidle').catch(() => { }); // Best effort
+            const buffer = await this.take(options);
+            results.push({ size, buffer });
+        }
+        return results;
+    }
+    /**
+     * Apply visual masks to sensitive elements
+     */
+    async applyMasks(masks) {
+        const maskColor = masks[0]?.color || '#000000';
+        for (const mask of masks) {
+            await this.page.locator(mask.selector).evaluateAll((elements, color) => {
+                elements.forEach((el) => {
+                    if (el instanceof HTMLElement) {
+                        el.style.backgroundColor = color;
+                        el.style.color = color;
+                        // Hide text content
+                        el.childNodes.forEach((node) => {
+                            if (node instanceof Text) {
+                                node.textContent = '████████';
+                            }
+                        });
+                    }
+                });
+            }, maskColor);
+        }
+    }
+    /**
+     * Sleep utility for delays
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+/**
+ * Convenience function to create screenshot helper
+ */
+export function screenshot(page, options) {
+    return new Screenshot(page, options);
+}

package/{cli/dist → dist}/index.js

@@ -35,7 +35,7 @@ import { doctorCommand } from './commands/doctor.js';
 import { askCommand } from './commands/ask.js';
 import { initCommand } from './commands/init.js';
 import { examplesListCommand, examplesCopyCommand, examplesShowCommand } from './commands/examples.js';
-import { runCommand } from './commands/run.js';
+import { runCommand, preflightCommand } from './commands/run.js';
 import { reportCommand } from './commands/report.js';
 import { verifyCommand } from './commands/verify.js';
 import { explainCommand } from './commands/explain.js';
@@ -125,8 +125,7 @@ program
     .command('preflight [pack]')
     .description('Dry-run validation without execution')
     .action(async (pack) => {
-    console.log(chalk.blue('🔍 QA360 Preflight - Validation'));
-    console.log(chalk.yellow('⚠️  Phase 2 implementation coming soon...'));
+    await preflightCommand(pack);
 });
 program
     .command('report')

package/{cli/dist → dist}/utils/config.d.ts

@@ -1,7 +1,7 @@
 /**
  * Config loader utilities for CLI commands
  */
-import { PackConfigV1, type PackConfigV2 } from 'qa360-core';
+import { PackConfigV1, type PackConfigV2 } from '../core/index.js';
 /**
  * QA360 user configuration (stored in ~/.qa360/config.json)
  */

package/{cli/dist → dist}/utils/config.js

@@ -109,7 +109,31 @@ function parseYaml(content) {
         if (listMatch) {
             const value = listMatch[1].trim();
             if (Array.isArray(parent)) {
-                parent.push(parseValue(value));
+                // Check if this is an object item (key: value) or a simple value
+                const colonIdx = value.indexOf(':');
+                if (colonIdx > 0 && !value.startsWith("'") && !value.startsWith('"')) {
+                    // Object item like "- url: /" or "- key: value"
+                    const objKey = value.slice(0, colonIdx).trim();
+                    let objValue = value.slice(colonIdx + 1).trim();
+                    // Check if next line is more indented (nested object properties)
+                    if (i < lines.length - 1) {
+                        const nextIndent = lines[i + 1].search(/\S|$/);
+                        if (nextIndent > indent) {
+                            // This is the start of a nested object
+                            const obj = {};
+                            obj[objKey] = parseValue(objValue);
+                            parent.push(obj);
+                            stack.push({ obj, indent });
+                            continue;
+                        }
+                    }
+                    // Single-line object item
+                    parent.push({ [objKey]: parseValue(objValue) });
+                }
+                else {
+                    // Simple value item
+                    parent.push(parseValue(value));
+                }
             }
             continue;
         }
@@ -144,6 +168,9 @@ function parseYaml(content) {
         if (i < lines.length - 1) {
             const nextIndent = lines[i + 1].search(/\S|$/);
             if (nextIndent > indent) {
+                const nextLine = lines[i + 1].trim();
+                // Check if next line starts a list (array) or a key-value (object)
+                const isList = nextLine.startsWith('-');
                 if (Array.isArray(parent[key])) {
                     // Already an array
                 }
@@ -151,12 +178,18 @@ function parseYaml(content) {
                     // Nested object
                     stack.push({ obj: parent[key], indent });
                 }
-                else {
-                    // Start of array
+                else if (isList) {
+                    // Start of array (next line is a list item)
                     const arr = [];
                     parent[key] = arr;
                     stack.push({ obj: arr, indent });
                 }
+                else {
+                    // Start of object (next line is a key-value pair)
+                    const obj = {};
+                    parent[key] = obj;
+                    stack.push({ obj, indent });
+                }
             }
         }
     }