commit d89fe8646cc1476f8dd5876ebf3266a20b2d2f9b Author: Zhongwei Li Date: Sun Nov 30 08:23:48 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..b1931fa --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "visual-regression-tester", + "description": "Visual diff testing with Percy, Chromatic, BackstopJS - catch unintended UI changes", + "version": "1.0.0", + "author": { + "name": "Claude Code Plugin Hub", + "email": "[email protected]" + }, + "skills": [ + "./skills" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..a3446bc --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# visual-regression-tester + +Visual diff testing with Percy, Chromatic, BackstopJS - catch unintended UI changes diff --git a/commands/visual-test.md b/commands/visual-test.md new file mode 100644 index 0000000..9d4d330 --- /dev/null +++ b/commands/visual-test.md @@ -0,0 +1,90 @@ +--- +description: Visual regression testing with screenshot comparison and diff analysis +shortcut: vt +--- + +# Visual Regression Tester + +Automated visual regression testing using screenshot comparison, pixel-perfect diff analysis, and integration with Percy, Chromatic, BackstopJS, and Playwright. + +## What You Do + +1. **Setup Visual Tests** + - Configure screenshot capture for components/pages + - Define viewport sizes and breakpoints + - Set up baseline images + +2. **Run Visual Comparisons** + - Capture current screenshots + - Compare against baselines + - Generate visual diffs + +3. **Analyze Changes** + - Review visual differences + - Classify intentional vs unintended changes + - Update baselines selectively + +4. **CI/CD Integration** + - Configure visual testing in pipelines + - Set up approval workflows + - Manage baseline updates + +## Usage Pattern + +When invoked, you should: + +1. Identify components/pages to test visually +2. Configure appropriate visual testing tool +3. Generate baseline screenshots if needed +4. Run visual comparison tests +5. Analyze and report visual differences +6. Provide recommendations for baseline updates + +## Output Format + +```markdown +## Visual Regression Test Report + +### Tests Run: [N] +**Tool:** [Percy / Chromatic / BackstopJS / Playwright] +**Viewports:** [list] + +### Visual Changes Detected: [N] + +#### Component: [Name] +**Status:** [New / Changed / Removed] +**Diff Score:** [X%] + +**Change Summary:** +- Layout shift: [description] +- Color changes: [description] +- Size changes: [description] + +**Screenshots:** +- Baseline: `[path]` +- Current: `[path]` +- Diff: `[path]` + +**Classification:** [Intentional / Bug / Review Needed] +**Recommendation:** [Accept / Reject / Investigate] + +### Summary + No changes: [N] + Minor changes: [N] + Major changes: [N] + +### Next Steps +- [ ] Review flagged changes +- [ ] Update baselines for intentional changes +- [ ] Investigate regressions +- [ ] Update visual test coverage +``` + +## Supported Tools + +- Percy (cloud-based visual testing) +- Chromatic (Storybook integration) +- BackstopJS (open-source) +- Playwright screenshots +- Puppeteer visual regression +- Cypress screenshots diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..fa75588 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,77 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:jeremylongshore/claude-code-plugins-plus:plugins/testing/visual-regression-tester", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "45d5d4b9016b2335eee0e9027d21e47170ba2a52", + "treeHash": "8e55f05e5c3daa67557031dfe2cca670d5952f320318079a053ca1e7702bb3f2", + "generatedAt": "2025-11-28T10:18:51.487272Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "visual-regression-tester", + "description": "Visual diff testing with Percy, Chromatic, BackstopJS - catch unintended UI changes", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "9f1c8b5eb067835377337fab3165b8f78fb2257371c55fd01bb215f4067252da" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "2543683aabd0770dbec8caf9bd618807d44f9835b9551645affd5f8d276ed2d4" + }, + { + "path": "commands/visual-test.md", + "sha256": "8b87b53f5516fdcf6e3c463eb6d885168f3c16a706d14a9d52c02c953105de9b" + }, + { + "path": "skills/visual-regression-tester/SKILL.md", + "sha256": "07009ee07a37607f6d9151141498fd566a78e26d42c40e442f52d0558c984532" + }, + { + "path": "skills/visual-regression-tester/references/README.md", + "sha256": "95baf547ba4943f874dbb09a63a8a672fcd2b312309846a8909bb37ec046b2de" + }, + { + "path": "skills/visual-regression-tester/scripts/README.md", + "sha256": "f8d39bbf4ddee123ccf6c0ba278d8441253c17fd56b517b1d631ab5889e99c68" + }, + { + "path": "skills/visual-regression-tester/assets/example_backstop_config.js", + "sha256": "010fe4400a51c111a5efb9e041ad82e2d98f29c40497e4e8a18a1b44bf73a0ab" + }, + { + "path": "skills/visual-regression-tester/assets/html_report_template.html", + "sha256": "ce4fa826a11981dac98ac14d2426ed36b343cc8262206b2d9a2be120038f4bd9" + }, + { + "path": "skills/visual-regression-tester/assets/example_percy_config.yml", + "sha256": "33337e2a56f3c8a9b58cea8593fc21db0dd536e31153afbd75e2b63bfaae58c3" + }, + { + "path": "skills/visual-regression-tester/assets/README.md", + "sha256": "c368cbccaff5b91f89d51a2eef2f8c9467b43d182aefc3c5b61aa06dafddca25" + }, + { + "path": "skills/visual-regression-tester/assets/example_chromatic_config.yml", + "sha256": "b727a94b40742b2c0e2836863c2714be9538ced042ccb467834c08a6e4d946b5" + } + ], + "dirSha256": "8e55f05e5c3daa67557031dfe2cca670d5952f320318079a053ca1e7702bb3f2" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/visual-regression-tester/SKILL.md b/skills/visual-regression-tester/SKILL.md new file mode 100644 index 0000000..af0c68e --- /dev/null +++ b/skills/visual-regression-tester/SKILL.md @@ -0,0 +1,54 @@ +--- +name: performing-visual-regression-testing +description: | + This skill enables Claude to execute visual regression tests using tools like Percy, Chromatic, and BackstopJS. It captures screenshots, compares them against baselines, and analyzes visual differences to identify unintended UI changes. Use this skill when the user requests visual testing, UI change verification, or regression testing for a web application or component. Trigger phrases include "visual test," "UI regression," "check visual changes," or "/visual-test". +allowed-tools: Read, Bash, Grep, Glob +version: 1.0.0 +--- + +## Overview + +This skill empowers Claude to automatically detect unintended UI changes by performing visual regression tests. It integrates with popular visual testing tools to streamline the process of capturing screenshots, comparing them against baselines, and identifying visual differences. + +## How It Works + +1. **Capture Screenshots**: Captures screenshots of specified components or pages using the configured visual testing tool. +2. **Compare Against Baselines**: Compares the captured screenshots against established baseline images. +3. **Analyze Visual Diffs**: Identifies and analyzes visual differences between the current screenshots and the baselines. + +## When to Use This Skill + +This skill activates when you need to: +- Detect unintended UI changes introduced by recent code modifications. +- Verify the visual consistency of a web application across different browsers or environments. +- Automate visual regression testing as part of a CI/CD pipeline. + +## Examples + +### Example 1: Verifying UI Changes After a Feature Update + +User request: "Run a visual test on the homepage to check for any UI regressions after the latest feature update." + +The skill will: +1. Capture a screenshot of the homepage. +2. Compare the screenshot against the baseline image of the homepage. +3. Report any visual differences detected, highlighting potential UI regressions. + +### Example 2: Checking Visual Consistency Across Browsers + +User request: "Perform a visual regression test on the product details page to ensure it renders correctly in Chrome and Firefox." + +The skill will: +1. Capture screenshots of the product details page in both Chrome and Firefox. +2. Compare the screenshots against the respective baseline images for each browser. +3. Identify and report any visual inconsistencies detected between the browsers. + +## Best Practices + +- **Configuration**: Ensure the visual testing tool is properly configured with the correct API keys and project settings. +- **Baselines**: Maintain accurate and up-to-date baseline images to avoid false positives. +- **Viewport Sizes**: Define appropriate viewport sizes to cover different screen resolutions and devices. + +## Integration + +This skill can be integrated with other Claude Code plugins to automate end-to-end testing workflows. For example, it can be combined with a testing plugin to run visual tests after functional tests have passed. \ No newline at end of file diff --git a/skills/visual-regression-tester/assets/README.md b/skills/visual-regression-tester/assets/README.md new file mode 100644 index 0000000..00f59c5 --- /dev/null +++ b/skills/visual-regression-tester/assets/README.md @@ -0,0 +1,8 @@ +# Assets + +Bundled resources for visual-regression-tester skill + +- [ ] example_percy_config.yml: Example Percy configuration file. +- [ ] example_chromatic_config.yml: Example Chromatic configuration file. +- [ ] example_backstop_config.js: Example BackstopJS configuration file. +- [ ] html_report_template.html: HTML template for generating visual regression test reports. diff --git a/skills/visual-regression-tester/assets/example_backstop_config.js b/skills/visual-regression-tester/assets/example_backstop_config.js new file mode 100644 index 0000000..48c6fc5 --- /dev/null +++ b/skills/visual-regression-tester/assets/example_backstop_config.js @@ -0,0 +1,72 @@ +/** + * BackstopJS Configuration File + * + * This is an example configuration file for BackstopJS. Customize it to fit your project's needs. + * + * For detailed documentation, visit: https://github.com/garris/BackstopJS + */ + +module.exports = { + id: 'my-project', // A unique ID for your project, used for report naming. Change this! + + viewports: [ + { + label: 'desktop', + width: 1920, + height: 1080, + }, + { + label: 'mobile', + width: 320, + height: 480, + }, + ], + + onBeforeScript: 'puppet/onBefore.js', + onReadyScript: 'puppet/onReady.js', + + scenarios: [ + { + label: 'Example Homepage', // A descriptive label for this scenario + url: 'https://example.com', // The URL to test + referenceUrl: '', // Optional: URL for the baseline/reference screenshots. Leave empty for first run. + readyEvent: '', // Optional: Wait for a specific event to fire before taking the screenshot. + readySelector: '', // Optional: Wait for a specific selector to be present before taking the screenshot. + delay: 0, // Optional: Wait for a specified number of milliseconds before taking the screenshot. Useful for animations. + hideSelectors: [], // Optional: Hide elements before taking the screenshot. Useful for dynamic content. + removeSelectors: [], // Optional: Remove elements before taking the screenshot. Useful for dynamic content. + selectorExpansion: true, // Optional: Expand selectors to include all matching elements. + selectors: [ + 'document', // Take a screenshot of the entire document + ], + misMatchThreshold: 0.1, // Percentage of acceptable pixel difference between the baseline and the test screenshot. + requireSameDimensions: true, // Ensure that the baseline and test screenshots have the same dimensions. + }, + // Add more scenarios here to test different pages and components. + // Example: + // { + // label: 'Example Contact Page', + // url: 'https://example.com/contact', + // selectors: [ + // '.contact-form', + // ], + // }, + ], + + paths: { + bitmaps_reference: 'backstop_data/bitmaps_reference', + bitmaps_test: 'backstop_data/bitmaps_test', + html_report: 'backstop_data/html_report', + ci_report: 'backstop_data/ci_report', + }, + + report: ['browser'], // Generate a browser-based HTML report. + engine: 'puppeteer', // Use Puppeteer as the browser automation engine. + engineOptions: { + args: ['--no-sandbox'], // Required for running Puppeteer in some environments (e.g., Docker). + }, + asyncCaptureLimit: 5, // Limit the number of concurrent screenshots to avoid overloading the system. + asyncCompareLimit: 50, // Limit the number of concurrent comparisons to avoid overloading the system. + debug: false, // Enable debug mode for more verbose logging. + debugWindow: false, // Open the browser window in debug mode. +}; \ No newline at end of file diff --git a/skills/visual-regression-tester/assets/example_chromatic_config.yml b/skills/visual-regression-tester/assets/example_chromatic_config.yml new file mode 100644 index 0000000..a01ca73 --- /dev/null +++ b/skills/visual-regression-tester/assets/example_chromatic_config.yml @@ -0,0 +1,55 @@ +# Configuration for Chromatic visual regression testing +# https://www.chromatic.com/ + +# Project token - REPLACE_ME with your actual Chromatic project token. +# This token is used to authenticate with Chromatic and identify your project. +projectToken: REPLACE_ME + +# Branch name - Optional, defaults to the current git branch. +# You can specify a branch name manually if needed. +branchName: main + +# Commit SHA - Optional, defaults to the current git commit SHA. +# Used to link the Chromatic build to a specific commit. +commitSha: YOUR_VALUE_HERE # e.g., "a1b2c3d4e5f6g7h8i9j0" + +# Repository slug - Optional, defaults to the origin URL from git config. +# Format: / (e.g., "my-org/my-repo") +repositorySlug: YOUR_VALUE_HERE # e.g., "my-org/my-repo" + +# Build number - Optional, defaults to the CI build number (if available). +# Useful for tracking specific builds within your CI/CD system. +buildNumber: YOUR_VALUE_HERE # e.g., "1234" + +# Auto Accept Changes - Flag to automatically accept all changes. USE WITH CAUTION! +# Useful in CI environments where you want to automatically approve visual changes. +# Set to 'true' to auto-accept all changes, 'false' to require manual approval. +autoAcceptChanges: false + +# Ignore Files - List of file patterns to ignore during screenshot collection. +# Use glob patterns to match files or directories. +ignoreFiles: + - "**/node_modules/**" + - "**/dist/**" + - "**/build/**" + +# Include Files - List of file patterns to include during screenshot collection. +# Use glob patterns to match files or directories. If not specified, all files are considered. +includeFiles: + - "**/src/**/*.stories.@(js|jsx|ts|tsx)" + - "**/stories/**/*.stories.@(js|jsx|ts|tsx)" + +# Storybook URL - The URL of your deployed Storybook instance. +# If not specified, Chromatic will attempt to build and serve Storybook locally. +# Useful when you want to use a pre-built Storybook instance. +storybookUrl: YOUR_VALUE_HERE # e.g., "https://your-storybook.example.com" + +# Debug - Enable debug mode for more verbose logging. +debug: false + +# Options specific to the Chromatic CLI. See https://www.chromatic.com/docs/cli-options for full details. +chromaticFlags: + # Example: --only-changed + onlyChanged: false + # Example: --exit-zero-on-changes + exitZeroOnChanges: false \ No newline at end of file diff --git a/skills/visual-regression-tester/assets/example_percy_config.yml b/skills/visual-regression-tester/assets/example_percy_config.yml new file mode 100644 index 0000000..67ef740 --- /dev/null +++ b/skills/visual-regression-tester/assets/example_percy_config.yml @@ -0,0 +1,42 @@ +# Percy configuration file example +# This file defines the settings for running visual regression tests using Percy. + +version: 2 +# Percy configuration version. Keep this as 2 for the latest stable features. + +percy: + # Percy specific settings + token: REPLACE_ME # Your Percy project token. Get this from the Percy dashboard. + branch: main # The branch to compare against. Defaults to 'main' or environment variable. + parallel: true # Enable parallel test execution for faster results. + widths: # Viewport widths to capture screenshots at. Important for responsive testing. + - 375 # Mobile + - 768 # Tablet + - 1280 # Desktop + minimum_height: 1024 # Minimum height for the screenshot. Useful for pages that dynamically load content. + debug: false # Enable debug logging. Useful for troubleshooting. + +# Generic configuration for test execution +test: + url: "YOUR_VALUE_HERE" # The base URL of your application. e.g., "https://example.com" + files: + - "path/to/your/test/file.js" # Example test file. Can be a glob pattern. + - "another/test/file.spec.ts" # Example test file. Can be a glob pattern. + # Test framework specific configurations. These are examples, adjust to your framework. + # This plugin doesn't execute the tests, it just passes the config along to Percy CLI or similar. + framework: + type: playwright # Example: "playwright", "cypress", "selenium" + options: # Framework specific options. Consult your framework's documentation. + headless: true # Run tests in headless mode. Good for CI/CD. + browser: chromium # Browser to use for testing. e.g., "chromium", "firefox", "webkit" + +# Environment variables to pass to the test execution environment. +# Useful for injecting credentials or other configuration values. +environment: + API_KEY: "YOUR_API_KEY" # Example API key. Replace with your actual key. + DATABASE_URL: "YOUR_DATABASE_URL" # Example database URL. Replace with your actual URL. + +# Optional: Configure custom snapshot names. Useful for making reports easier to read. +snapshots: + prefix: "Component_" # Prefix for all snapshot names. + suffix: "_Example" # Suffix for all snapshot names. \ No newline at end of file diff --git a/skills/visual-regression-tester/assets/html_report_template.html b/skills/visual-regression-tester/assets/html_report_template.html new file mode 100644 index 0000000..3a8ad8c --- /dev/null +++ b/skills/visual-regression-tester/assets/html_report_template.html @@ -0,0 +1,139 @@ + + + + + + Visual Regression Test Report + + + + +
+

Visual Regression Test Report

+ +

Date: {{report_date}}

+

Generated By: Visual Regression Tester Plugin

+ +

Summary

+

Total Tests: {{total_tests}}

+

Passed: {{passed_tests}}

+

Failed: {{failed_tests}}

+

Pending: {{pending_tests}}

+ +

Test Results

+ + {{test_results}} + +
+

Report generated by Visual Regression Tester plugin.

+
+
+ + + \ No newline at end of file diff --git a/skills/visual-regression-tester/references/README.md b/skills/visual-regression-tester/references/README.md new file mode 100644 index 0000000..3c2164d --- /dev/null +++ b/skills/visual-regression-tester/references/README.md @@ -0,0 +1,8 @@ +# References + +Bundled resources for visual-regression-tester skill + +- [ ] percy_api_docs.md: Documentation for the Percy API, including authentication, project setup, and test execution. +- [ ] chromatic_api_docs.md: Documentation for the Chromatic API, including authentication, project setup, and test execution. +- [ ] backstopjs_config.md: Example BackstopJS configuration file with detailed explanations of each option. +- [ ] visual_testing_best_practices.md: A guide to best practices for visual regression testing, including test setup, baseline management, and change classification. diff --git a/skills/visual-regression-tester/scripts/README.md b/skills/visual-regression-tester/scripts/README.md new file mode 100644 index 0000000..6bf8a3b --- /dev/null +++ b/skills/visual-regression-tester/scripts/README.md @@ -0,0 +1,7 @@ +# Scripts + +Bundled resources for visual-regression-tester skill + +- [ ] run_visual_tests.sh: Executes visual regression tests using specified tool and configuration. +- [ ] update_baselines.sh: Updates the baseline images for visual regression tests. +- [ ] analyze_diffs.py: Analyzes the visual differences and classifies them as intentional or unintended.