Visual Regression Monitor DevTools Plugin

A comprehensive TanStack DevTools plugin for visual regression testing with screenshot capture, comparison, and Playwright integration.

Features

📸 Screenshot Capture

• Playwright Integration: Seamless integration with Playwright MCP tools for browser automation
• Responsive Testing: Capture screenshots across multiple viewport breakpoints
• Cross-Browser Support: Test on Chromium, Firefox, and WebKit engines
• Element Targeting: Capture specific page elements using CSS selectors
• Animation Capture: Frame-by-frame recording of UI animations and transitions

🔍 Visual Comparison

• Advanced Diff Algorithm: Pixel-by-pixel comparison with configurable sensitivity
• SSIM Analysis: Structural Similarity Index for perceptually accurate comparisons
• Perceptual Hashing: Fast similarity detection using image fingerprinting
• Threshold Configuration: Customizable difference thresholds for pass/fail criteria
• Region Analysis: Detailed breakdown of changed areas with severity levels

📱 Responsive Testing

• Breakpoint Management: Predefined and custom viewport configurations
• Layout Shift Detection: Automatic detection of significant layout changes
• Cross-Viewport Comparison: Compare the same URL across different screen sizes
• Mobile/Desktop Testing: Simulate different device types and orientations

📊 Timeline & Analytics

• Activity Timeline: Chronological view of testing activities
• Test Suite Management: Organize screenshots into logical test groups
• Statistics Dashboard: Comprehensive metrics on test results and coverage
• Export/Import: Configuration and results export for CI/CD integration

Installation

npm install @sucoza/visual-regression-monitor-devtools-plugin

Usage

Basic Setup

import { PluginPanel } from '@sucoza/visual-regression-monitor-devtools-plugin';

// Use as a standalone component
function DevTools() {
  return (
    <div className="devtools-container">
      <PluginPanel />
    </div>
  );
}

With TanStack DevTools

import { createVisualRegressionDevToolsClient } from '@sucoza/visual-regression-monitor-devtools-plugin';

const client = createVisualRegressionDevToolsClient();

// Access plugin functionality
const { screenshots, visualDiffs, settings } = client.getState();

Hooks API

import { useScreenshots, useVisualDiff, useResponsiveTesting } from '@sucoza/visual-regression-monitor-devtools-plugin';

function MyComponent() {
  const { screenshots, actions } = useScreenshots();
  const { visualDiffs, actions: diffActions } = useVisualDiff();
  const { breakpoints, actions: responsiveActions } = useResponsiveTesting();

  // Capture a screenshot
  const handleCapture = async () => {
    await actions.captureScreenshot({
      url: 'https://example.com',
      name: 'Homepage',
      viewport: { width: 1920, height: 1080, deviceScaleFactor: 1, isMobile: false }
    });
  };

  // Compare screenshots
  const handleCompare = async () => {
    await diffActions.compareScreenshots(baselineId, comparisonId);
  };

  // Responsive testing
  const handleResponsiveTesting = async () => {
    await responsiveActions.testUrlAcrossBreakpoints('https://example.com');
  };

  return (
    <div>
      <button onClick={handleCapture}>Capture Screenshot</button>
      <button onClick={handleCompare}>Compare Screenshots</button>
      <button onClick={handleResponsiveTesting}>Test Responsive</button>
    </div>
  );
}

Configuration

Screenshot Settings

const settings = {
  captureSettings: {
    fullPage: false,
    hideScrollbars: true,
    disableAnimations: false,
    waitForFonts: true,
    waitForImages: true,
    delay: 0,
    quality: 90,
    format: 'png'
  }
};

Responsive Breakpoints

const breakpoints = [
  { name: 'Mobile', width: 375, height: 667, deviceScaleFactor: 2, isMobile: true },
  { name: 'Tablet', width: 768, height: 1024, deviceScaleFactor: 1, isMobile: false },
  { name: 'Desktop', width: 1920, height: 1080, deviceScaleFactor: 1, isMobile: false },
];

Diff Configuration

const diffOptions = {
  ignoreAntialiasing: true,
  ignoreColors: false,
  threshold: 0.2,
  regions: [
    { x: 0, y: 0, width: 100, height: 100 } // Exclude specific regions
  ]
};

Playwright MCP Integration

This plugin integrates with Playwright MCP (Model Context Protocol) tools for browser automation:

// Example MCP tool usage (handled internally by the plugin)
// mcp__playwright__browser_navigate({ url: 'https://example.com' })
// mcp__playwright__browser_resize({ width: 1920, height: 1080 })
// mcp__playwright__browser_take_screenshot({ fullPage: true })

API Reference

Core Functions

Screenshot Management

• captureScreenshot(request: CaptureRequest): Capture a single screenshot
• captureResponsiveScreenshots(url: string, viewports: Viewport[]): Capture across multiple viewports
• captureAnimationFrames(url: string, selector: string, duration: number): Record animation frames

Visual Comparison

• compareScreenshots(baselineId: string, comparisonId: string): Compare two screenshots
• batchCompareScreenshots(baselineId: string, comparisonIds: string[]): Batch comparison
• calculateSimilarityScore(image1: ImageData, image2: ImageData): Calculate similarity

State Management

• getState(): Get current plugin state
• subscribe(callback: Function): Subscribe to state changes
• dispatch(action: DevToolsAction): Dispatch state updates

Types

interface Screenshot {
  id: string;
  name: string;
  url: string;
  selector?: string;
  viewport: Viewport;
  browserEngine: BrowserEngine;
  timestamp: number;
  dataUrl: string;
  metadata: ScreenshotMetadata;
  tags?: string[];
}

interface VisualDiff {
  id: string;
  baselineId: string;
  comparisonId: string;
  timestamp: number;
  status: 'passed' | 'failed' | 'pending';
  differences: DiffRegion[];
  metrics: DiffMetrics;
  threshold: number;
}

interface CaptureRequest {
  url: string;
  selector?: string;
  viewport?: Viewport;
  options?: Partial<CaptureSettings>;
  browserEngine?: BrowserEngine;
  name?: string;
  tags?: string[];
}

Example Application

Run the example application to see the plugin in action:

cd example
npm install
npm run dev

The example includes:

• Plugin demonstration with all features
• Different layout patterns for testing
• Interactive controls for exploring functionality

Development

Build

npm run build        # Build for production
npm run dev          # Build in watch mode
npm run typecheck    # Type checking
npm run lint         # ESLint
npm run format       # Prettier

Testing

npm test             # Run tests
npm run test:ui      # Run tests with UI

Architecture

The plugin follows TanStack DevTools patterns:

• Event-Driven Architecture: Uses @tanstack/devtools-event-client for communication
• Zustand State Management: Central state store with useSyncExternalStore
• Component Architecture: Modular React components with hooks
• TypeScript: Full type safety throughout the codebase
• Build System: Rollup with dual CJS/ESM output

Directory Structure

src/
├── components/          # React UI components
│   ├── PluginPanel.tsx     # Main devtools panel
│   ├── ScreenshotCapture.tsx # Screenshot interface
│   ├── VisualDiff.tsx      # Diff visualization
│   ├── Timeline.tsx        # Activity timeline
│   ├── ComparisonView.tsx  # Animation analysis
│   └── Settings.tsx        # Configuration
├── core/               # Business logic
│   ├── devtools-client.ts  # Event client integration
│   ├── devtools-store.ts   # Zustand store
│   ├── screenshot-engine.ts # Playwright integration
│   ├── diff-algorithm.ts   # Visual comparison
│   └── storage.ts          # Persistence layer
├── hooks/              # Custom React hooks
│   ├── useScreenshots.ts   # Screenshot management
│   ├── useVisualDiff.ts    # Diff operations
│   └── useResponsiveTesting.ts # Responsive testing
├── types/              # TypeScript definitions
├── utils/              # Utility functions
│   ├── image-processing.ts # Image manipulation
│   └── index.ts           # General utilities
└── index.ts            # Main exports

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

MIT

Part of the @sucoza TanStack DevTools ecosystem.

Support

• 📖 Documentation
• 🐛 Bug Reports
• 💬 Discussions
• 📧 Support

Part of the @sucoza TanStack DevTools ecosystem.