@vizzly-testing/cli 0.1.0 → 0.2.0

package/docs/test-integration.md

@@ -0,0 +1,412 @@
+# Test Integration Guide
+
+The `vizzly run` command integrates Vizzly directly into your test suite, automatically capturing screenshots during test execution and processing them through Vizzly's visual comparison pipeline.
+
+## Command Options
+
+**`--build-name <name>`** - Custom build name
+```bash
+vizzly run "npm test" --build-name "PR-123"
+```
+
+**`--environment <env>`** - Environment name (default: "test")
+```bash
+vizzly run "npm test" --environment "staging"
+```
+
+**`--branch <branch>`** - Git branch override
+```bash
+vizzly run "npm test" --branch "feature/new-ui"
+```
+
+**`--commit <sha>`** - Git commit SHA override
+```bash
+vizzly run "npm test" --commit "abc123def456"
+```
+
+**`--message <msg>`** - Commit message override
+```bash
+vizzly run "npm test" --message "Add new component"
+```## Basic Usage
+
+```bash
+vizzly run "<your-test-command>"
+```
+
+Examples with different test frameworks:
+
+```bash
+vizzly run "npm test"
+vizzly run "npx playwright test"
+vizzly run "npx cypress run"
+vizzly run "bundle exec rspec"
+vizzly run "python -m pytest"
+```
+
+## How It Works
+
+When you run `vizzly run`:
+
+1. **Starts a local server** - Creates a screenshot capture endpoint
+2. **Sets environment variables** - Makes Vizzly available to your tests
+3. **Runs your test command** - Executes your normal test suite
+4. **Captures screenshots** - Collects screenshots from `vizzlyScreenshot()` calls
+5. **Uploads results** - Sends all screenshots to Vizzly for processing
+
+## Environment Variables
+
+The CLI automatically sets these variables for your test process:
+
+- `VIZZLY_SERVER_URL` - Local server URL for screenshot uploads
+- `VIZZLY_BUILD_ID` - Unique identifier for this test run
+- `VIZZLY_ENABLED` - Set to `true` to enable screenshot capture
+- `VIZZLY_TDD_MODE` - Set to `true` when using `--tdd` flag
+
+## Adding Screenshots to Tests
+
+Import the client and use `vizzlyScreenshot()` in your tests:
+
+```javascript
+import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
+
+// Your test framework takes the screenshot
+const screenshot = await page.screenshot();
+
+// Send to Vizzly
+await vizzlyScreenshot('homepage', screenshot, {
+  properties: {
+    browser: 'chrome',
+    viewport: '1920x1080'
+  }
+});
+```
+
+## Framework Examples
+
+### Playwright
+
+```javascript
+import { test } from '@playwright/test';
+import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
+
+test('homepage test', async ({ page }) => {
+  await page.goto('/');
+  
+  const screenshot = await page.screenshot();
+  await vizzlyScreenshot('homepage', screenshot, {
+    properties: {
+      browser: 'chrome',
+      viewport: '1920x1080',
+      page: 'home'
+    }
+  });
+});
+```
+
+### Cypress
+
+```javascript
+// cypress/support/commands.js
+import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
+
+Cypress.Commands.add('vizzlyScreenshot', (name, properties = {}) => {
+  cy.screenshot(name, { capture: 'viewport' });
+  
+  cy.readFile(`cypress/screenshots/${name}.png`, 'base64').then((imageBase64) => {
+    const imageBuffer = Buffer.from(imageBase64, 'base64');
+    return vizzlyScreenshot(name, imageBuffer, {
+      properties: {
+        browser: Cypress.browser.name,
+        framework: 'cypress',
+        ...properties
+      }
+    });
+  });
+});
+
+// In your test
+describe('Homepage', () => {
+  it('should render correctly', () => {
+    cy.visit('/');
+    cy.vizzlyScreenshot('homepage', {
+      page: 'home',
+      state: 'logged-out'
+    });
+  });
+});
+```
+
+### Puppeteer
+
+```javascript
+import puppeteer from 'puppeteer';
+import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
+
+describe('Visual tests', () => {
+  test('homepage screenshot', async () => {
+    const browser = await puppeteer.launch();
+    const page = await browser.newPage();
+    await page.goto('/');
+    
+    const screenshot = await page.screenshot();
+    await vizzlyScreenshot('homepage', screenshot, {
+      properties: {
+        browser: 'chrome',
+        framework: 'puppeteer'
+      }
+    });
+    
+    await browser.close();
+  });
+});
+```
+
+## Command Options
+
+### Server Configuration
+
+**`--port <port>`** - Server port (default: 47392)
+```bash
+vizzly run "npm test" --port 3002
+```
+
+**`--timeout <ms>`** - Server timeout in milliseconds (default: 30000)
+```bash
+vizzly run "npm test" --timeout 60000
+```
+
+### Build Configuration
+
+**`--build-name <name>`** - Custom build name
+```bash
+vizzly run "npm test" --build-name "PR-123"
+```
+
+**`--environment <env>`** - Environment name (default: "test")
+```bash
+vizzly run "npm test" --environment "staging"
+```
+
+**`--branch <branch>`** - Git branch override
+```bash
+vizzly run "npm test" --branch "feature/new-ui"
+```
+
+### Processing Options
+
+**`--wait`** - Wait for build completion
+```bash
+vizzly run "npm test" --wait
+```
+
+**`--eager`** - Create build immediately (default: lazy)
+```bash
+vizzly run "npm test" --eager
+```
+
+**`--threshold <number>`** - Comparison threshold (0-1, default: 0.01)
+```bash
+vizzly run "npm test" --threshold 0.02
+```
+
+### Development Options
+
+**`--tdd`** - Enable TDD mode (see [TDD Mode Guide](./tdd-mode.md))
+```bash
+vizzly run "npm test" --tdd
+```
+
+**`--allow-no-token`** - Allow running without API token
+```bash
+vizzly run "npm test" --allow-no-token
+```
+
+**`--token <token>`** - API token override
+```bash
+vizzly run "npm test" --token "your-token-here"
+```
+
+### Baseline Configuration
+
+**`--baseline-build <id>`** - Use specific build as baseline
+```bash
+vizzly run "npm test" --baseline-build "build_123"
+```
+
+**`--baseline-comparison <id>`** - Use specific comparison as baseline
+```bash
+vizzly run "npm test" --baseline-comparison "comp_456"
+```
+
+## Screenshot Properties
+
+The `properties` object in `vizzlyScreenshot()` is flexible and can contain any metadata:
+
+```javascript
+await vizzlyScreenshot('dashboard', screenshot, {
+  properties: {
+    // Technical metadata
+    browser: 'chrome',
+    os: 'macos',
+    viewport: '1920x1080',
+    device: 'desktop',
+    
+    // Organizational metadata
+    component: 'dashboard',
+    page: 'home',
+    feature: 'analytics',
+    theme: 'dark',
+    
+    // Test metadata
+    testSuite: 'smoke-tests',
+    userType: 'admin',
+    state: 'logged-in',
+    
+    // Custom metadata
+    buildNumber: process.env.BUILD_NUMBER,
+    environment: 'staging'
+  }
+});
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: Visual Tests
+on: [push, pull_request]
+
+jobs:
+  visual-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - run: npx vizzly run "npm test" --wait
+        env:
+          VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}
+```
+
+### GitLab CI
+
+```yaml
+visual-tests:
+  stage: test
+  image: node:20
+  script:
+    - npm ci
+    - npx vizzly run "npm test" --wait
+  variables:
+    VIZZLY_TOKEN: $VIZZLY_TOKEN
+```
+
+## Advanced Usage
+
+### Conditional Screenshots
+
+Only take screenshots when Vizzly is enabled:
+
+```javascript
+import { isVizzlyEnabled, vizzlyScreenshot } from '@vizzly-testing/cli/client';
+
+if (isVizzlyEnabled()) {
+  const screenshot = await page.screenshot();
+  await vizzlyScreenshot('homepage', screenshot);
+}
+```
+
+### Batch Screenshot Processing
+
+Wait for all screenshots to be processed:
+
+```javascript
+import { vizzlyFlush } from '@vizzly-testing/cli/client';
+
+// Take multiple screenshots
+await vizzlyScreenshot('page1', screenshot1);
+await vizzlyScreenshot('page2', screenshot2);
+await vizzlyScreenshot('page3', screenshot3);
+
+// Wait for all to be processed
+await vizzlyFlush();
+```
+
+### Custom Configuration
+
+Use a custom configuration per test run:
+
+```javascript
+import { configure } from '@vizzly-testing/cli/client';
+
+// Configure before taking screenshots
+configure({
+  serverUrl: 'http://localhost:3001',
+  enabled: true
+});
+```
+
+## Troubleshooting
+
+**Port already in use**
+```bash
+vizzly run "npm test" --port 3002
+```
+
+**Screenshots not captured**
+- Verify you're calling `vizzlyScreenshot()` in your tests
+- Check that your test framework supports the Buffer API
+- Ensure the image data is valid PNG format
+
+**Test command not found**
+- Use absolute paths or ensure commands are in PATH
+- Quote complex commands properly
+- Test your command works independently first
+
+**Server timeout**
+- Increase timeout for long-running test suites
+- Check for hanging processes or infinite loops
+
+```bash
+vizzly run "npm test" --timeout 120000  # 2 minutes
+```
+
+## Best Practices
+
+### Screenshot Naming
+Use descriptive, consistent names:
+```javascript
+// Good
+await vizzlyScreenshot('homepage-logged-out', screenshot);
+await vizzlyScreenshot('dashboard-admin-view', screenshot);
+
+// Avoid
+await vizzlyScreenshot('test1', screenshot);
+await vizzlyScreenshot('screenshot', screenshot);
+```
+
+### Organizing Tests
+Group related screenshots with properties:
+```javascript
+await vizzlyScreenshot('user-profile', screenshot, {
+  properties: {
+    component: 'profile',
+    state: 'editing',
+    userType: 'admin'
+  }
+});
+```
+
+### Performance
+- Take screenshots only when necessary
+- Use appropriate image sizes
+- Consider screenshot timing in your tests
+
+## Next Steps
+
+- Learn about [TDD Mode](./tdd-mode.md) for local development
+- Explore [Upload Command](./upload-command.md) for direct uploads
+- Check the [API Reference](./api-reference.md) for detailed function documentation

package/docs/upload-command.md

@@ -0,0 +1,189 @@
+# Upload Command Guide
+
+The `vizzly upload` command is the simplest way to get started with Vizzly. It uploads screenshots directly from a directory without requiring test integration.
+
+## Basic Usage
+
+```bash
+vizzly upload <path>
+```
+
+Upload all screenshots from a directory:
+
+```bash
+vizzly upload ./screenshots
+vizzly upload ./test-results/screenshots
+vizzly upload ./cypress/screenshots
+```
+
+## Options
+
+### Build Information
+
+**`--build-name <name>`** - Custom build name
+```bash
+vizzly upload ./screenshots --build-name "Release v1.2.3"
+vizzly upload ./screenshots --build-name "PR-456"
+```
+
+**`--environment <env>`** - Environment name (default: "test")
+```bash
+vizzly upload ./screenshots --environment "staging"
+vizzly upload ./screenshots --environment "production"
+```
+
+### Git Integration
+
+The CLI automatically detects git information, but you can override:
+
+**`--branch <branch>`** - Git branch override
+```bash
+vizzly upload ./screenshots --branch "feature/new-ui"
+```
+
+**`--commit <sha>`** - Git commit SHA override
+```bash
+vizzly upload ./screenshots --commit "abc123def456"
+```
+
+**`--message <msg>`** - Commit message override
+```bash
+vizzly upload ./screenshots --message "Fix header layout"
+```
+
+### Comparison Settings
+
+**`--threshold <number>`** - Comparison threshold (0-1, default: 0.01)
+```bash
+vizzly upload ./screenshots --threshold 0.05  # More tolerant
+vizzly upload ./screenshots --threshold 0.001 # More strict
+```
+
+### Processing
+
+**`--wait`** - Wait for build completion
+```bash
+vizzly upload ./screenshots --wait
+```
+
+This will:
+- Upload all screenshots
+- Wait for processing to complete
+- Show progress and results
+- Exit with appropriate status code
+
+**`--metadata <json>`** - Additional metadata as JSON
+```bash
+vizzly upload ./screenshots --metadata '{"browser": "chrome", "viewport": "1920x1080"}'
+```
+
+## Examples
+
+### Basic Upload
+```bash
+# Simple upload with auto-detected git info
+vizzly upload ./screenshots
+```
+
+### Release Build
+```bash
+# Upload with specific build name and wait for results
+vizzly upload ./screenshots \
+  --build-name "Release v2.1.0" \
+  --environment "production" \
+  --wait
+```
+
+### CI/CD Integration
+```bash
+# Upload with CI-specific metadata
+vizzly upload ./test-results/screenshots \
+  --build-name "CI-Build-${BUILD_NUMBER}" \
+  --branch "${GIT_BRANCH}" \
+  --commit "${GIT_COMMIT}" \
+  --message "${GIT_COMMIT_MESSAGE}" \
+  --wait
+```
+
+### Manual Testing
+```bash
+# Upload with custom metadata for manual test session
+vizzly upload ./manual-screenshots \
+  --build-name "Manual Test Session" \
+  --metadata '{"tester": "john.doe", "device": "iPhone 13"}' \
+  --environment "staging"
+```
+
+## File Support
+
+The upload command supports:
+
+- **PNG files** - Primary format for screenshots
+- **JPG/JPEG files** - Also supported
+- **Recursive directory scanning** - Finds images in subdirectories
+- **Automatic filtering** - Ignores non-image files
+
+## Build Processing
+
+When you upload screenshots, Vizzly:
+
+1. **Creates a build** - Groups your screenshots together
+2. **Finds baselines** - Matches against previous approved screenshots
+3. **Generates comparisons** - Creates visual diffs for changed screenshots
+4. **Provides results** - Shows what changed, what's new, what's approved
+
+## Status Codes
+
+The upload command exits with different status codes:
+
+- **0** - Success (all screenshots approved or no changes)
+- **1** - Changes detected (requires review)
+- **2** - Upload failed or error occurred
+
+This makes it perfect for CI/CD pipelines where you want the build to fail if visual changes are detected.
+
+## Common Workflows
+
+### First Time Setup
+```bash
+# Upload initial baseline screenshots
+vizzly upload ./screenshots --build-name "Initial Baseline"
+```
+
+### Regular Development
+```bash
+# Upload after making changes
+vizzly upload ./screenshots --build-name "Feature: New Dashboard"
+```
+
+### Release Process
+```bash
+# Upload release candidate screenshots
+vizzly upload ./screenshots \
+  --build-name "Release Candidate v2.0" \
+  --environment "production" \
+  --wait
+```
+
+## Troubleshooting
+
+**No screenshots found**
+- Check the path exists and contains image files
+- Verify file permissions
+- Use absolute paths if relative paths aren't working
+
+**Upload failed**
+- Verify your API token is set: `echo $VIZZLY_TOKEN`
+- Check network connectivity
+- Try with `--verbose` for detailed error information
+
+**Slow uploads**
+- Large image files take longer to upload
+- Network speed affects upload time
+- Use `--wait` to see progress information
+
+## Next Steps
+
+- Learn about [Test Integration](./test-integration.md) for automated screenshot capture
+- Explore [TDD Mode](./tdd-mode.md) for local development
+- Check the [API Reference](./api-reference.md) for programmatic usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Visual review platform for UI developers and designers",
   "keywords": [
     "visual-testing",
@@ -13,10 +13,10 @@
     "cli"
   ],
   "homepage": "https://vizzly.dev",
-  "bugs": "https://github.com/vizzly/cli/issues",
+  "bugs": "https://github.com/vizzly-testing/cli/issues",
   "repository": {
     "type": "git",
-    "url": "https://github.com/vizzly/cli.git"
+    "url": "https://github.com/vizzly-testing/cli.git"
   },
   "license": "MIT",
   "author": "Stubborn Mule Software <support@vizzly.dev>",
@@ -47,6 +47,7 @@
   "files": [
     "bin",
     "dist",
+    "docs",
     "README.md",
     "LICENSE"
   ],
@@ -72,13 +73,10 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@babel/runtime": "^7.23.6",
-    "@vitejs/plugin-react": "^4.7.0",
     "commander": "^11.1.0",
     "cosmiconfig": "^9.0.0",
     "form-data": "^4.0.0",
     "glob": "^10.3.10",
-    "inquirer": "^12.9.1",
     "odiff-bin": "^3.2.1"
   },
   "devDependencies": {