### Install Vizzly CLI

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/QUICKSTART.md

Installs the Vizzly CLI globally using npm.

```bash
npm install -g @vizzly-testing/cli
```

--------------------------------

### vizzly tdd start command

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Example of starting TDD with 'vizzly tdd start' and getting JSON output.

```bash
vizzly tdd start --json
```

--------------------------------

### Usage Commands

Source: https://github.com/vizzly-testing/cli/blob/main/examples/custom-plugin/README.md

Commands to run after installing the plugin to see its functionality.

```bash
# See the new commands in help
vizzly --help

# Try the commands
vizzly hello
vizzly greet "World" --loud
vizzly check-services
vizzly list-screenshots
```

--------------------------------

### Testing on iPhone 15 Pro Max

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/INTEGRATION.md

Example command to run tests on a specific iOS simulator.

```bash
xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15 Pro Max'
```

--------------------------------

### Write a Visual Test

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/QUICKSTART.md

Example of a basic UI test case using Vizzly to capture a screenshot of the home screen.

```swift
import XCTest
import Vizzly
import VizzlyXCTest

class MyAppUITests: XCTestCase {
    let app = XCUIApplication()

    func testHomeScreen() {
        app.launch()

        // Wait for screen to load
        let title = app.navigationBars["Home"]
        XCTAssertTrue(title.waitForExistence(timeout: 5))

        // 📸 Capture screenshot
        app.vizzlyScreenshot(name: "home-screen")
    }
}
```

--------------------------------

### Testing on iPad Air

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/INTEGRATION.md

Example command to run tests on a specific iPad simulator.

```bash
xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPad Air (5th generation)'
```

--------------------------------

### Run Tests on Different Simulators

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/INTEGRATION.md

Example command to run tests on multiple simulators to capture device-specific screenshots.

```bash
# iPhone 15
xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'
```

--------------------------------

### Plugin Logic Example

Source: https://github.com/vizzly-testing/cli/blob/main/examples/custom-plugin/README.md

Example `plugin.js` file demonstrating how to register a custom command.

```javascript
export default {
  name: 'my-plugin',
  version: '1.0.0',
  register(program, { config, output, services }) {
    program
      .command('my-command')
      .description('My custom command')
      .action(() => {
        output.info('Running my command!');
      });
  }
};
```

--------------------------------

### Vizzly UI Test Example

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/INTEGRATION.md

Example Swift code demonstrating how to integrate Vizzly into an iOS UI test case using VizzlyXCTest for capturing screenshots with optional properties.

```swift
import XCTest
import Vizzly
import VizzlyXCTest

final class MyAppUITests: XCTestCase {

    let app = XCUIApplication()

    override func setUpWithError() throws {
        continueAfterFailure = true
        app.launch()

        // Optional: Log Vizzly status
        print("Vizzly ready: \(VizzlyClient.shared.isReady)")
    }

    func testLaunchScreen() {
        // Wait for launch screen
        let logo = app.images["AppLogo"]
        XCTAssertTrue(logo.waitForExistence(timeout: 5))

        // Capture screenshot
        app.vizzlyScreenshot(name: "launch-screen")
    }

    func testHomeScreen() {
        // Wait for home screen
        let homeTitle = app.navigationBars["Home"]
        XCTAssertTrue(homeTitle.waitForExistence(timeout: 5))

        // Capture with properties
        app.vizzlyScreenshot(
            name: "home-screen",
            properties: [
                "section": "home",
                "authenticated": false
            ]
        )
    }
}
```

--------------------------------

### Start TDD Server

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/QUICKSTART.md

Starts the Vizzly TDD server in your iOS project directory.

```bash
vizzly tdd start
```

--------------------------------

### vizzly tdd start command JSON output

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Example JSON output for the 'vizzly tdd start' command.

```json
{
  "status": "started",
  "port": 47392,
  "pid": 12345,
  "dashboardUrl": "http://localhost:47392"
}
```

--------------------------------

### Install and Initialize

Source: https://github.com/vizzly-testing/cli/blob/main/README.md

Install the Vizzly CLI globally and initialize it.

```bash
npm install -g @vizzly-testing/cli

vizzly init
```

--------------------------------

### GitHub Actions CI/CD Example

Source: https://github.com/vizzly-testing/cli/blob/main/clients/ember/README.md

An example of how to configure a GitHub Actions workflow to install Playwright and run tests with Vizzly.

```yaml
# GitHub Actions example
- name: Install Playwright
  run: npx playwright install chromium

- name: Run Tests
  env:
    VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}
  run: ember test
```

--------------------------------

### Main Config File - Example

Source: https://github.com/vizzly-testing/cli/blob/main/clients/static-site/README.md

Example configuration for the staticSite plugin in vizzly.config.js.

```javascript
// vizzly.config.js
export default {
  // Standard Vizzly config
  server: { port: 47392 },
  build: { environment: 'test' },

  // Static Site plugin config
  staticSite: {
    viewports: [
      { name: 'mobile', width: 375, height: 667 },
      { name: 'tablet', width: 768, height: 1024 },
      { name: 'desktop', width: 1920, height: 1080 },
    ],

    browser: {
      headless: true,
      args: ['--no-sandbox'],
    },

    screenshot: {
      fullPage: true,
      omitBackground: false,
    },

    // Concurrency auto-detected from CPU cores (min 2, max 8)
    // concurrency: 4,

    // Page filtering
    include: 'blog/**',
    exclude: '**/404.html',

    // Page discovery
    pageDiscovery: {
      useSitemap: true,
      sitemapPath: 'sitemap.xml',
      scanHtml: true,
    },
  },
};
```

--------------------------------

### Running CLI with Arguments

Source: https://github.com/vizzly-testing/cli/blob/main/AGENTS.md

Example of how to run the local CLI entrypoint with arguments.

```bash
npm run cli -- status
```

--------------------------------

### Installation

Source: https://github.com/vizzly-testing/cli/blob/main/clients/static-site/README.md

Install the static site plugin using npm.

```bash
npm install @vizzly-testing/static-site
```

--------------------------------

### Installation

Source: https://github.com/vizzly-testing/cli/blob/main/clients/vitest/README.md

Install the Vizzly Vitest plugin and CLI.

```bash
npm install -D @vizzly-testing/vitest @vizzly-testing/cli
```

--------------------------------

### Full JSON output

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Example of getting full JSON output for the 'vizzly builds' command.

```bash
vizzly builds --json
```

--------------------------------

### Installation

Source: https://github.com/vizzly-testing/cli/blob/main/clients/ember/test-app/README.md

Steps to clone the repository and install dependencies.

```bash
git clone <repository-url>
cd test-ember-app
npm install
```

--------------------------------

### Vizzly Configuration File

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/INTEGRATION.md

Example of a vizzly.config.js file with optional settings for screenshot threshold, TDD server port, and baseline directory.

```javascript
export default {
  // Screenshot threshold (0-100)
  threshold: 0,

  // TDD server port
  port: 47392,

  // Baseline directory
  baselineDir: '.vizzly/baselines'
}
```

--------------------------------

### Run Tests

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/QUICKSTART.md

Command to run Xcode tests from the terminal.

```bash
xcodebuild test \
  -scheme MyApp \
  -destination 'platform=iOS Simulator,name=iPhone 15'
```

--------------------------------

### Manual Configuration Example

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/README.md

Example of manually configuring the VizzlyClient with a specific server URL, overriding auto-discovery.

```swift
// Override auto-discovery
let client = VizzlyClient(serverUrl: "http://localhost:47392")
```

--------------------------------

### Responsive Design Test Example

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/INTEGRATION.md

Swift code snippet demonstrating how Vizzly automatically captures device information like model, screen dimensions, and scale factor when running tests on different simulators.

```swift
// Run tests on different simulators to capture device-specific screenshots
// Vizzly automatically includes device info in properties

func testResponsiveDesign() {
    app.launch()

    // The SDK automatically captures:
    // - Device model (iPhone 15, iPad Air, etc.)
    // - Screen dimensions
    // - Scale factor

    app.vizzlyScreenshot(name: "home-screen")
}
```

--------------------------------

### vizzly run command

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Example of running a command with 'vizzly run' and getting JSON output.

```bash
vizzly run "npm test" --json
```

--------------------------------

### Get Specific Build

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Get details for a specific build.

```bash
vizzly builds --build <id> --json
vizzly builds --build <id> --comparisons --json  # Include comparison details
```

--------------------------------

### Configuration - Config File Example

Source: https://github.com/vizzly-testing/cli/blob/main/clients/storybook/README.md

Example of a vizzly.config.js file with Storybook configuration.

```javascript
// vizzly.config.js
export default {
  storybook: {
    viewports: [
      { name: 'mobile', width: 375, height: 667 },
      { name: 'tablet', width: 768, height: 1024 },
      { name: 'desktop', width: 1920, height: 1080 },
    ],

    browser: {
      headless: true,
      args: ['--no-sandbox'],
    },

    screenshot: {
      fullPage: true,
      omitBackground: false,
    },

    concurrency: 3,

    include: 'components/**',
    exclude: '**/*.test',

    interactions: {
      // Pattern-based hooks
      'Button/*': async (page) => {
        await page.hover('button');
      },
      'Tooltip/*': async (page) => {
        await page.click('.tooltip-trigger');
      },
    },
  },
};
```

--------------------------------

### Services API Example

Source: https://github.com/vizzly-testing/cli/blob/main/examples/custom-plugin/README.md

Example of how to use the Services API within a plugin.

```javascript
let { git, testRunner, serverManager } = services;

// Git detection (v0.25.0+) - handles CI environments correctly
let gitInfo = await git.detect({ buildPrefix: 'MyPlugin' });
// Returns: { branch, commit, message, prNumber, buildName }

// Build lifecycle
let buildId = await testRunner.createBuild(options);
await testRunner.finalizeBuild(buildId, isTddMode, success, executionTime);

// Server control
await serverManager.start(buildId, tddMode, setBaseline);
await serverManager.stop();
```

--------------------------------

### vizzly tdd list command

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Example of listing TDD servers with 'vizzly tdd list' and getting JSON output.

```bash
vizzly tdd list --json
```

--------------------------------

### Get Configuration

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Display the current Vizzly configuration.

```bash
vizzly config --json
```

```json
{
  "configFile": "/path/to/vizzly.config.js",
  "config": {
    "server": { "port": 47392, "timeout": 30000 },
    "comparison": { "threshold": 2.0, "minClusterSize": 2 },
    "tdd": { "openReport": false },
    "api": {
      "url": "https://app.vizzly.dev",
      "tokenConfigured": true,
      "tokenPrefix": "vzt_abc1..."
    }
  },
  "project": {
    "name": "My Project",
    "slug": "my-project",
    "organization": "my-org"
  }
}
```

--------------------------------

### Plugin package.json

Source: https://github.com/vizzly-testing/cli/blob/main/examples/custom-plugin/README.md

Example `package.json` for a Vizzly plugin, including the `vizzlyPlugin` field.

```json
{
  "name": "@vizzly-testing/my-plugin",
  "vizzlyPlugin": "./plugin.js"
}
```

--------------------------------

### Sitemap.xml Parsing Example

Source: https://github.com/vizzly-testing/cli/blob/main/clients/static-site/README.md

Example of a sitemap.xml file used for page discovery.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/</loc>
  </url>
  <url>
    <loc>https://example.com/blog/post-1</loc>
  </url>
</urlset>
```

--------------------------------

### Installation via gem command

Source: https://github.com/vizzly-testing/cli/blob/main/clients/ruby/README.md

Install the Vizzly gem directly using the gem command.

```bash
gem install vizzly
```

--------------------------------

### Installation

Source: https://github.com/vizzly-testing/cli/blob/main/clients/storybook/README.md

Install the @vizzly-testing/storybook package using npm.

```bash
npm install @vizzly-testing/storybook
```

--------------------------------

### Start Vizzly TDD Server

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/README.md

Command to start the local Vizzly TDD server.

```bash
cd /path/to/your/ios/project
vizzly tdd start
```

--------------------------------

### Browser Arguments for Launch Failures

Source: https://github.com/vizzly-testing/cli/blob/main/clients/static-site/README.md

Example of how to pass browser arguments to resolve browser launch issues.

```bash
vizzly static-site ./dist --browser-args "--no-sandbox,--disable-dev-shm-usage"

```

--------------------------------

### vizzly tdd run command

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Example of running a command with 'vizzly tdd run' and getting JSON output.

```bash
vizzly tdd run "npm test" --json
```

--------------------------------

### Symlink to node_modules

Source: https://github.com/vizzly-testing/cli/blob/main/examples/custom-plugin/README.md

Steps to create a symlink for the plugin to be recognized by npm.

```bash
# From the vizzly-cli root
npm link

# Create symlink for the plugin
cd examples/custom-plugin
npm link @vizzly-testing/cli
cd ../..
mkdir -p node_modules/@vizzly-testing
ln -s ../../examples/custom-plugin node_modules/@vizzly-testing/example-plugin
```

--------------------------------

### vizzly context build commands

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Examples of using the `vizzly context build` command with various flags.

```bash
vizzly context build abc123 --json
vizzly context build abc123 --agent --json
vizzly context build abc123 --agent --json --include diffs,comments
vizzly context build abc123 --agent --json --full
vizzly context build current --source local --json
vizzly context build current --source local --agent
```

--------------------------------

### Vizzly Vitest Example CSS

Source: https://github.com/vizzly-testing/cli/blob/main/clients/vitest/tests/e2e/index.html

CSS styles for the Vizzly Vitest example page.

```css
body {
  margin: 0;
  font-family: system-ui, -apple-system, sans-serif;
  display: flex;
  justify-content: center;
  align-items: center;
  min-height: 100vh;
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

.hero {
  text-align: center;
  color: white;
  padding: 3rem;
}

h1 {
  font-size: 3rem;
  margin: 0 0 1rem 0;
}

p {
  font-size: 1.25rem;
  opacity: 0.9;
}
```

--------------------------------

### vizzly context similar command

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Example of using the `vizzly context similar` command.

```bash
vizzly context similar fp-dashboard --project storybook --org acme --json
```

--------------------------------

### Per-Story Configuration Example

Source: https://github.com/vizzly-testing/cli/blob/main/clients/storybook/README.md

Example of configuring specific stories with tags and parameters in Storybook files.

```javascript
// Button.stories.js
export let Primary = {
  args: { label: 'Click me' },
  parameters: {
    vizzly: {
      viewports: [
        { name: 'mobile', width: 375, height: 667 },
      ],
      beforeScreenshot: async (page) => {
        await page.hover('button');
      },
    },
  },
};

export let Disabled = {
  args: { label: 'Disabled', disabled: true },
  tags: ['vizzly-skip'], // Don't screenshot this story
};
```

--------------------------------

### Installation

Source: https://github.com/vizzly-testing/cli/blob/main/clients/ember/README.md

Install the Vizzly Ember SDK and a Playwright browser.

```bash
npm install -D @vizzly-testing/ember

# Install a Playwright browser
npx playwright install chromium
```

--------------------------------

### Screenshot with Properties

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/QUICKSTART.md

Captures a screenshot with custom properties like theme and user.

```swift
app.vizzlyScreenshot(
    name: "checkout-flow",
    properties: [
        "theme": "dark",
        "user": "premium"
    ]
)
```

--------------------------------

### TDD Mode - Start Server

Source: https://github.com/vizzly-testing/cli/blob/main/clients/storybook/README.md

Command to start the Vizzly TDD server for local visual testing.

```bash
# Start TDD server
vizzly tdd start
```

--------------------------------

### Full build context JSON output

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Example of full JSON output for complete build context.

```json
{
  "resource": "build_context",
  "source": "cloud",
  "scope": {
    "organization": { "slug": "acme" },
    "project": { "slug": "storybook" }
  },
  "build": {
    "id": "abc123",
    "status": "completed",
    "approval_status": "pending"
  },
  "baseline": {
    "selected": {
      "id": "baseline-build",
      "name": "Approved Main",
      "approval_status": "approved"
    },
    "selection_reason": "common_ancestor",
    "comparison_baseline_build_ids": ["baseline-build"]
  },
  "status": {
    "needs_review": true,
    "reasons": ["comparisons_need_review"],
    "pending_comparisons": 3,
    "unresolved_comments": 0
  },
  "summary": {
    "comparisons": {
      "total": 12,
      "changed": 2,
      "new": 1
    },
    "review": {
      "pending": 3,
      "approved": 9,
      "rejected": 0
    }
  },
  "screenshots": [
    {
      "name": "Dashboard",
      "url": "https://...",
      "baseline": { "url": "https://..." }
    }
  ],
  "comparisons": [
    {
      "id": "cmp-1",
      "screenshot_name": "Dashboard",
      "result": "changed",
      "needs_review": true,
      "diff": {
        "percentage": 0.42,
        "image_url": "https://...",
        "regions": []
      }
    }
  ],
  "comments": {
    "build": [],
    "screenshot_count": 0
  }
}
```

--------------------------------

### Interactions File (Optional) - Example

Source: https://github.com/vizzly-testing/cli/blob/main/clients/static-site/README.md

Example of a vizzly.static-site.js file for page-specific interactions and overrides.

```javascript
// vizzly.static-site.js
export default {
  // Interaction hooks - run before screenshots
  interactions: {
    'blog/*': async (page) => {
      await page.waitForSelector('.blog-content');
    },
    'products/*': async (page) => {
      await page.click('.view-details');
    },
  },

  // Per-page configuration overrides
  pages: {
    '/': {
      viewports: ['mobile', 'desktop'],
    },
    '/pricing': {
      screenshot: { fullPage: true },
    },
  },
};
```

--------------------------------

### Installation with Bundler

Source: https://github.com/vizzly-testing/cli/blob/main/clients/ruby/README.md

Add the Vizzly gem to your application's Gemfile and run bundle install.

```ruby
gem 'vizzly'
```

```bash
bundle install
```

--------------------------------

### vizzly context screenshot commands

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Examples of using the `vizzly context screenshot` command.

```bash
vizzly context screenshot Dashboard --json
vizzly context screenshot Dashboard --source local --json
```

--------------------------------

### Basic Screenshot Example

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/README.md

Capturing a full-screen screenshot with a given name.

```swift
func testLoginScreen() {
    app.launch()
    app.buttons["Login"].tap()

    // Capture full screen
    app.vizzlyScreenshot(name: "login-screen")
}
```

--------------------------------

### Plugin Options

Source: https://github.com/vizzly-testing/cli/blob/main/clients/vitest/README.md

Example of how to use the Vizzly plugin with and without options.

```javascript
import { vizzlyPlugin } from '@vizzly-testing/vitest'

// Simple - just add the plugin
vizzlyPlugin()

// Or with options (rarely needed)
vizzlyPlugin({
  // Plugin-specific options can go here
})
```

--------------------------------

### configure() API - Basic Usage

Source: https://github.com/vizzly-testing/cli/blob/main/clients/ember/README.md

Basic example of using the configure() function to wrap Testem configuration.

```javascript
const { configure } = require('@vizzly-testing/ember');

// Basic - runs headless by default
module.exports = configure({
  launch_in_ci: ['Chrome'],
  launch_in_dev: ['Chrome'],
});
```

--------------------------------

### vizzly context comparison commands

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Examples of using the `vizzly context comparison` command.

```bash
vizzly context comparison cmp-1 --json
vizzly context comparison build-detail-screenshots --source local --json
```

--------------------------------

### Troubleshooting: Browser fails to launch

Source: https://github.com/vizzly-testing/cli/blob/main/clients/ember/README.md

Instructions for installing Playwright browsers, including dependencies for CI environments.

```bash
npx playwright install chromium

For CI environments, you may need additional dependencies:

npx playwright install-deps chromium
```

--------------------------------

### Multiple Device Orientations Example

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/README.md

Capturing screenshots for different device orientations.

```swift
func testResponsiveLayout() {
    app.launch()

    // Portrait
    XCUIDevice.shared.orientation = .portrait
    app.vizzlyScreenshot(
        name: "home-portrait",
        properties: ["orientation": "portrait"]
    )

    // Landscape
    XCUIDevice.shared.orientation = .landscapeLeft
    app.vizzlyScreenshot(
        name: "home-landscape",
        properties: ["orientation": "landscape"]
    )
}
```

--------------------------------

### Local Testing Configuration

Source: https://github.com/vizzly-testing/cli/blob/main/examples/custom-plugin/README.md

Configuration in `vizzly.config.js` to test your plugin locally.

```javascript
export default {
  plugins: ['./path/to/your/plugin.js']
};
```

--------------------------------

### Running / Development

Source: https://github.com/vizzly-testing/cli/blob/main/clients/ember/test-app/README.md

Commands to start the development server and access the app and tests.

```bash
npm run start
```

--------------------------------

### Screenshot Options

Source: https://github.com/vizzly-testing/cli/blob/main/clients/vitest/README.md

Example of passing custom options to `toMatchScreenshot`.

```javascript
await expect(page).toMatchScreenshot('screenshot.png', {
  // Custom properties for multi-variant testing
  properties: {
    theme: 'dark',
    language: 'en',
    userRole: 'admin'
  },

  // Comparison threshold (0-100)
  threshold: 5,

  // Full page capture
  fullPage: true
})
```

--------------------------------

### Multi-Variant Testing Example

Source: https://github.com/vizzly-testing/cli/blob/main/clients/vitest/README.md

Demonstrates testing different component variants using properties.

```javascript
test('button variants', async () => {
  // Light theme
  document.body.classList.add('theme-light')
  await expect(page.getByRole('button')).toMatchScreenshot('button.png', {
    properties: { theme: 'light' }
  })

  // Dark theme
  document.body.classList.remove('theme-light')
  document.body.classList.add('theme-dark')
  await expect(page.getByRole('button')).toMatchScreenshot('button.png', {
    properties: { theme: 'dark' }
  })
})
```

--------------------------------

### Screenshot with Properties Example

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/README.md

Capturing a screenshot with custom properties for metadata.

```swift
func testDarkMode() {
    app.launch()
    enableDarkMode()

    app.vizzlyScreenshot(
        name: "home-dark",
        properties: [
            "theme": "dark",
            "feature": "dark-mode"
        ]
    )
}
```

--------------------------------

### Get Specific Config Value

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Retrieve a specific configuration value.

```bash
vizzly config comparison.threshold --json
```

```json
{
  "key": "comparison.threshold",
  "value": 2.0
}
```

--------------------------------

### Screenshot an Element

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/QUICKSTART.md

Captures a screenshot of a specific UI element, like a button.

```swift
let button = app.buttons["Submit"]
button.vizzlyScreenshot(name: "submit-button")
```

--------------------------------

### Using the Client Directly Example

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/README.md

Sending a PNG representation of a screenshot directly using VizzlyClient.

```swift
import Vizzly

func testWithDirectClient() {
    let screenshot = app.screenshot()

    VizzlyClient.shared.screenshot(
        name: "custom-screenshot",
        image: screenshot.pngRepresentation,
        properties: [
            "customProperty": "value",
            "browser": "Safari"
        ],
        threshold: 0
    )
}
```

--------------------------------

### Local Path in Config

Source: https://github.com/vizzly-testing/cli/blob/main/examples/custom-plugin/README.md

Add this configuration to your `vizzly.config.js` to use a local plugin.

```javascript
export default {
  plugins: [
    './examples/custom-plugin/plugin.js'
  ]
};
```

--------------------------------

### Run Tests - TDD Mode

Source: https://github.com/vizzly-testing/cli/blob/main/clients/vitest/README.md

Start Vizzly TDD server and run Vitest tests.

```bash
# Terminal 1: Start Vizzly TDD server
npx vizzly dev start

# Terminal 2: Run tests
npx vitest

# Open dashboard at http://localhost:47392
```

--------------------------------

### Using Properties for Screenshot Context

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/README.md

Example demonstrating how to add custom properties to a screenshot for additional context.

```swift
app.vizzlyScreenshot(
    name: "product-list",
    properties: [
        "theme": "dark",
        "user": "premium",
        "itemCount": 50
    ]
)
```

--------------------------------

### vizzly tdd stop command

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Example of stopping TDD with 'vizzly tdd stop' and getting JSON output.

```bash
vizzly tdd stop --json
```

--------------------------------

### Good Screenshot Naming Convention

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/README.md

Example of recommended screenshot naming conventions using dashes for hierarchy.

```swift
// ✅ Good - Use dashes for hierarchy
app.vizzlyScreenshot(name: "checkout-payment-form-valid-card")
app.vizzlyScreenshot(name: "settings-profile-edit-mode")
```

--------------------------------

### Build, Test, and Development Commands

Source: https://github.com/vizzly-testing/cli/blob/main/AGENTS.md

Common commands for building, testing, and developing the CLI and reporter.

```bash
npm run build
npm test
npm run test:watch
npm run test:reporter
npm run test:types
npm run lint
npm run format:check
npm run fix
npm run cli -- <args>
```

--------------------------------

### configure() API - With Debugging Options

Source: https://github.com/vizzly-testing/cli/blob/main/clients/ember/README.md

Example of configuring headed mode with additional debugging options like slowMo and timeout.

```javascript
const { configure } = require('@vizzly-testing/ember');

module.exports = configure({
  launch_in_ci: ['Chrome'],
}, {
  headless: false,
  slowMo: 100,     // Slow down for debugging
  timeout: 60000,  // Longer launch timeout
});
```

--------------------------------

### vizzly tdd status command

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Example of checking TDD status with 'vizzly tdd status' and getting JSON output.

```bash
vizzly tdd status --json
```

--------------------------------

### GitHub Actions Integration

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/README.md

Example YAML configuration for integrating Vizzly visual tests into a GitHub Actions workflow.

```yaml
name: Visual Tests

on: [push, pull_request]

jobs:
  ios-tests:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v3

      - name: Run UI tests with Vizzly
        env:
          VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}
        run: |
          npx vizzly run -- xcodebuild test \
            -scheme MyApp \
            -destination 'platform=iOS Simulator,name=iPhone 15' \
            -resultBundlePath TestResults
```

--------------------------------

### Troubleshooting - Browser launch fails

Source: https://github.com/vizzly-testing/cli/blob/main/clients/storybook/README.md

Command to capture screenshots with additional browser arguments to resolve potential sandbox issues.

```bash
vizzly storybook ./storybook-static --browser-args "--no-sandbox,--disable-dev-shm-usage"
```

--------------------------------

### Initialize Vizzly Configuration

Source: https://github.com/vizzly-testing/cli/blob/main/README.md

Generate a default configuration file for Vizzly.

```bash
vizzly init
```

--------------------------------

### CLI Usage - With custom viewports

Source: https://github.com/vizzly-testing/cli/blob/main/clients/static-site/README.md

Capture screenshots with custom viewports defined as name:WxH.

```bash
vizzly static-site ./dist \
  --viewports "mobile:375x667,tablet:768x1024,desktop:1920x1080"
```

--------------------------------

### Install Playwright Browsers

Source: https://github.com/vizzly-testing/cli/blob/main/clients/ember/README.md

Commands to install the necessary browsers for Playwright to use with Vizzly.

```bash
npx playwright install chromium
npx playwright install firefox
npx playwright install webkit
```

--------------------------------

### vizzly init command JSON output

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Example JSON output for the `vizzly init --json` command, indicating project initialization status.

```bash
vizzly init --json
```

```json
{
  "status": "created",
  "configPath": "/path/to/vizzly.config.js"
}
```

--------------------------------

### Preview Build Artifacts

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Generate a preview for build artifacts in a directory.

```bash
vizzly preview ./dist --json
```

```json
{
  "success": true,
  "buildId": "abc123-def456",
  "previewUrl": "https://preview.vizzly.dev/abc123",
  "files": 150,
  "bytes": 5000000,
  "compressedBytes": 1200000,
  "compressionRatio": "76%",
  "expiresAt": "2025-03-01T00:00:00Z"
}
```

--------------------------------

### Run Your Tests

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/README.md

Command to run UI tests via xcodebuild.

```bash
# Via Xcode: Cmd+U
# Or via command line:
xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'
```

--------------------------------

### Get Baseline Info

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Retrieve information for a specific baseline.

```bash
vizzly baselines --info "button-primary" --json
```

--------------------------------

### Custom Threshold Example

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/README.md

Capturing a screenshot with a custom comparison threshold.

```swift
func testAnimatedContent() {
    // Allow a higher comparison threshold for animated content
    app.vizzlyScreenshot(
        name: "animated-banner",
        threshold: 5
    )
}
```

--------------------------------

### Local Development (TDD Mode)

Source: https://github.com/vizzly-testing/cli/blob/main/README.md

Start the TDD server and run tests in watch mode for instant visual diffs.

```bash
vizzly tdd start
npm test -- --watch
```

--------------------------------

### Element Screenshot Example

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/README.md

Capturing a screenshot of a specific UI element.

```swift
func testNavigationBar() {
    let navbar = app.navigationBars.firstMatch

    // Capture just the navbar
    navbar.vizzlyScreenshot(
        name: "navbar",
        properties: ["component": "navbar"]
    )
}
```

--------------------------------

### Checking for Sitemap and HTML Files

Source: https://github.com/vizzly-testing/cli/blob/main/clients/static-site/README.md

Commands to verify the presence of sitemap.xml and HTML files in the distribution directory.

```bash
ls dist/sitemap.xml
ls dist/**/*.html

```

--------------------------------

### Troubleshooting: Verifying Server Reachability

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/INTEGRATION.md

Bash commands to ensure the Vizzly TDD server is running and reachable, including explicitly setting the server URL.

```bash
1. Ensure TDD server is running: `vizzly tdd start`
2. Check `~/.vizzly/server.json` exists in your home directory
3. Verify the server is reachable: `curl http://localhost:47392/health`
4. Or explicitly set: `export VIZZLY_SERVER_URL=http://localhost:47392`
```

--------------------------------

### Server Not Found Troubleshooting

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/README.md

Steps to troubleshoot 'Server Not Found' errors, including starting the TDD server, checking configuration, and verifying reachability.

```bash
vizzly tdd start
```

```bash
curl http://localhost:47392/health
```

```bash
export VIZZLY_SERVER_URL=http://localhost:47392
```

--------------------------------

### List Builds

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

List builds with optional filtering.

```bash
vizzly builds --json
vizzly builds --branch main --status completed --limit 10 --json
```

```json
{
  "builds": [
    {
      "id": "abc123-def456",
      "name": "Build #123",
      "status": "completed",
      "branch": "main",
      "commit": "abc1234",
      "commitMessage": "Add feature",
      "environment": "test",
      "screenshotCount": 15,
      "comparisons": {
        "total": 15,
        "new": 2,
        "changed": 1,
        "identical": 12
      },
      "approvalStatus": "approved",
      "createdAt": "2025-01-15T10:30:00Z",
      "completedAt": "2025-01-15T10:32:00Z"
    }
  ],
  "pagination": {
    "total": 100,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}
```

--------------------------------

### Get Specific Comparison

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Retrieve details for a specific comparison by its ID.

```bash
vizzly comparisons --id <comparison-id> --json
```

--------------------------------

### Run UI Tests via Command Line

Source: https://github.com/vizzly-testing/cli/blob/main/clients/swift/INTEGRATION.md

Command to run UI tests for a specific scheme and destination using xcodebuild.

```bash
xcodebuild test \
  -scheme MyApp \
  -destination 'platform=iOS Simulator,name=iPhone 15' \
  -only-testing:MyAppUITests
```

--------------------------------

### Fingerprint context JSON output

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Example JSON output for fingerprint context.

```json
{
  "resource": "fingerprint_context",
  "source": "cloud",
  "fingerprint": {
    "hash": "fp-dashboard"
  },
  "matches": [
    {
      "comparison_id": "cmp-1",
      "build_id": "abc123",
      "screenshot_name": "Dashboard"
    }
  ]
}
```

--------------------------------

### Screenshot context JSON output

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Example JSON output for screenshot context.

```json
{
  "resource": "screenshot_context",
  "source": "cloud",
  "screenshot": {
    "name": "Dashboard"
  },
  "confirmed_regions": [
    {
      "label": "Known header copy band"
    }
  ],
  "history": {
    "recent_comparisons": []
  }
}
```

--------------------------------

### CLI Usage - Capture screenshots from a static site build

Source: https://github.com/vizzly-testing/cli/blob/main/clients/static-site/README.md

Capture screenshots from a static site build located in the ./dist directory.

```bash
vizzly static-site ./dist
```

--------------------------------

### Comparison context JSON output

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Example JSON output for comparison context.

```json
{
  "resource": "comparison_context",
  "source": "local_workspace",
  "comparison": {
    "id": "cmp-1",
    "name": "Dashboard",
    "result": "changed",
    "analysis": {
      "diff_image_url": ".vizzly/diffs/dashboard.png",
      "diff_regions": [],
      "confirmed_regions": []
    }
  },
  "history": {
    "similar_by_fingerprint": [],
    "recent_by_name": [],
    "hotspot_analysis": {
      "confidence": "no_data"
    }
  }
}
```

--------------------------------

### Interaction Hooks - Global Hooks (Pattern-Based)

Source: https://github.com/vizzly-testing/cli/blob/main/clients/storybook/README.md

Example of global, pattern-based interaction hooks in vizzly.config.js.

```javascript
// vizzly.config.js
export default {
  storybook: {
    interactions: {
    'Button/*': async (page) => {
      // Apply to all Button stories
      await page.hover('button');
    },
    'Form/*': async (page) => {
      // Apply to all Form stories
      await page.fill('input[name="email"]', 'test@example.com');
      await page.click('button[type="submit"]');
    },
    'Dropdown/WithOptions': async (page) => {
      // Specific story
      await page.click('.dropdown-toggle');
    },
    },
  },
};
```

--------------------------------

### Visual Context for Agents - Build or Comparison

Source: https://github.com/vizzly-testing/cli/blob/main/README.md

Get cloud context for a build or comparison. Use --json for a durable automation path.

```bash
# Cloud context for a build or comparison
vizzly context build abc123
vizzly context comparison def456 --json
```

--------------------------------

### Review Queue Context

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Get the review queue context for a project or source.

```bash
vizzly context review-queue --project storybook --org acme --json
vizzly context review-queue --source local --json
```

```json
{
  "resource": "review_queue_context",
  "source": "local_workspace",
  "summary": {
    "total": 2,
    "changed": 1,
    "new": 1
  },
  "comparisons": [
    {
      "id": "cmp-1",
      "name": "Settings Panel",
      "result": "changed"
    }
  ]
}
```

--------------------------------

### Troubleshooting - Screenshots are blank

Source: https://github.com/vizzly-testing/cli/blob/main/clients/storybook/README.md

Example of using the `interactions` hook to wait for specific elements to appear before taking a screenshot, useful when components need time to render.

```javascript
interactions: {
  '**': async (page) => {
    // Wait for your component's content to be visible
    await page.waitForSelector('.your-component-class', { visible: true });
  },
}
```

--------------------------------

### Select specific fields

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Example of selecting specific fields (id, status, branch) for the 'vizzly builds' command using JSON output.

```bash
vizzly builds --json id,status,branch
```

--------------------------------

### Compact agent JSON output

Source: https://github.com/vizzly-testing/cli/blob/main/docs/json-output.md

Example of compact JSON output for agent consumption.

```json
{
  "resource": "build_agent_context",
  "source": "cloud",
  "project": {
    "organization": "acme",
    "slug": "storybook",
    "name": "Storybook"
  },
  "build": {
    "id": "abc123",
    "status": "completed",
    "approval_status": "pending"
  },
  "baseline": {
    "selected": {
      "id": "baseline-build",
      "name": "Approved Main",
      "approval_status": "approved"
    },
    "selection_reason": "latest approved build"
  },
  "status": {
    "needs_review": true,
    "reasons": ["comparisons_need_review"],
    "pending_comparisons": 3,
    "unresolved_comments": 0
  },
  "summary": {
    "comparisons": {
      "total": 12,
      "changed": 2,
      "new": 1
    }
  },
  "evidence": [
    {
      "id": "cmp-1",
      "name": "Dashboard",
      "result": "changed",
      "needs_review": true,
      "diff": {
        "percentage": 0.42,
        "fingerprint_hash": "00000000001ec127",
        "region_count": 12,
        "image_url": "https://..."
      }
    }
  ],
  "next_actions": [
    "Inspect the changed and new comparisons before editing related UI.",
    "Use approved baselines as the expected visual behavior.",
    "Leave approval decisions to human reviewers."
  ]
}
```

--------------------------------

### CLI Usage - With filtering

Source: https://github.com/vizzly-testing/cli/blob/main/clients/static-site/README.md

Capture screenshots with include and exclude patterns for page filtering.

```bash
vizzly static-site ./dist \
  --include "blog/**" \
  --exclude "**/404.html"
```