From df890ca4c8c5e63eefcfce94ab47153e55899d95 Mon Sep 17 00:00:00 2001 From: Robert DeLuca Date: Thu, 5 Feb 2026 04:21:07 -0600 Subject: [PATCH 1/2] =?UTF-8?q?=E2=9C=A8=20Update=20Claude=20plugin=20to?= =?UTF-8?q?=20v0.3.0=20with=20full=20CLI=20support?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove MCP references - the plugin is now purely skills-based - Update CLI commands to match current Vizzly CLI structure - Add review commands: approve, reject, comment - Add cloud build commands: status, builds, comparisons - Add account commands: login, logout, whoami, orgs, projects - Add project commands: project:select, project:list, project:token - Update setup instructions to use project:select workflow - Add CLI Integration section to README --- .claude-plugin/marketplace.json | 4 +- vizzly-plugin/README.md | 8 +++ .../plugins/vizzly/.claude-plugin/plugin.json | 4 +- vizzly-plugin/plugins/vizzly/README.md | 16 +++--- .../plugins/vizzly/commands/setup.md | 8 +-- .../vizzly/skills/check-visual-tests/SKILL.md | 17 +++++-- .../skills/debug-visual-regression/SKILL.md | 11 ++-- .../vizzly/skills/vizzly-knowledge/SKILL.md | 51 +++++++++++++++++-- 8 files changed, 91 insertions(+), 28 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 6446bef..45bd99d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -10,8 +10,8 @@ "plugins": [ { "name": "vizzly", - "version": "0.2.0", - "description": "Visual regression testing with Vizzly - debug failures, check test status, and learn visual testing best practices", + "version": "0.3.0", + "description": "Visual regression testing with Vizzly - debug failures, check test status, review changes, and learn visual testing best practices", "source": "./vizzly-plugin/plugins/vizzly", "category": "testing" } diff --git a/vizzly-plugin/README.md b/vizzly-plugin/README.md index f8091db..1762108 100644 --- a/vizzly-plugin/README.md +++ b/vizzly-plugin/README.md @@ -35,6 +35,14 @@ Then restart Claude Code. - `/vizzly:setup` - Initialize Vizzly in a project - `/vizzly:suggest-screenshots` - Analyze tests and suggest where to add visual screenshots +### CLI Integration + +The plugin teaches Claude how to use the full Vizzly CLI: +- TDD commands: `vizzly tdd start`, `vizzly tdd run`, `vizzly baselines` +- Cloud commands: `vizzly run`, `vizzly status`, `vizzly builds` +- Review commands: `vizzly approve`, `vizzly reject`, `vizzly comment` +- Setup commands: `vizzly init`, `vizzly login`, `vizzly project:select` + ## Structure ``` diff --git a/vizzly-plugin/plugins/vizzly/.claude-plugin/plugin.json b/vizzly-plugin/plugins/vizzly/.claude-plugin/plugin.json index c6c130f..1afcf1b 100644 --- a/vizzly-plugin/plugins/vizzly/.claude-plugin/plugin.json +++ b/vizzly-plugin/plugins/vizzly/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "vizzly", - "description": "Visual regression testing with Vizzly - debug failures, check test status, and learn visual testing best practices", - "version": "0.2.0", + "description": "Visual regression testing with Vizzly - debug failures, check test status, review changes, and learn visual testing best practices", + "version": "0.3.0", "author": { "name": "Vizzly Team", "url": "https://vizzly.dev" diff --git a/vizzly-plugin/plugins/vizzly/README.md b/vizzly-plugin/plugins/vizzly/README.md index bdc1295..dce8956 100644 --- a/vizzly-plugin/plugins/vizzly/README.md +++ b/vizzly-plugin/plugins/vizzly/README.md @@ -88,14 +88,14 @@ The homepage screenshot is failing, can you help debug it? This plugin is **skills-first, not tools-first**. -Instead of complex MCP servers, the plugin teaches Claude: -- How to read `.vizzly/report-data.json` for test results -- How to view screenshot images with the Read tool -- How to run CLI commands like `vizzly tdd start` -- When and where to add visual tests -- Visual testing best practices - -Claude uses its built-in capabilities (Read, Bash, etc.) - the plugin just provides the knowledge. +The plugin teaches Claude how to work with Vizzly: +- Read `.vizzly/report-data.json` for test results +- View screenshot images with the Read tool +- Run CLI commands like `vizzly tdd start` +- Review and approve visual changes via the CLI +- Understand visual testing best practices + +Claude uses its built-in capabilities (Read, Bash, etc.) combined with the Vizzly CLI - the plugin provides the knowledge to use them effectively. --- diff --git a/vizzly-plugin/plugins/vizzly/commands/setup.md b/vizzly-plugin/plugins/vizzly/commands/setup.md index cc8318e..c5cd08b 100644 --- a/vizzly-plugin/plugins/vizzly/commands/setup.md +++ b/vizzly-plugin/plugins/vizzly/commands/setup.md @@ -100,16 +100,18 @@ Check the project to determine which SDK to recommend: For local TDD mode, no token is needed! Just run: vizzly tdd start -For cloud features, create a .env file: -VIZZLY_TOKEN=your-api-token-here +For cloud features, authenticate with your account: +vizzly login -Add .env to .gitignore +Then select a project for your directory: +vizzly project:select ``` **For CI/CD:** ``` Add VIZZLY_TOKEN as a secret in your CI provider. +Get your project token with: vizzly project:token Example GitHub Actions: env: diff --git a/vizzly-plugin/plugins/vizzly/skills/check-visual-tests/SKILL.md b/vizzly-plugin/plugins/vizzly/skills/check-visual-tests/SKILL.md index f66d739..f2e8426 100644 --- a/vizzly-plugin/plugins/vizzly/skills/check-visual-tests/SKILL.md +++ b/vizzly-plugin/plugins/vizzly/skills/check-visual-tests/SKILL.md @@ -134,15 +134,24 @@ The TDD server doesn't appear to be running. To start visual testing: http://localhost:47392 ``` -## Alternative: CLI Status Command +## Alternative: CLI Status Commands -You can also run the CLI command to get status: +You can also run CLI commands to get status: +**For local TDD:** ```bash -vizzly tdd status +vizzly tdd status # Show current test status +vizzly baselines # List and query baselines ``` -This shows the same information in the terminal. +**For cloud builds:** +```bash +vizzly status # Check specific build status +vizzly builds # List recent builds +vizzly comparisons # Query and search comparisons +``` + +These commands show the same information in the terminal. ## Example Full Response diff --git a/vizzly-plugin/plugins/vizzly/skills/debug-visual-regression/SKILL.md b/vizzly-plugin/plugins/vizzly/skills/debug-visual-regression/SKILL.md index 284e67f..e9969c2 100644 --- a/vizzly-plugin/plugins/vizzly/skills/debug-visual-regression/SKILL.md +++ b/vizzly-plugin/plugins/vizzly/skills/debug-visual-regression/SKILL.md @@ -94,8 +94,9 @@ Based on what you observe, suggest likely causes: **If the change is intentional:** Explain that they can accept the new baseline: -- Via the dashboard at `http://localhost:47392` -- Or by copying the file: `cp .vizzly/current/.png .vizzly/baselines/.png` +- Via the TDD dashboard at `http://localhost:47392` +- Via CLI: `vizzly approve ` (for cloud builds) +- Or by copying the file: `cp .vizzly/current/.png .vizzly/baselines/.png` (local TDD) **If the change is unintentional:** Help them investigate: @@ -133,8 +134,10 @@ Check recent changes to header styles: Run: `git diff HEAD~3 -- "*.css" | grep -A5 -B5 "header\|nav"` **If intentional:** -Accept the new baseline via the dashboard or run: -`cp .vizzly/current/homepage.png .vizzly/baselines/homepage.png` +Accept the new baseline: +- TDD dashboard at `http://localhost:47392` +- Cloud build: `vizzly approve ` +- Local TDD: `cp .vizzly/current/homepage.png .vizzly/baselines/homepage.png` ``` ## When TDD Server Isn't Running diff --git a/vizzly-plugin/plugins/vizzly/skills/vizzly-knowledge/SKILL.md b/vizzly-plugin/plugins/vizzly/skills/vizzly-knowledge/SKILL.md index 983cab1..4db87ae 100644 --- a/vizzly-plugin/plugins/vizzly/skills/vizzly-knowledge/SKILL.md +++ b/vizzly-plugin/plugins/vizzly/skills/vizzly-knowledge/SKILL.md @@ -71,26 +71,61 @@ This is the primary source of truth for test results. Read it to understand test ## CLI Commands -**TDD Mode:** +**TDD Mode (Local Development):** ```bash vizzly tdd start # Start TDD server (background) vizzly tdd run "npm test" # Run tests with ephemeral server vizzly tdd status # Show current test status vizzly tdd stop # Stop the TDD server +vizzly baselines # List and query local baselines ``` -**Cloud Mode:** +**Cloud Mode (CI/CD):** ```bash vizzly run "npm test" # Run tests and upload to cloud vizzly run "npm test" --wait # Wait for cloud processing +vizzly status # Check build status +vizzly builds # List and query builds vizzly finalize # Finalize parallel builds +vizzly comparisons # Query and search comparisons +``` + +**Review Commands (approve/reject visual changes):** +```bash +vizzly approve # Approve a comparison +vizzly reject # Reject a comparison +vizzly comment "msg" # Add a comment to a build ``` **Project Setup:** ```bash vizzly init # Create vizzly.config.js +vizzly config # Display current configuration +vizzly doctor # Run diagnostics to check environment +``` + +**Account & Authentication:** +```bash vizzly login # Authenticate with Vizzly cloud -vizzly project link # Link to a cloud project +vizzly logout # Clear stored authentication tokens +vizzly whoami # Show current auth status +vizzly orgs # List organizations you have access to +vizzly projects # List projects you have access to +``` + +**Project Configuration:** +```bash +vizzly project:select # Configure project for current directory +vizzly project:list # Show all configured projects +vizzly project:token # Show project token for current directory +vizzly project:remove # Remove project configuration +``` + +**Advanced:** +```bash +vizzly api # Make raw API requests +vizzly upload # Upload screenshots directly +vizzly preview # Upload static files as preview ``` ## Taking Screenshots in Tests @@ -113,12 +148,18 @@ await vizzlyScreenshot('homepage', await page.screenshot(), { When a screenshot changes intentionally, you need to accept it as the new baseline: -**Via Dashboard:** +**Via TDD Dashboard (Local):** 1. Open `http://localhost:47392` 2. Review the visual diff 3. Click "Accept" on screenshots you want to update -**Via File Operations:** +**Via CLI (Cloud builds):** +```bash +vizzly approve # Approve a specific comparison +vizzly reject # Reject a specific comparison +``` + +**Via File Operations (Local TDD):** Copy the current screenshot to baselines: ```bash cp .vizzly/current/homepage.png .vizzly/baselines/homepage.png From 2d724e0b99c3ee2bf39e44a173050b00eee5b8aa Mon Sep 17 00:00:00 2001 From: Robert DeLuca Date: Thu, 5 Feb 2026 04:36:50 -0600 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=93=9D=20Address=20PR=20feedback=20on?= =?UTF-8?q?=20CLI=20command=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix reject command syntax: -r/--reason flag is required - Add context for when to use local vs cloud commands - Show how to find comparison IDs with vizzly comparisons -b - Use short flags (-r, -m, -b) matching CLI conventions - Add comparisons filtering examples (--name, --status) --- .../vizzly/skills/check-visual-tests/SKILL.md | 8 ++++---- .../vizzly/skills/debug-visual-regression/SKILL.md | 6 +++--- .../vizzly/skills/vizzly-knowledge/SKILL.md | 14 +++++++++----- 3 files changed, 16 insertions(+), 12 deletions(-) diff --git a/vizzly-plugin/plugins/vizzly/skills/check-visual-tests/SKILL.md b/vizzly-plugin/plugins/vizzly/skills/check-visual-tests/SKILL.md index f2e8426..2518ed7 100644 --- a/vizzly-plugin/plugins/vizzly/skills/check-visual-tests/SKILL.md +++ b/vizzly-plugin/plugins/vizzly/skills/check-visual-tests/SKILL.md @@ -138,16 +138,16 @@ The TDD server doesn't appear to be running. To start visual testing: You can also run CLI commands to get status: -**For local TDD:** +**For local TDD:** (use when running `vizzly tdd start`) ```bash vizzly tdd status # Show current test status vizzly baselines # List and query baselines ``` -**For cloud builds:** +**For cloud builds:** (use when running `vizzly run` in CI) ```bash -vizzly status # Check specific build status -vizzly builds # List recent builds +vizzly status # Check specific build status (build ID from CI output) +vizzly builds # List recent builds to find build IDs vizzly comparisons # Query and search comparisons ``` diff --git a/vizzly-plugin/plugins/vizzly/skills/debug-visual-regression/SKILL.md b/vizzly-plugin/plugins/vizzly/skills/debug-visual-regression/SKILL.md index e9969c2..5075ba4 100644 --- a/vizzly-plugin/plugins/vizzly/skills/debug-visual-regression/SKILL.md +++ b/vizzly-plugin/plugins/vizzly/skills/debug-visual-regression/SKILL.md @@ -95,8 +95,8 @@ Based on what you observe, suggest likely causes: **If the change is intentional:** Explain that they can accept the new baseline: - Via the TDD dashboard at `http://localhost:47392` -- Via CLI: `vizzly approve ` (for cloud builds) -- Or by copying the file: `cp .vizzly/current/.png .vizzly/baselines/.png` (local TDD) +- Via CLI (cloud): `vizzly comparisons -b ` to find ID, then `vizzly approve ` +- Via file copy (local TDD): `cp .vizzly/current/.png .vizzly/baselines/.png` **If the change is unintentional:** Help them investigate: @@ -136,7 +136,7 @@ Run: `git diff HEAD~3 -- "*.css" | grep -A5 -B5 "header\|nav"` **If intentional:** Accept the new baseline: - TDD dashboard at `http://localhost:47392` -- Cloud build: `vizzly approve ` +- Cloud: `vizzly comparisons -b ` → `vizzly approve ` - Local TDD: `cp .vizzly/current/homepage.png .vizzly/baselines/homepage.png` ``` diff --git a/vizzly-plugin/plugins/vizzly/skills/vizzly-knowledge/SKILL.md b/vizzly-plugin/plugins/vizzly/skills/vizzly-knowledge/SKILL.md index 4db87ae..527347b 100644 --- a/vizzly-plugin/plugins/vizzly/skills/vizzly-knowledge/SKILL.md +++ b/vizzly-plugin/plugins/vizzly/skills/vizzly-knowledge/SKILL.md @@ -92,9 +92,12 @@ vizzly comparisons # Query and search comparisons **Review Commands (approve/reject visual changes):** ```bash -vizzly approve # Approve a comparison -vizzly reject # Reject a comparison -vizzly comment "msg" # Add a comment to a build +vizzly comparisons -b # List comparisons for a build +vizzly comparisons --name "Button*" --status changed # Search by name/status +vizzly approve # Approve a comparison +vizzly approve -m "LGTM" # Approve with comment +vizzly reject -r "reason" # Reject (reason required) +vizzly comment "message" # Add comment to a build ``` **Project Setup:** @@ -155,8 +158,9 @@ When a screenshot changes intentionally, you need to accept it as the new baseli **Via CLI (Cloud builds):** ```bash -vizzly approve # Approve a specific comparison -vizzly reject # Reject a specific comparison +vizzly comparisons -b # List comparisons for a build +vizzly approve # Approve a comparison +vizzly reject -r "reason" # Reject (reason required) ``` **Via File Operations (Local TDD):**