@browserflow-ai/generator 0.0.6

package/src/visual-checks.test.ts

@@ -0,0 +1,232 @@
+/**
+ * visual-checks.test.ts
+ * Tests for visual check code generation, including region mask support.
+ */
+
+import { describe, it, expect } from 'bun:test';
+import type { MaskRegion } from '@browserflow-ai/core';
+import {
+  generateScreenshotAssertion,
+  generateScreenshotCapture,
+  generateMaskSetupCode,
+} from './visual-checks.js';
+
+describe('visual-checks', () => {
+  describe('generateScreenshotAssertion', () => {
+    it('generates basic screenshot assertion without masks', () => {
+      const result = generateScreenshotAssertion({ name: 'homepage' });
+
+      expect(result).toContain("await expect(page).toHaveScreenshot('homepage.png');");
+    });
+
+    it('generates screenshot assertion with selector-based mask', () => {
+      const masks: MaskRegion[] = [
+        { selector: '.timestamp', reason: 'Dynamic timestamp' },
+      ];
+      const result = generateScreenshotAssertion({ name: 'homepage', mask: masks });
+
+      expect(result).toContain("mask: [page.locator('.timestamp')]");
+    });
+
+    it('generates screenshot assertion with region-based mask', () => {
+      const masks: MaskRegion[] = [
+        {
+          region: { x: 10, y: 20, width: 100, height: 50 },
+          reason: 'Dynamic ad section',
+        },
+      ];
+      const result = generateScreenshotAssertion({ name: 'homepage', mask: masks });
+
+      // Should generate overlay element reference
+      expect(result).toContain("mask: [page.locator('[data-bf-mask=\"0\"]')]");
+    });
+
+    it('generates screenshot assertion with mixed masks', () => {
+      const masks: MaskRegion[] = [
+        { selector: '.timestamp' },
+        { region: { x: 10, y: 20, width: 100, height: 50 } },
+        { selector: '.user-avatar' },
+        { region: { x: 80, y: 5, width: 15, height: 10 } },
+      ];
+      const result = generateScreenshotAssertion({ name: 'dashboard', mask: masks });
+
+      // Should include both selector and region masks
+      expect(result).toContain("page.locator('.timestamp')");
+      expect(result).toContain("page.locator('[data-bf-mask=\"0\"]')");
+      expect(result).toContain("page.locator('.user-avatar')");
+      expect(result).toContain("page.locator('[data-bf-mask=\"1\"]')");
+    });
+
+    it('handles empty mask array', () => {
+      const result = generateScreenshotAssertion({ name: 'page', mask: [] });
+
+      // Should not include mask option when array is empty
+      expect(result).not.toContain('mask:');
+    });
+
+    it('uses correct page variable for masks', () => {
+      const masks: MaskRegion[] = [
+        { selector: '.dynamic-content' },
+      ];
+      const result = generateScreenshotAssertion(
+        { name: 'test', mask: masks },
+        { pageVar: 'customPage' }
+      );
+
+      expect(result).toContain("customPage.locator('.dynamic-content')");
+    });
+  });
+
+  describe('generateScreenshotCapture', () => {
+    it('generates capture with selector-based mask', () => {
+      const masks: MaskRegion[] = [
+        { selector: '.timestamp' },
+      ];
+      const result = generateScreenshotCapture({ name: 'capture', mask: masks });
+
+      expect(result).toContain("mask: [page.locator('.timestamp')]");
+    });
+
+    it('generates capture with region-based mask', () => {
+      const masks: MaskRegion[] = [
+        { region: { x: 25, y: 30, width: 40, height: 20 } },
+      ];
+      const result = generateScreenshotCapture({ name: 'capture', mask: masks });
+
+      expect(result).toContain("mask: [page.locator('[data-bf-mask=\"0\"]')]");
+    });
+
+    it('generates capture with mixed masks', () => {
+      const masks: MaskRegion[] = [
+        { selector: '.header' },
+        { region: { x: 0, y: 90, width: 100, height: 10 } },
+      ];
+      const result = generateScreenshotCapture({ name: 'capture', mask: masks });
+
+      expect(result).toContain("page.locator('.header')");
+      expect(result).toContain("page.locator('[data-bf-mask=\"0\"]')");
+    });
+  });
+
+  describe('generateMaskSetupCode', () => {
+    it('generates no setup code when no region masks present', () => {
+      const masks: MaskRegion[] = [
+        { selector: '.timestamp' },
+        { selector: '.user-avatar' },
+      ];
+      const result = generateMaskSetupCode(masks);
+
+      expect(result).toBe('');
+    });
+
+    it('generates overlay injection for single region mask', () => {
+      const masks: MaskRegion[] = [
+        { region: { x: 10, y: 20, width: 100, height: 50 } },
+      ];
+      const result = generateMaskSetupCode(masks);
+
+      // Should inject overlay element with correct positioning
+      expect(result).toContain('await page.evaluate');
+      expect(result).toContain('document.createElement');
+      expect(result).toContain("div.setAttribute('data-bf-mask'");
+      expect(result).toContain('left:10%');
+      expect(result).toContain('top:20%');
+      expect(result).toContain('width:100%');
+      expect(result).toContain('height:50%');
+      expect(result).toContain('position:fixed');
+      expect(result).toContain('pointer-events:none');
+      expect(result).toContain('z-index:99999');
+      expect(result).toContain('document.body.appendChild');
+    });
+
+    it('generates overlay injection for multiple region masks', () => {
+      const masks: MaskRegion[] = [
+        { selector: '.header' },
+        { region: { x: 10, y: 20, width: 30, height: 40 } },
+        { region: { x: 80, y: 5, width: 15, height: 10 } },
+        { selector: '.footer' },
+      ];
+      const result = generateMaskSetupCode(masks);
+
+      // Should only process region masks (indices 0 and 1 for regions)
+      expect(result).toContain('await page.evaluate');
+      expect(result).toContain('left:10%');
+      expect(result).toContain('top:20%');
+      expect(result).toContain('left:80%');
+      expect(result).toContain('top:5%');
+      // Should create two overlay elements
+      expect((result.match(/data-bf-mask/g) || []).length).toBe(2);
+    });
+
+    it('uses correct data attribute indices for region masks', () => {
+      const masks: MaskRegion[] = [
+        { region: { x: 0, y: 0, width: 50, height: 50 } },  // index 0
+        { selector: '.selector1' },                         // not counted
+        { region: { x: 50, y: 50, width: 50, height: 50 } }, // index 1
+        { selector: '.selector2' },                         // not counted
+        { region: { x: 25, y: 25, width: 50, height: 50 } }, // index 2
+      ];
+      const result = generateMaskSetupCode(masks);
+
+      // Should use indices 0, 1, 2 for the three region masks
+      expect(result).toContain("'data-bf-mask', '0'");
+      expect(result).toContain("'data-bf-mask', '1'");
+      expect(result).toContain("'data-bf-mask', '2'");
+    });
+
+    it('handles empty mask array', () => {
+      const result = generateMaskSetupCode([]);
+
+      expect(result).toBe('');
+    });
+
+    it('uses custom page variable when provided', () => {
+      const masks: MaskRegion[] = [
+        { region: { x: 10, y: 20, width: 30, height: 40 } },
+      ];
+      const result = generateMaskSetupCode(masks, 'customPage');
+
+      expect(result).toContain('await customPage.evaluate');
+    });
+  });
+
+  describe('mask array generation edge cases', () => {
+    it('preserves order of mixed masks', () => {
+      const masks: MaskRegion[] = [
+        { selector: '.first' },
+        { region: { x: 10, y: 10, width: 10, height: 10 } },
+        { selector: '.second' },
+        { region: { x: 20, y: 20, width: 20, height: 20 } },
+        { selector: '.third' },
+      ];
+      const result = generateScreenshotAssertion({ name: 'test', mask: masks });
+
+      // Should maintain order in mask array
+      // Use greedy match to handle attribute selectors with brackets
+      const maskArrayMatch = result.match(/mask: \[(.*)\]/s);
+      expect(maskArrayMatch).toBeTruthy();
+
+      const maskArray = maskArrayMatch![1];
+      const firstIndex = maskArray.indexOf("'.first'");
+      const secondIndex = maskArray.indexOf('[data-bf-mask="0"]');
+      const thirdIndex = maskArray.indexOf("'.second'");
+      const fourthIndex = maskArray.indexOf('[data-bf-mask="1"]');
+      const fifthIndex = maskArray.indexOf("'.third'");
+
+      expect(firstIndex).toBeLessThan(secondIndex);
+      expect(secondIndex).toBeLessThan(thirdIndex);
+      expect(thirdIndex).toBeLessThan(fourthIndex);
+      expect(fourthIndex).toBeLessThan(fifthIndex);
+    });
+
+    it('escapes special characters in selector masks', () => {
+      const masks: MaskRegion[] = [
+        { selector: "div[data-test='value']" },
+      ];
+      const result = generateScreenshotAssertion({ name: 'test', mask: masks });
+
+      // Should properly escape the selector string
+      expect(result).toContain("page.locator('div[data-test=\\'value\\']')");
+    });
+  });
+});

package/src/visual-checks.ts

@@ -0,0 +1,294 @@
+/**
+ * visual-checks.ts
+ * Generates Playwright screenshot assertion code.
+ */
+
+import type { MaskRegion } from '@browserflow-ai/core';
+import { escapeString } from './locator-emit.js';
+
+/**
+ * Options for screenshot assertion generation.
+ */
+export interface ScreenshotOptions {
+  /** Name for the screenshot (used in baseline path) */
+  name: string;
+  /** Regions to mask during comparison */
+  mask?: MaskRegion[];
+  /** Maximum allowed pixel difference (0-1) */
+  maxDiffPixelRatio?: number;
+  /** Threshold for pixel color difference (0-1) */
+  threshold?: number;
+  /** Animation handling: "disabled" waits for animations to finish */
+  animations?: 'disabled' | 'allow';
+  /** Whether to capture full page */
+  fullPage?: boolean;
+  /** Timeout for screenshot capture */
+  timeout?: number;
+}
+
+/**
+ * Options for visual check code generation.
+ */
+export interface VisualCheckEmitOptions {
+  /** Variable name for the page object (default: "page") */
+  pageVar?: string;
+  /** Base path for baseline screenshots */
+  baselinesPath?: string;
+  /** Include comments explaining the assertion */
+  includeComments?: boolean;
+}
+
+/**
+ * Generates code for a Playwright toHaveScreenshot assertion.
+ *
+ * @example
+ * generateScreenshotAssertion({ name: 'homepage' })
+ * // Returns: "await expect(page).toHaveScreenshot('homepage.png');"
+ */
+export function generateScreenshotAssertion(
+  options: ScreenshotOptions,
+  emitOptions: VisualCheckEmitOptions = {}
+): string {
+  const { pageVar = 'page', includeComments = false } = emitOptions;
+  const lines: string[] = [];
+
+  if (includeComments && options.name) {
+    lines.push(`// Visual check: ${options.name}`);
+  }
+
+  const screenshotName = options.name.endsWith('.png')
+    ? options.name
+    : `${options.name}.png`;
+
+  const assertionOptions = buildAssertionOptions(options, pageVar);
+
+  if (assertionOptions) {
+    lines.push(
+      `await expect(${pageVar}).toHaveScreenshot('${escapeString(screenshotName)}', ${assertionOptions});`
+    );
+  } else {
+    lines.push(
+      `await expect(${pageVar}).toHaveScreenshot('${escapeString(screenshotName)}');`
+    );
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Generates code for an element-specific screenshot assertion.
+ *
+ * @example
+ * generateElementScreenshotAssertion("page.locator('.card')", { name: 'card' })
+ * // Returns: "await expect(page.locator('.card')).toHaveScreenshot('card.png');"
+ */
+export function generateElementScreenshotAssertion(
+  locatorCode: string,
+  options: ScreenshotOptions,
+  emitOptions: VisualCheckEmitOptions = {}
+): string {
+  const { pageVar = 'page', includeComments = false } = emitOptions;
+  const lines: string[] = [];
+
+  if (includeComments && options.name) {
+    lines.push(`// Visual check (element): ${options.name}`);
+  }
+
+  const screenshotName = options.name.endsWith('.png')
+    ? options.name
+    : `${options.name}.png`;
+
+  const assertionOptions = buildAssertionOptions(options, pageVar);
+
+  if (assertionOptions) {
+    lines.push(
+      `await expect(${locatorCode}).toHaveScreenshot('${escapeString(screenshotName)}', ${assertionOptions});`
+    );
+  } else {
+    lines.push(
+      `await expect(${locatorCode}).toHaveScreenshot('${escapeString(screenshotName)}');`
+    );
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Builds the options object string for toHaveScreenshot.
+ */
+function buildAssertionOptions(options: ScreenshotOptions, pageVar = 'page'): string {
+  const parts: string[] = [];
+
+  if (options.maxDiffPixelRatio !== undefined) {
+    parts.push(`maxDiffPixelRatio: ${options.maxDiffPixelRatio}`);
+  }
+
+  if (options.threshold !== undefined) {
+    parts.push(`threshold: ${options.threshold}`);
+  }
+
+  if (options.animations) {
+    parts.push(`animations: '${options.animations}'`);
+  }
+
+  if (options.fullPage !== undefined) {
+    parts.push(`fullPage: ${options.fullPage}`);
+  }
+
+  if (options.timeout !== undefined) {
+    parts.push(`timeout: ${options.timeout}`);
+  }
+
+  if (options.mask && options.mask.length > 0) {
+    const maskCode = generateMaskArray(options.mask, pageVar);
+    parts.push(`mask: ${maskCode}`);
+  }
+
+  if (parts.length === 0) {
+    return '';
+  }
+
+  return `{ ${parts.join(', ')} }`;
+}
+
+/**
+ * Generates code for a mask array.
+ */
+function generateMaskArray(masks: MaskRegion[], pageVar = 'page'): string {
+  let regionMaskIndex = 0;
+  const maskItems = masks
+    .map((mask) => {
+      if (mask.selector) {
+        return `${pageVar}.locator('${escapeString(mask.selector)}')`;
+      }
+      if (mask.region) {
+        // Create reference to overlay element that will be injected
+        const selector = `[data-bf-mask="${regionMaskIndex}"]`;
+        const locatorCode = `${pageVar}.locator('${escapeString(selector)}')`;
+        regionMaskIndex++;
+        return locatorCode;
+      }
+      return null;
+    })
+    .filter((item): item is string => item !== null);
+
+  if (maskItems.length === 0) {
+    return '[]';
+  }
+
+  return `[${maskItems.join(', ')}]`;
+}
+
+/**
+ * Generates a screenshot capture statement (not an assertion).
+ */
+export function generateScreenshotCapture(
+  options: ScreenshotOptions,
+  emitOptions: VisualCheckEmitOptions = {}
+): string {
+  const { pageVar = 'page', baselinesPath, includeComments = false } = emitOptions;
+  const lines: string[] = [];
+
+  if (includeComments && options.name) {
+    lines.push(`// Capture screenshot: ${options.name}`);
+  }
+
+  const screenshotName = options.name.endsWith('.png')
+    ? options.name
+    : `${options.name}.png`;
+
+  const path = baselinesPath
+    ? `${baselinesPath}/${screenshotName}`
+    : screenshotName;
+
+  const captureOptions: string[] = [];
+  captureOptions.push(`path: '${escapeString(path)}'`);
+
+  if (options.fullPage !== undefined) {
+    captureOptions.push(`fullPage: ${options.fullPage}`);
+  }
+
+  if (options.animations) {
+    captureOptions.push(`animations: '${options.animations}'`);
+  }
+
+  if (options.mask && options.mask.length > 0) {
+    const maskCode = generateMaskArray(options.mask, pageVar);
+    captureOptions.push(`mask: ${maskCode}`);
+  }
+
+  lines.push(
+    `await ${pageVar}.screenshot({ ${captureOptions.join(', ')} });`
+  );
+
+  return lines.join('\n');
+}
+
+/**
+ * Generates code for comparing two screenshot paths.
+ * This is useful for custom comparison logic outside of Playwright's built-in assertions.
+ */
+export function generateScreenshotCompare(
+  actualPath: string,
+  expectedPath: string,
+  options: { threshold?: number } = {}
+): string {
+  const { threshold = 0.05 } = options;
+  return `
+// Compare screenshots
+const actualBuffer = await fs.readFile('${escapeString(actualPath)}');
+const expectedBuffer = await fs.readFile('${escapeString(expectedPath)}');
+const { diffPixelRatio } = await compareImages(actualBuffer, expectedBuffer);
+expect(diffPixelRatio).toBeLessThanOrEqual(${threshold});
+`.trim();
+}
+
+/**
+ * Generates a helper import statement for visual comparisons.
+ */
+export function generateVisualImports(): string {
+  return `import { expect } from '@playwright/test';`;
+}
+
+/**
+ * Generates wait-for-animations code before taking a screenshot.
+ */
+export function generateWaitForAnimations(pageVar = 'page'): string {
+  return `// Wait for animations to complete
+await ${pageVar}.waitForLoadState('networkidle');
+await ${pageVar}.waitForTimeout(500);`;
+}
+
+/**
+ * Generates code to inject overlay elements for region-based masks.
+ * Returns empty string if no region masks are present.
+ */
+export function generateMaskSetupCode(
+  masks: MaskRegion[],
+  pageVar = 'page'
+): string {
+  // Filter to only region-based masks
+  const regionMasks = masks.filter((m) => m.region);
+
+  if (regionMasks.length === 0) {
+    return '';
+  }
+
+  // Generate individual injection statements for each region mask
+  // Each block is wrapped in its own scope to reuse variable name 'div'
+  const injectionStatements = regionMasks
+    .map((mask, index) => {
+      const r = mask.region!;
+      return `  {
+    const div = document.createElement('div');
+    div.setAttribute('data-bf-mask', '${index}');
+    div.style.cssText = 'position:fixed;left:${r.x}%;top:${r.y}%;width:${r.width}%;height:${r.height}%;pointer-events:none;z-index:99999';
+    document.body.appendChild(div);
+  }`;
+    })
+    .join('\n');
+
+  return `await ${pageVar}.evaluate(() => {
+${injectionStatements}
+});`;
+}