@vizzly-testing/cli 0.10.3 → 0.11.0

package/.claude-plugin/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "vizzly": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/vizzly-server/index.js"]
+    }
+  }
+}

package/.claude-plugin/README.md

@@ -0,0 +1,114 @@
+# Vizzly Claude Code Plugin
+
+> Integrate Vizzly visual regression testing seamlessly into your Claude Code workflow
+
+This plugin brings Vizzly's powerful visual testing capabilities directly into Claude Code, helping you debug visual regressions, manage baselines, and integrate visual testing into your development workflow—all with AI assistance.
+
+## Installation
+
+### From GitHub (Recommended)
+
+```bash
+# Add the marketplace
+/plugin marketplace add vizzly-testing/vizzly-cli
+
+# Install the plugin
+/plugin install vizzly@vizzly-marketplace
+```
+
+### From Local Source
+
+```bash
+# Clone the repository
+git clone https://github.com/vizzly-testing/vizzly-cli.git
+cd vizzly-cli
+
+# Add the marketplace
+/plugin marketplace add ./.claude-plugin
+
+# Install the plugin
+/plugin install vizzly@vizzly-marketplace
+```
+
+## Features
+
+### 🔍 **TDD Status Checking**
+- `/vizzly:tdd-status` - Check current TDD status and comparison results
+- See failed/new/passed screenshot counts
+- Direct links to diff images and dashboard
+
+### 🐛 **Smart Diff Analysis**
+- `/vizzly:debug-diff <screenshot-name>` - Analyze visual regression failures
+- AI-powered analysis with contextual suggestions
+- Guidance on whether to accept or fix changes
+
+### 💡 **Screenshot Suggestions**
+- `/vizzly:suggest-screenshots` - Analyze test files for screenshot opportunities
+- Framework-specific code examples
+- Respect your test structure and patterns
+
+### ⚡ **Quick Setup**
+- `/vizzly:setup` - Initialize Vizzly configuration
+- Environment variable guidance
+- CI/CD integration help
+
+## MCP Server Tools
+
+The plugin provides an MCP server with direct access to Vizzly data:
+
+### Local TDD Tools
+- `detect_context` - Detect if using local TDD or cloud mode
+- `get_tdd_status` - Get current TDD comparison results
+- `read_comparison_details` - Detailed info for specific screenshot
+- `accept_baseline` - Accept a screenshot as new baseline
+- `reject_baseline` - Reject a baseline with reason
+
+### Cloud API Tools
+- `list_recent_builds` - List recent builds with filtering
+- `get_build_status` - Get build status with commit context
+- `get_comparison` - Get comparison details with screenshots
+- `approve_comparison` - Approve a comparison with comment
+- `reject_comparison` - Reject a comparison with reason
+- `create_build_comment` - Add comment to build
+
+## Authentication
+
+The plugin automatically uses your Vizzly authentication with the following priority:
+
+1. **Explicitly provided token** (via tool parameters)
+2. **Environment variable** (`VIZZLY_TOKEN`)
+3. **Project mapping** (configured via `vizzly project:select`)
+4. **User access token** (from `vizzly login`)
+
+### Getting Started
+
+**For local development:**
+```bash
+vizzly login                # Authenticate with your Vizzly account
+vizzly project:select       # Optional: set project-specific token
+```
+
+**For CI/CD:**
+```bash
+export VIZZLY_TOKEN=vzt_your_project_token
+```
+
+The plugin will automatically use the appropriate token based on your context.
+
+## Requirements
+
+- Claude Code
+- Node.js 20+
+- Vizzly CLI (`@vizzly-testing/cli`) installed in your project
+- TDD mode running for local features
+- Authentication configured (see above) for cloud features
+
+## Documentation
+
+- [Vizzly CLI](https://github.com/vizzly-testing/vizzly-cli) - Official CLI documentation
+- [Vizzly Platform](https://vizzly.dev) - Web dashboard and cloud features
+- [Claude Code](https://claude.com/claude-code) - Claude Code documentation
+
+## License
+
+MIT © Vizzly Team

package/.claude-plugin/commands/debug-diff.md

@@ -0,0 +1,153 @@
+---
+description: Analyze a specific visual regression failure and suggest fixes
+---
+
+# Debug Vizzly Visual Regression
+
+Analyze a specific failing visual comparison in detail. Supports both local TDD mode and cloud API mode.
+
+## Process
+
+1. **Call the unified MCP tool**: Use `read_comparison_details` with the identifier (screenshot name or comparison ID)
+   - The tool automatically detects whether to use local TDD mode or cloud mode
+   - Pass screenshot name (e.g., "homepage_desktop") for local mode
+   - Pass comparison ID (e.g., "cmp_abc123") for cloud mode
+   - Returns a response with `mode` field indicating which mode was used
+
+2. **Check the mode in the response**:
+   - **Local mode** (`mode: "local"`): Returns filesystem paths (`baselinePath`, `currentPath`, `diffPath`)
+   - **Cloud mode** (`mode: "cloud"`): Returns URLs (`baselineUrl`, `currentUrl`, `diffUrl`)
+
+3. **Analyze the comparison data**:
+   - Diff percentage and threshold
+   - Status (failed/new/passed)
+   - Image references (paths or URLs depending on mode)
+
+4. **View the actual images** (critical for visual analysis):
+
+   Check the `mode` field in the response to determine which tool to use:
+
+   **If mode is "local":**
+   - Response contains filesystem paths (`baselinePath`, `currentPath`, `diffPath`)
+   - **Use the Read tool to view ONLY baselinePath and currentPath**
+   - **DO NOT read diffPath** - it causes API errors
+
+   **If mode is "cloud":**
+   - Response contains public URLs (`baselineUrl`, `currentUrl`, `diffUrl`)
+   - **Use the WebFetch tool to view ONLY baselineUrl and currentUrl**
+   - **DO NOT fetch diffUrl** - it causes API errors
+
+   **IMPORTANT:** You MUST view the baseline and current images to provide accurate analysis
+
+5. **Provide detailed visual insights** based on what you see:
+   - What type of change was detected (small/moderate/large diff)
+   - Describe the specific visual differences you observe in the images
+   - Identify which UI components, elements, or layouts changed
+   - Possible causes based on diff percentage and visual inspection:
+     - <1%: Anti-aliasing, font rendering, subpixel differences
+     - 1-5%: Layout shifts, padding/margin changes, color variations
+     - > 5%: Significant layout changes, missing content, major visual updates
+
+6. **Suggest next steps** based on the mode:
+   - **If local mode**: Whether to accept using `accept_baseline` tool
+   - **If cloud mode**: Whether to approve/reject using `approve_comparison` or `reject_comparison` tools
+   - Areas to investigate if unintentional
+   - How to fix common issues
+   - Specific code changes if you can identify them from the visual diff
+
+## Example Analysis (Local TDD Mode)
+
+```
+Step 1: Call read_comparison_details with screenshot name
+Tool: read_comparison_details({ identifier: "homepage" })
+
+Response:
+{
+  "name": "homepage",
+  "status": "failed",
+  "diffPercentage": 2.3,
+  "threshold": 0.1,
+  "mode": "local",
+  "baselinePath": "/Users/you/project/.vizzly/baselines/homepage.png",
+  "currentPath": "/Users/you/project/.vizzly/screenshots/homepage.png",
+  "diffPath": "/Users/you/project/.vizzly/diffs/homepage.png"
+}
+
+Step 2: Detected mode is "local", so use Read tool for images
+Read(baselinePath) and Read(currentPath)
+
+Visual Analysis:
+[After reading the baseline and current image files...]
+
+Comparing the two images, the navigation header has shifted down by approximately 10-15 pixels.
+Specific changes observed:
+- The logo position moved from y:20px to y:35px
+- Navigation menu items are now overlapping with the hero section
+- The "Sign Up" button background changed from blue (#2563eb) to a darker blue (#1e40af)
+
+Root Cause:
+Based on the visual comparison, this appears to be a margin or padding change on the
+header element. The button color change is likely a hover state being captured.
+
+Recommendations:
+1. Check for recent CSS changes to:
+   - `.header` or `nav` margin-top/padding-top
+   - Any global layout shifts affecting the header
+2. The button color change suggests a hover state - ensure consistent state during screenshot capture
+3. If the header position change is intentional:
+   - Accept as new baseline using `accept_baseline` tool
+4. If unintentional:
+   - Revert CSS changes to header positioning
+   - Verify with: `git diff src/styles/header.css`
+```
+
+## Example Analysis (Cloud Mode)
+
+```
+Step 1: Call read_comparison_details with comparison ID
+Tool: read_comparison_details({
+  identifier: "cmp_xyz789",
+  apiToken: "vzt_..."
+})
+
+Response:
+{
+  "name": "homepage",
+  "status": "failed",
+  "diffPercentage": 2.3,
+  "threshold": 0.1,
+  "mode": "cloud",
+  "baselineUrl": "https://app.vizzly.dev/screenshots/abc123/baseline.png",
+  "currentUrl": "https://app.vizzly.dev/screenshots/abc123/current.png",
+  "diffUrl": "https://app.vizzly.dev/screenshots/abc123/diff.png",
+  "comparisonId": "cmp_xyz789",
+  "buildId": "bld_abc123"
+}
+
+Step 2: Detected mode is "cloud", so use WebFetch tool for images
+WebFetch(baselineUrl) and WebFetch(currentUrl)
+
+Visual Analysis:
+[After fetching the baseline and current image URLs...]
+
+[Same analysis as local mode example...]
+
+Recommendations:
+1. [Same technical recommendations as local mode...]
+2. If the header position change is intentional:
+   - Approve this comparison using `approve_comparison` tool
+3. If unintentional:
+   - Reject using `reject_comparison` tool with detailed reason
+   - Have the team fix the CSS changes
+```
+
+## Important Notes
+
+- **Unified Tool**: Always use `read_comparison_details` with the identifier - it automatically detects the mode
+- **Mode Detection**: Check the `mode` field in the response to know which viewing tool to use
+- **Image Viewing**:
+  - Local mode → Use Read tool with filesystem paths
+  - Cloud mode → Use WebFetch tool with URLs
+- **Diff Images**: NEVER attempt to view/read/fetch the diff image - it causes API errors
+- **Visual Analysis**: Always view the baseline and current images before providing analysis
+- Visual inspection reveals details that diff percentages alone cannot convey

package/.claude-plugin/commands/setup.md

@@ -0,0 +1,137 @@
+---
+description: Initialize Vizzly visual testing in a project
+---
+
+# Setup Vizzly in Project
+
+Help the user set up Vizzly visual regression testing in their project.
+
+## Setup Steps
+
+**Execute steps 1-5 to complete the CLI setup, then proceed to step 6 for SDK recommendations.**
+
+1. **Check if Vizzly is already configured**
+   - Look for `vizzly.config.js` in the project root
+   - Check if `@vizzly-testing/cli` is in package.json
+   - If already configured, inform the user and exit
+
+2. **Install Vizzly CLI**
+
+   Run this command:
+
+   ```bash
+   npm install --save-dev @vizzly-testing/cli
+   ```
+
+3. **Initialize configuration**
+
+   Run this command:
+
+   ```bash
+   npx vizzly init
+   ```
+
+   This creates `vizzly.config.js` with sensible defaults.
+
+4. **Add .vizzly/ to .gitignore**
+
+   Add `.vizzly/` to the project's `.gitignore` file to avoid committing local TDD artifacts.
+
+5. **Environment Variables**
+
+   Present the user with instructions to set up their API token:
+
+   **For local development:**
+   Create a `.env` file:
+
+   ```
+   VIZZLY_TOKEN=your-api-token-here
+   ```
+
+   Add `.env` to `.gitignore`
+
+   **For CI/CD:**
+   Add `VIZZLY_TOKEN` as a secret in their CI provider
+
+6. **Next Steps**
+
+   After CLI setup is complete, detect the project type and recommend the appropriate SDK:
+
+   **SDK Detection Priority (check in this order):**
+   - **Ruby**: Check for `Gemfile` → Recommend Ruby SDK
+   - **Storybook**: Check for `@storybook/*` in package.json or `.storybook/` directory → Recommend Storybook SDK
+   - **Static Site**: Check for static site generators (`astro`, `next`, `gatsby`, `vitepress`, `eleventy` in package.json) or build directories (`dist/`, `build/`, `.next/out/`, `_site/`) → Recommend Static Site SDK
+   - **JavaScript/Node.js**: Check for `package.json` → Recommend JavaScript SDK
+
+   **Present the detected SDK recommendation:**
+
+   For Ruby:
+
+   ```
+   📦 Next: Install the Ruby SDK
+   gem install vizzly
+
+   Documentation: https://docs.vizzly.dev/integration/sdk/ruby/overview
+   ```
+
+   For Storybook:
+
+   ```
+   📦 Next: Install the Storybook SDK
+   npm install --save-dev @vizzly-testing/storybook
+
+   Documentation: https://docs.vizzly.dev/integration/sdk/storybook/overview
+   ```
+
+   For Static Site:
+
+   ```
+   📦 Next: Install the Static Site SDK
+   npm install --save-dev @vizzly-testing/static-site
+
+   Documentation: https://docs.vizzly.dev/integration/sdk/static-site/overview
+   ```
+
+   For JavaScript:
+
+   ```
+   📦 Next: Use the JavaScript SDK (already included with the CLI)
+
+   Documentation: https://docs.vizzly.dev/integration/sdk/javascript/overview
+   ```
+
+   **End with this context summary:**
+
+   ```
+   ✅ Setup Complete
+
+   What was accomplished:
+   - Vizzly CLI installed
+   - Configuration file created (vizzly.config.js)
+   - .vizzly/ added to .gitignore
+   - Environment variable instructions provided
+
+   What's next:
+   - Install the recommended SDK (see above)
+   - Add screenshot capture to your tests (if needed)
+   - Run `vizzly tdd start` to test locally
+
+   [For Claude: The CLI is now installed and configured. When the user returns saying they installed the SDK, help them integrate it into their tests and start capturing screenshots. The workflow is: install SDK → add screenshot calls to tests → run vizzly tdd to verify locally.]
+   ```
+
+## What NOT to Do
+
+- Do not modify their test files
+- Do not generate example test code
+- Do not make assumptions about their test framework
+- Do not create new test files
+
+## What to Provide
+
+- Installation commands
+- Configuration file creation
+- Environment setup guidance
+- Links to documentation
+- Next steps for integration
+
+Let the user integrate Vizzly into their existing tests themselves. Vizzly works with any test framework that can capture screenshots.

package/.claude-plugin/commands/suggest-screenshots.md

@@ -0,0 +1,111 @@
+---
+description: Analyze test files and suggest where visual screenshots would be valuable
+---
+
+# Suggest Screenshot Opportunities
+
+Analyze existing test files to identify ideal locations for visual regression testing.
+
+## Process
+
+1. **Detect SDK type** (same logic as setup command)
+
+   **If Storybook detected** (`@storybook/*` in package.json or `.storybook/` directory):
+   - Inform user that Storybook SDK auto-discovers all stories
+   - No manual screenshot calls needed
+   - Exit early
+
+   **If Static Site detected** (build directories like `dist/`, `build/`, `.next/out/` or static site generators):
+   - Inform user that Static Site SDK auto-discovers all pages
+   - No manual screenshot calls needed
+   - Exit early
+
+   **Otherwise continue** with test file analysis below.
+
+2. **Ask user for test directory** if not obvious (e.g., `tests/`, `e2e/`, `__tests__/`, `spec/`)
+
+3. **Find test files** using glob patterns:
+   - `**/*.test.{js,ts,jsx,tsx}`
+   - `**/*.spec.{js,ts,jsx,tsx}`
+   - `**/e2e/**/*.{js,ts}`
+
+   **IMPORTANT: Exclude these directories:**
+   - `node_modules/`
+   - `dist/`, `build/`, `out/`
+   - `.next/`, `.nuxt/`, `.vite/`
+   - `coverage/`, `.nyc_output/`
+   - `vendor/`
+   - Any hidden directories (`.*/`)
+
+   Use the Glob tool with explicit exclusion or filter results to avoid these directories.
+
+4. **Analyze test files** looking for:
+   - Page navigations (`.goto()`, `.visit()`, `navigate()`)
+   - User interactions before assertions (`.click()`, `.type()`, `.fill()`)
+   - Component rendering (React Testing Library, etc.)
+   - Visual assertions or wait conditions
+
+5. **Suggest screenshot points** where:
+   - After page loads or navigations
+   - After key user interactions
+   - Before visual assertions
+   - At different viewport sizes
+   - For different user states (logged in/out, etc.)
+
+6. **Provide code examples** specific to their test framework:
+
+   **Playwright:**
+
+   ```javascript
+   import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
+
+   // After page navigation
+   await page.goto('/dashboard');
+   await vizzlyScreenshot('dashboard-logged-in', await page.screenshot(), {
+     browser: 'chrome',
+     viewport: '1920x1080'
+   });
+   ```
+
+   **Cypress:**
+
+   ```javascript
+   cy.visit('/login');
+   cy.screenshot('login-page');
+   // Then add vizzlyScreenshot in custom command
+   ```
+
+## Output Format
+
+```
+Found 8 potential screenshot opportunities in your tests:
+
+tests/e2e/auth.spec.js:
+  Line 15: After login page navigation
+    Suggested screenshot: 'login-page'
+    Reason: Page load after navigation
+
+  Line 28: After successful login
+    Suggested screenshot: 'dashboard-authenticated'
+    Reason: User state change (logged in)
+
+tests/e2e/checkout.spec.js:
+  Line 42: Shopping cart with items
+    Suggested screenshot: 'cart-with-items'
+    Reason: Visual state after user interaction
+
+  Line 67: Checkout confirmation page
+    Suggested screenshot: 'order-confirmation'
+    Reason: Final state of user flow
+
+Example integration for Playwright:
+[Provide code example specific to their test]
+```
+
+## Important Notes
+
+- **Do NOT modify test files**
+- **Do NOT create new test files**
+- Only provide suggestions and examples
+- Let the user decide where to add screenshots
+- Respect their test framework and structure

package/.claude-plugin/commands/tdd-status.md

@@ -0,0 +1,43 @@
+---
+description: Check TDD dashboard status and view visual regression test results
+---
+
+# Check Vizzly TDD Status
+
+Use the Vizzly MCP server to check the current TDD status:
+
+1. Call the `get_tdd_status` tool from the vizzly MCP server
+2. Analyze the comparison results
+3. Show a summary of:
+   - Total screenshots tested
+   - Passed, failed, and new screenshot counts
+   - List of failed comparisons with diff percentages
+   - Available diff images to inspect
+4. If TDD server is running, provide the dashboard URL
+5. For failed comparisons, provide guidance on next steps
+
+## Example Output Format
+
+```
+Vizzly TDD Status:
+✅ Total: 15 screenshots
+✅ Passed: 12
+❌ Failed: 2 (exceeded threshold)
+🆕 New: 1 (no baseline)
+
+Failed Comparisons:
+- homepage (2.3% diff) - Check .vizzly/diffs/homepage.png
+- login-form (1.8% diff) - Check .vizzly/diffs/login-form.png
+
+New Screenshots:
+- dashboard (no baseline for comparison)
+
+Dashboard: http://localhost:47392
+
+Next Steps:
+- Review diff images to understand what changed
+- Accept baselines from dashboard if changes are intentional
+- Fix visual issues if changes are unintentional
+```
+
+Focus on providing actionable information to help the developer understand what's failing and why.

package/.claude-plugin/marketplace.json

@@ -0,0 +1,28 @@
+{
+  "name": "vizzly-marketplace",
+  "owner": {
+    "name": "Vizzly Team",
+    "email": "team@vizzly.dev"
+  },
+  "metadata": {
+    "description": "Official Vizzly plugin for Claude Code - visual regression testing integration with TDD workflow support",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "vizzly",
+      "source": "./",
+      "description": "Visual regression testing integration for Vizzly - TDD workflow support and debugging tools",
+      "version": "0.1.0",
+      "author": {
+        "name": "Vizzly Team",
+        "url": "https://vizzly.dev"
+      },
+      "homepage": "https://vizzly.dev",
+      "repository": "https://github.com/vizzly-testing/vizzly-cli",
+      "license": "MIT",
+      "keywords": ["visual-testing", "regression-testing", "tdd", "screenshot-testing", "vizzly"],
+      "category": "testing"
+    }
+  ]
+}