@vizzly-testing/cli 0.10.3 → 0.11.1

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/mcp/vizzly-server/cloud-api-provider.js

@@ -0,0 +1,354 @@
+/**
+ * Provider for Vizzly Cloud API integration
+ */
+export class CloudAPIProvider {
+  constructor() {
+    this.defaultApiUrl = process.env.VIZZLY_API_URL || 'https://app.vizzly.dev';
+  }
+
+  /**
+   * Make API request to Vizzly
+   */
+  async makeRequest(path, apiToken, apiUrl = this.defaultApiUrl) {
+    if (!apiToken) {
+      throw new Error(
+        'API token required. Set VIZZLY_TOKEN environment variable or provide via apiToken parameter.'
+      );
+    }
+
+    let url = `${apiUrl}${path}`;
+    let response = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${apiToken}`,
+        'User-Agent': 'Vizzly-Claude-Plugin/0.1.0'
+      }
+    });
+
+    if (!response.ok) {
+      let error = await response.text();
+      throw new Error(`API request failed (${response.status}): ${error}`);
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Get build status and details
+   */
+  async getBuildStatus(buildId, apiToken, apiUrl) {
+    if (!buildId || typeof buildId !== 'string') {
+      throw new Error('buildId is required and must be a non-empty string');
+    }
+
+    let data = await this.makeRequest(
+      `/api/sdk/builds/${buildId}?include=comparisons`,
+      apiToken,
+      apiUrl
+    );
+
+    let { build } = data;
+
+    // Calculate comparison summary
+    let comparisons = build.comparisons || [];
+    let summary = {
+      total: comparisons.length,
+      new: comparisons.filter((c) => c.status === 'new').length,
+      changed: comparisons.filter((c) => c.has_diff).length,
+      identical: comparisons.filter((c) => !c.has_diff && c.status !== 'new').length
+    };
+
+    // Group comparisons by status
+    let failedComparisons = comparisons
+      .filter((c) => c.has_diff)
+      .map((c) => ({
+        name: c.name,
+        diffPercentage: c.diff_percentage,
+        currentUrl: c.current_screenshot?.original_url,
+        baselineUrl: c.baseline_screenshot?.original_url,
+        diffUrl: c.diff_image?.url
+      }));
+
+    let newComparisons = comparisons
+      .filter((c) => c.status === 'new')
+      .map((c) => ({
+        name: c.name,
+        currentUrl: c.current_screenshot?.original_url
+      }));
+
+    return {
+      build: {
+        id: build.id,
+        name: build.name,
+        branch: build.branch,
+        status: build.status,
+        url: build.url,
+        organizationSlug: build.organizationSlug,
+        projectSlug: build.projectSlug,
+        createdAt: build.created_at,
+        // Include commit details for debugging
+        commitSha: build.commit_sha,
+        commitMessage: build.commit_message,
+        commonAncestorSha: build.common_ancestor_sha
+      },
+      summary,
+      failedComparisons,
+      newComparisons
+    };
+  }
+
+  /**
+   * List recent builds
+   */
+  async listRecentBuilds(apiToken, options = {}) {
+    let { limit = 10, branch, apiUrl } = options;
+
+    let queryParams = new URLSearchParams({
+      limit: limit.toString()
+    });
+
+    if (branch) {
+      queryParams.append('branch', branch);
+    }
+
+    let data = await this.makeRequest(`/api/sdk/builds?${queryParams}`, apiToken, apiUrl);
+
+    return {
+      builds: data.builds.map((b) => ({
+        id: b.id,
+        name: b.name,
+        branch: b.branch,
+        status: b.status,
+        environment: b.environment,
+        createdAt: b.created_at
+      })),
+      pagination: data.pagination
+    };
+  }
+
+  /**
+   * Get token context (organization and project info)
+   */
+  async getTokenContext(apiToken, apiUrl) {
+    return await this.makeRequest('/api/sdk/token/context', apiToken, apiUrl);
+  }
+
+  /**
+   * Get comparison details
+   */
+  async getComparison(comparisonId, apiToken, apiUrl) {
+    if (!comparisonId || typeof comparisonId !== 'string') {
+      throw new Error('comparisonId is required and must be a non-empty string');
+    }
+
+    let data = await this.makeRequest(`/api/sdk/comparisons/${comparisonId}`, apiToken, apiUrl);
+
+    return data.comparison;
+  }
+
+  // ==================================================================
+  // BUILD COMMENTS
+  // ==================================================================
+
+  /**
+   * Create a comment on a build
+   */
+  async createBuildComment(buildId, content, type, apiToken, apiUrl) {
+    if (!buildId || typeof buildId !== 'string') {
+      throw new Error('buildId is required and must be a non-empty string');
+    }
+    if (!content || typeof content !== 'string') {
+      throw new Error('content is required and must be a non-empty string');
+    }
+
+    let url = `${apiUrl || this.defaultApiUrl}/api/sdk/builds/${buildId}/comments`;
+    let response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${apiToken}`,
+        'User-Agent': 'Vizzly-Claude-Plugin/0.1.0',
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({ content, type })
+    });
+
+    if (!response.ok) {
+      let error = await response.text();
+      throw new Error(`Failed to create comment (${response.status}): ${error}`);
+    }
+
+    return response.json();
+  }
+
+  /**
+   * List comments for a build
+   */
+  async listBuildComments(buildId, apiToken, apiUrl) {
+    if (!buildId || typeof buildId !== 'string') {
+      throw new Error('buildId is required and must be a non-empty string');
+    }
+
+    let data = await this.makeRequest(`/api/sdk/builds/${buildId}/comments`, apiToken, apiUrl);
+
+    // Filter out unnecessary fields from comments for MCP
+    let filterComment = (comment) => {
+      // eslint-disable-next-line no-unused-vars
+      let { profile_photo_url, email, ...filtered } = comment;
+      // Recursively filter replies if they exist
+      if (filtered.replies && Array.isArray(filtered.replies)) {
+        filtered.replies = filtered.replies.map(filterComment);
+      }
+      return filtered;
+    };
+
+    return {
+      ...data,
+      comments: data.comments ? data.comments.map(filterComment) : []
+    };
+  }
+
+  // ==================================================================
+  // COMPARISON APPROVALS
+  // ==================================================================
+
+  /**
+   * Approve a comparison
+   */
+  async approveComparison(comparisonId, comment, apiToken, apiUrl) {
+    if (!comparisonId || typeof comparisonId !== 'string') {
+      throw new Error('comparisonId is required and must be a non-empty string');
+    }
+
+    let url = `${apiUrl || this.defaultApiUrl}/api/sdk/comparisons/${comparisonId}/approve`;
+    let response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${apiToken}`,
+        'User-Agent': 'Vizzly-Claude-Plugin/0.1.0',
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({ comment })
+    });
+
+    if (!response.ok) {
+      let error = await response.text();
+      throw new Error(`Failed to approve comparison (${response.status}): ${error}`);
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Reject a comparison
+   */
+  async rejectComparison(comparisonId, reason, apiToken, apiUrl) {
+    if (!comparisonId || typeof comparisonId !== 'string') {
+      throw new Error('comparisonId is required and must be a non-empty string');
+    }
+    if (!reason || typeof reason !== 'string') {
+      throw new Error('reason is required and must be a non-empty string');
+    }
+
+    let url = `${apiUrl || this.defaultApiUrl}/api/sdk/comparisons/${comparisonId}/reject`;
+    let response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${apiToken}`,
+        'User-Agent': 'Vizzly-Claude-Plugin/0.1.0',
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({ reason })
+    });
+
+    if (!response.ok) {
+      let error = await response.text();
+      throw new Error(`Failed to reject comparison (${response.status}): ${error}`);
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Update comparison approval status
+   */
+  async updateComparisonApproval(comparisonId, approvalStatus, comment, apiToken, apiUrl) {
+    let url = `${apiUrl || this.defaultApiUrl}/api/sdk/comparisons/${comparisonId}/approval`;
+    let response = await fetch(url, {
+      method: 'PUT',
+      headers: {
+        Authorization: `Bearer ${apiToken}`,
+        'User-Agent': 'Vizzly-Claude-Plugin/0.1.0',
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({ approval_status: approvalStatus, comment })
+    });
+
+    if (!response.ok) {
+      let error = await response.text();
+      throw new Error(`Failed to update comparison approval (${response.status}): ${error}`);
+    }
+
+    return response.json();
+  }
+
+  // ==================================================================
+  // REVIEW STATUS
+  // ==================================================================
+
+  /**
+   * Get review summary for a build
+   */
+  async getReviewSummary(buildId, apiToken, apiUrl) {
+    if (!buildId || typeof buildId !== 'string') {
+      throw new Error('buildId is required and must be a non-empty string');
+    }
+
+    let data = await this.makeRequest(
+      `/api/sdk/builds/${buildId}/review-summary`,
+      apiToken,
+      apiUrl
+    );
+
+    return data;
+  }
+
+  // ==================================================================
+  // TDD WORKFLOW
+  // ==================================================================
+
+  /**
+   * Download baseline screenshots from a cloud build
+   * Returns screenshot data that can be saved locally
+   */
+  async downloadBaselines(buildId, screenshotNames, apiToken, apiUrl) {
+    if (!buildId || typeof buildId !== 'string') {
+      throw new Error('buildId is required and must be a non-empty string');
+    }
+
+    let data = await this.makeRequest(
+      `/api/sdk/builds/${buildId}?include=screenshots`,
+      apiToken,
+      apiUrl
+    );
+
+    let { build } = data;
+    let screenshots = build.screenshots || [];
+
+    // Filter by screenshot names if provided
+    if (screenshotNames && screenshotNames.length > 0) {
+      screenshots = screenshots.filter((s) => screenshotNames.includes(s.name));
+    }
+
+    return {
+      buildId: build.id,
+      buildName: build.name,
+      screenshots: screenshots.map((s) => ({
+        name: s.name,
+        url: s.original_url,
+        sha256: s.sha256,
+        width: s.viewport_width,
+        height: s.viewport_height,
+        browser: s.browser
+      }))
+    };
+  }
+}