@vizzly-testing/cli 0.23.1 → 0.24.0

package/claude-plugin/skills/check-visual-tests/SKILL.md

@@ -1,158 +0,0 @@
----
-name: Check Visual Test Status
-description: Check the status of Vizzly visual regression tests. Use when the user asks about test status, test results, what's failing, how tests are doing, or wants a summary of visual tests. Works with both local TDD and cloud modes.
-allowed-tools: mcp__plugin_vizzly_vizzly__get_tdd_status, mcp__plugin_vizzly_vizzly__detect_context
----
-
-# Check Visual Test Status
-
-Automatically check Vizzly visual test status when the user asks about their tests. Provides a quick summary of passed, failed, and new screenshots.
-
-## When to Use This Skill
-
-Activate this Skill when the user:
-- Asks "How are my tests doing?"
-- Asks "Are there any failing tests?"
-- Asks "What's the status of visual tests?"
-- Asks "Show me test results"
-- Asks "What's failing?"
-- Wants a summary of visual regression tests
-
-## How This Skill Works
-
-1. **Detect context** (local TDD or cloud mode)
-2. **Fetch TDD status** from the local server
-3. **Analyze results** to identify failures, new screenshots, and passes
-4. **Provide summary** with actionable information
-5. **Link to dashboard** for detailed review
-
-## Instructions
-
-### Step 1: Get TDD Status
-
-Use the `get_tdd_status` tool from the Vizzly MCP server to fetch current comparison results.
-
-This returns:
-- Total screenshot count
-- Passed, failed, and new screenshot counts
-- List of all comparisons with details
-- Dashboard URL (if TDD server is running)
-
-### Step 2: Analyze the Results
-
-Examine the comparison data:
-- Count total, passed, failed, and new screenshots
-- Identify which specific screenshots failed
-- Note diff percentages for failures
-- Check if new screenshots need baselines
-
-### Step 3: Provide Clear Summary
-
-Format the output to be scannable and actionable:
-
-```
-Vizzly TDD Status:
-✅ Total: [count] screenshots
-✅ Passed: [count]
-❌ Failed: [count] (exceeded threshold)
-🆕 New: [count] (no baseline)
-
-Failed Comparisons:
-- [name] ([diff]% diff) - Exceeds [threshold]% threshold
-- [name] ([diff]% diff) - Exceeds [threshold]% threshold
-
-New Screenshots:
-- [name] (no baseline for comparison)
-
-Dashboard: http://localhost:47392
-```
-
-### Step 4: Suggest Next Steps
-
-Based on the results, provide guidance:
-
-**If there are failures:**
-- Suggest using the debug-visual-regression Skill for detailed analysis
-- Provide dashboard link for visual review
-- Mention accept/reject options
-
-**If there are new screenshots:**
-- Explain that new screenshots need baseline approval
-- Show how to accept them from dashboard or CLI
-
-**If all passed:**
-- Confirm tests are passing
-- No action needed
-
-## Example Output
-
-```
-User: "How are my tests?"
-
-Vizzly TDD Status:
-✅ Total: 15 screenshots
-✅ Passed: 12
-❌ Failed: 2 (exceeded threshold)
-🆕 New: 1 (no baseline)
-
-Failed Comparisons:
-- homepage (2.3% diff) - Exceeds 0.1% threshold
-  Check .vizzly/diffs/homepage.png
-- login-form (1.8% diff) - Exceeds 0.1% threshold
-  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
-- For detailed analysis of failures, ask me to debug specific screenshots
-- Fix visual issues if changes are unintentional
-```
-
-## Example When All Pass
-
-```
-User: "Are my visual tests passing?"
-
-Vizzly TDD Status:
-✅ Total: 15 screenshots
-✅ All passed!
-
-No visual regressions detected. All screenshots match their baselines.
-
-Dashboard: http://localhost:47392
-```
-
-## Example When TDD Not Running
-
-```
-User: "How are my tests?"
-
-Vizzly TDD Status:
-❌ TDD server is not running
-
-To start TDD mode:
-  vizzly tdd start
-
-Then run your tests to capture screenshots.
-```
-
-## Important Notes
-
-- **Quick status check** - Designed for fast overview, not detailed analysis
-- **Use dashboard for visuals** - Link to dashboard for image review
-- **Suggest next steps** - Always provide actionable guidance
-- **Detect TDD mode** - Only works with local TDD server running
-- **For detailed debugging** - Suggest using debug-visual-regression Skill
-
-## Focus on Actionability
-
-Always end with clear next steps:
-- What to investigate
-- Which tools to use (dashboard, debug Skill)
-- How to accept/reject baselines
-- When to fix code vs accept changes

package/claude-plugin/skills/debug-visual-regression/SKILL.md

@@ -1,269 +0,0 @@
----
-name: Debug Visual Regression
-description: Analyze visual regression test failures in Vizzly. Use when the user mentions failing visual tests, screenshot differences, visual bugs, diffs, or asks to debug/investigate/analyze visual changes. Works with both local TDD and cloud modes.
-allowed-tools: Read, WebFetch, mcp__plugin_vizzly_vizzly__read_comparison_details, mcp__plugin_vizzly_vizzly__search_comparisons, mcp__plugin_vizzly_vizzly__accept_baseline, mcp__plugin_vizzly_vizzly__approve_comparison, mcp__plugin_vizzly_vizzly__reject_comparison
----
-
-# Debug Visual Regression
-
-Automatically analyze visual regression failures when the user mentions them. This Skill helps identify the root cause of visual differences and suggests whether to accept or fix changes.
-
-## When to Use This Skill
-
-Activate this Skill when the user:
-- Mentions "failing visual test" or "screenshot failure"
-- Asks "what's wrong with my visual tests?"
-- Says "the homepage screenshot is different" or similar
-- Wants to understand why a visual comparison failed
-- Asks to "debug", "analyze", or "investigate" visual changes
-- Mentions specific screenshot names that are failing
-
-## How This Skill Works
-
-1. **Automatically detect the mode** (local TDD or cloud)
-2. **Fetch comparison details** using the screenshot name or comparison ID
-3. **View the actual images** to perform visual analysis
-4. **Provide detailed insights** on what changed and why
-5. **Suggest next steps** (accept, reject, or fix)
-
-## Instructions
-
-### Step 1: Call the Unified MCP Tool
-
-Use `read_comparison_details` with the identifier:
-- Pass screenshot name (e.g., "homepage_desktop") for local mode
-- Pass comparison ID (e.g., "cmp_abc123") for cloud mode
-- The tool automatically detects which mode to use
-- Returns a response with `mode` field indicating local or cloud
-
-### Step 2: Check the Mode in Response
-
-The response will contain a `mode` field:
-- **Local mode** (`mode: "local"`): Returns filesystem paths (`baselinePath`, `currentPath`, `diffPath`)
-- **Cloud mode** (`mode: "cloud"`): Returns URLs (`baselineUrl`, `currentUrl`, `diffUrl`)
-
-### Step 3: Analyze Comparison Data
-
-Examine the comparison details:
-- Diff percentage and threshold
-- Status (failed/new/passed)
-- Image references (paths or URLs depending on mode)
-- Viewport and browser information
-
-### Step 4: View the Actual Images
-
-**CRITICAL:** You MUST view the baseline and current images to provide accurate analysis.
-
-**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
-
-### Step 5: Provide Detailed Visual Insights
-
-Based on what you observe in the images:
-
-**Describe the specific visual differences:**
-- Which UI components, elements, or layouts changed
-- Colors, spacing, typography, positioning changes
-- Missing or added elements
-
-**Categorize the change by diff percentage:**
-- **< 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
-
-**Identify possible causes:**
-- CSS changes (margin, padding, positioning)
-- Content changes (text, images)
-- State issues (hover, focus, loading states)
-- Browser/viewport rendering differences
-
-### Step 6: Suggest Next Steps
-
-**If local mode:**
-- Whether to accept using `accept_baseline` tool
-- Specific code areas to investigate if unintentional
-- How to fix common issues
-
-**If cloud mode:**
-- Whether to approve using `approve_comparison` tool
-- Whether to reject using `reject_comparison` tool with reason
-- Team coordination steps
-
-**If changes are intentional:**
-- Explain why it's safe to accept/approve
-- Confirm this matches expected behavior
-
-**If changes are unintentional:**
-- Specific files to check (CSS, templates, components)
-- Git commands to investigate recent changes
-- How to reproduce and fix
-
-## Example Analysis (Local TDD Mode)
-
-```
-User: "The homepage screenshot is failing"
-
-Step 1: Call tool
-Tool: read_comparison_details({ identifier: "homepage" })
-
-Response:
-{
-  "name": "homepage",
-  "status": "failed",
-  "diffPercentage": 2.3,
-  "threshold": 2.0,
-  "mode": "local",
-  "baselinePath": "/Users/you/project/.vizzly/baselines/homepage.png",
-  "currentPath": "/Users/you/project/.vizzly/screenshots/homepage.png"
-}
-
-Step 2: View images
-Read(baselinePath)
-Read(currentPath)
-
-Step 3: Visual Analysis
-Comparing the two images, I can see the following changes:
-
-Visual Differences:
-- The navigation header has shifted down by approximately 10-15 pixels
-- 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 darker blue (#1e40af)
-
-Root Cause Analysis:
-Based on the 2.3% diff and visual comparison, this appears to be:
-1. A margin or padding change on the header element
-2. The button color change suggests a hover state being captured
-
-Recommendations:
-If intentional:
-- This appears to be a deliberate redesign of the header spacing
-- Accept as new baseline if these changes match your design updates
-
-If unintentional:
-- Check recent CSS changes to `.header` or `nav` margin-top/padding-top
-- Verify button states during screenshot capture to avoid hover state
-- Investigate with: `git diff src/styles/header.css`
-- Fix the header positioning and re-run tests
-```
-
-## Example Analysis (Cloud Mode)
-
-```
-User: "Can you check comparison cmp_xyz789?"
-
-Step 1: Call tool
-Tool: read_comparison_details({
-  identifier: "cmp_xyz789",
-  apiToken: "vzt_..."
-})
-
-Response:
-{
-  "name": "login-page",
-  "status": "failed",
-  "diffPercentage": 0.8,
-  "threshold": 2.0,
-  "mode": "cloud",
-  "baselineUrl": "https://app.vizzly.dev/screenshots/abc123/baseline.png",
-  "currentUrl": "https://app.vizzly.dev/screenshots/abc123/current.png",
-  "comparisonId": "cmp_xyz789"
-}
-
-Step 2: View images
-WebFetch(baselineUrl, "show me the baseline screenshot")
-WebFetch(currentUrl, "show me the current screenshot")
-
-Step 3: Visual Analysis
-The differences are very subtle (0.8% diff):
-
-Visual Differences:
-- Input field border color slightly different (#e5e7eb vs #d1d5db)
-- Submit button has very slight shadow change
-- Font anti-aliasing appears slightly different
-
-Root Cause Analysis:
-This appears to be browser rendering differences or minor CSS updates:
-- The 0.8% diff suggests this is not a major visual change
-- Could be Chrome version differences
-- Could be sub-pixel rendering variations
-
-Recommendations:
-This is likely acceptable to approve:
-- The changes are extremely minor (< 1%)
-- No functional UI changes
-- Probably browser/rendering variations
-
-Approve with: approve_comparison tool
-Or adjust threshold to 1% if these variations are expected
-```
-
-## Cross-Build Debugging (Cloud Only)
-
-When debugging visual regressions in cloud mode, you can track a screenshot across multiple builds to identify when changes were introduced.
-
-### When to Use Search
-
-Use `search_comparisons` when:
-- The user asks "when did this screenshot start failing?"
-- They want to track a visual change across builds
-- They're investigating a regression that appeared recently
-- They want to see the history of a specific screenshot
-
-### How to Search
-
-```javascript
-// Search for all comparisons of a screenshot
-search_comparisons({
-  name: "homepage_desktop",
-  branch: "main",  // optional: filter by branch
-  limit: 10        // optional: limit results
-})
-```
-
-### Example Workflow
-
-```
-User: "When did the homepage screenshot start failing?"
-
-Step 1: Search for the screenshot across builds
-Tool: search_comparisons({ name: "homepage", branch: "main", limit: 10 })
-
-Response shows 10 comparisons from most recent to oldest, each with:
-- Build name, branch, and creation date
-- Diff percentage and status
-- Screenshot URLs
-
-Step 2: Analyze the timeline
-- Build #45 (today): 5.2% diff - FAILED
-- Build #44 (yesterday): 5.1% diff - FAILED
-- Build #43 (2 days ago): 0.3% diff - PASSED
-- Build #42 (3 days ago): 0.2% diff - PASSED
-
-Step 3: Report findings
-"The homepage screenshot started failing between Build #43 and #44
-(approximately 1-2 days ago). The diff jumped from 0.3% to 5.1%,
-suggesting a significant visual change was introduced."
-
-Step 4: Deep dive into the failing build
-Tool: read_comparison_details({ identifier: "cmp_xyz_from_build44" })
-[View images and provide detailed analysis as usual]
-```
-
-## Important Notes
-
-- **Always use `read_comparison_details`** - it automatically detects the mode
-- **Use `search_comparisons` for cloud debugging** - to track changes across builds
-- **Check the `mode` field** to know which viewing tool to use (Read vs WebFetch)
-- **Never view diff images** - only baseline and current
-- **Visual inspection is critical** - don't rely solely on diff percentages
-- **Be specific in analysis** - identify exact elements that changed
-- **Provide actionable advice** - specific files, commands, or tools to use
-- **Consider context** - small diffs might be acceptable, large ones need investigation