tessl/npm-percy--cli

Command line interface for Percy visual testing platform that enables developers to capture, upload, and manage visual snapshots for web applications.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Configuration

Name: tessl/npm-percy--cli
Author: tessl

Tools for creating, validating, and migrating Percy configuration files across different formats. Percy supports multiple configuration file formats and provides commands to manage configuration lifecycle.

Capabilities

Config Create

Create a new Percy configuration file in the format of your choice. Automatically generates a configuration file with common options and helpful comments.

/**
 * Create new Percy configuration file
 * Generates a config file with default settings and documentation
 * 
 * Usage: percy config create [filepath]
 * 
 * Arguments:
 *   filepath                      Optional path where to create config file
 * 
 * Options (format selection - mutually exclusive):
 *   --rc                         Create .percyrc file (JSON format)
 *   --yaml                       Create .percy.yaml file
 *   --yml                        Create .percy.yml file
 *   --json                       Create .percy.json file
 *   --js                         Create .percy.js file (JavaScript module)
 * 
 * Default: Creates .percy.yml if no format specified
 */
percy config create [filepath]

Usage Examples:

# Create default config (.percy.yml)
percy config create

# Create specific format configs
percy config create --rc         # .percyrc (JSON)
percy config create --yaml       # .percy.yaml
percy config create --yml        # .percy.yml
percy config create --json       # .percy.json
percy config create --js         # .percy.js

# Create config at specific path
percy config create config/percy.yaml --yaml
percy config create .percyrc --rc

Config Validate

Validate a Percy configuration file against the current schema. Checks syntax, validates option values, and reports any errors or warnings.

/**
 * Validate Percy configuration file
 * Checks config syntax and validates against current schema
 * 
 * Usage: percy config validate [filepath]
 * 
 * Arguments:
 *   filepath                      Optional path to config file to validate
 *                                Default: searches for config in current directory
 * 
 * Exit codes:
 *   0 - Configuration is valid
 *   1 - Configuration has errors or file not found
 */
percy config validate [filepath]

Usage Examples:

# Validate config in current directory (auto-discovery)
percy config validate

# Validate specific config file
percy config validate .percy.yml
percy config validate config/percy.json
percy config validate package.json  # Validates 'percy' field

Config Migrate

Migrate configuration file to the latest version and format. Handles version upgrades and format conversions while preserving all settings.

/**
 * Migrate configuration to latest version
 * Updates config schema version and converts deprecated options
 * 
 * Usage: percy config migrate [filepath] [output]
 * 
 * Arguments:
 *   filepath                      Path to config file to migrate
 *   output                        Optional output path for migrated config
 * 
 * Options:
 *   --dry-run, -d                Print new config without writing to file
 * 
 * Exit codes:
 *   0 - Migration completed successfully
 *   1 - Migration failed or no changes needed
 */
percy config migrate [filepath] [output]

Usage Examples:

# Migrate config in-place
percy config migrate .percy.yml

# Migrate to new file
percy config migrate old-config.json new-config.yml

# Preview migration without writing
percy config migrate .percy.yml --dry-run

# Migrate with different output format
percy config migrate .percyrc percy.config.js

Configuration File Formats

YAML Format

# .percy.yml or .percy.yaml
version: 2

snapshot:
  widths: [375, 768, 1280]
  minHeight: 1024
  percyCSS: |
    .dynamic-content { display: none; }
    .timestamp { visibility: hidden; }

discovery:
  allowedHostnames:
    - "*.example.com"
    - "cdn.assets.com"
  disallowedHostnames:
    - "ads.example.com"
  networkIdleTimeout: 100
  concurrency: 5

agent:
  assetDiscovery:
    networkIdleTimeout: 100
    pagePoolSizeMin: 1
    pagePoolSizeMax: 5

JSON Format

{
  "version": 2,
  "snapshot": {
    "widths": [375, 768, 1280],
    "minHeight": 1024,
    "percyCSS": ".ads { display: none; }"
  },
  "discovery": {
    "allowedHostnames": ["*.example.com"],
    "disallowedHostnames": ["ads.example.com"],
    "networkIdleTimeout": 100,
    "concurrency": 5
  }
}

JavaScript Format

// .percy.js or percy.config.js
export default {
  version: 2,
  snapshot: {
    widths: [375, 768, 1280],
    minHeight: 1024,
    percyCSS: `
      .dynamic-content { display: none; }
      .timestamp { visibility: hidden; }
    `
  },
  discovery: {
    allowedHostnames: ['*.example.com'],
    disallowedHostnames: ['ads.example.com'],
    networkIdleTimeout: 100,
    concurrency: 5
  }
};

Package.json Integration

{
  "name": "my-app",
  "scripts": {
    "test": "percy exec -- jest"
  },
  "percy": {
    "version": 2,
    "snapshot": {
      "widths": [375, 768, 1280]
    }
  }
}

Configuration Options

Core Configuration

# Schema version (required)
version: 2

# Snapshot configuration
snapshot:
  widths: [375, 768, 1280]        # Viewport widths to capture
  minHeight: 1024                 # Minimum screenshot height
  percyCSS: string                # CSS to inject into pages
  enableLayout: boolean           # Enable layout diffing
  
# Discovery configuration  
discovery:
  allowedHostnames: string[]      # Allowed hostname patterns
  disallowedHostnames: string[]   # Disallowed hostname patterns
  networkIdleTimeout: number      # Network idle timeout (ms)
  concurrency: number             # Asset discovery concurrency
  userAgent: string               # Custom user agent
  requestHeaders: object          # Custom request headers
  authorization: object           # Authorization headers
  captureMockedServiceWorker: boolean  # Capture mocked service workers
  captureSrcset: boolean          # Capture responsive images
  
# Agent configuration (advanced)
agent:
  assetDiscovery:
    networkIdleTimeout: number    # Asset network idle timeout
    pagePoolSizeMin: number       # Minimum browser pages
    pagePoolSizeMax: number       # Maximum browser pages
    cacheResponses: boolean       # Cache HTTP responses
  clientInfo: string              # Client identification
  environmentInfo: string         # Environment identification

Discovery Configuration

Control how Percy discovers and processes web assets:

discovery:
  # Hostname filtering
  allowedHostnames:
    - "*.mysite.com"
    - "cdn.assets.com"
    - "fonts.googleapis.com"
  
  disallowedHostnames:
    - "ads.example.com"
    - "analytics.google.com"
    - "*.facebook.com"
  
  # Network timing
  networkIdleTimeout: 100         # Wait for network idle (ms)
  
  # Performance tuning
  concurrency: 5                  # Parallel asset requests
  
  # Request customization
  userAgent: "Percy/1.0 Custom"
  requestHeaders:
    "X-Percy-Test": "true"
    "Authorization": "Bearer token123"

Snapshot Configuration

Control visual snapshot capture settings:

snapshot:
  # Responsive testing
  widths: [375, 768, 1024, 1280]
  
  # Screenshot sizing
  minHeight: 1024                 # Minimum screenshot height
  
  # Visual modifications
  percyCSS: |
    /* Hide dynamic content */
    .timestamp { visibility: hidden; }
    .ads { display: none; }
    .loading-spinner { display: none; }
    
    /* Stabilize animations */
    *, *::before, *::after {
      animation-duration: 0s !important;
      animation-delay: 0s !important;
      transition-duration: 0s !important;
      transition-delay: 0s !important;
    }
  
  # Advanced options
  enableLayout: true              # Enable layout-based diffing

Configuration Discovery

Percy searches for configuration files in this order:

.percyrc (JSON)
.percy.json
.percy.yaml
.percy.yml
.percy.js
.percy.cjs
percy.config.js
percy.config.cjs
package.json (percy field)

Environment Override

Environment variables can override configuration values:

# Override specific config values
PERCY_LOGLEVEL=debug percy exec -- npm test
PERCY_CONFIG=./custom-config.yml percy exec -- npm test

# Discovery overrides
PERCY_NETWORK_IDLE_TIMEOUT=200 percy snapshot ./dist
PERCY_CONCURRENCY=10 percy snapshot ./dist

Migration Examples

Version 1 to Version 2

# Old format (version 1)
widths: [375, 768, 1280]
minHeight: 1024
css: ".ads { display: none; }"

# New format (version 2)
version: 2
snapshot:
  widths: [375, 768, 1280]
  minHeight: 1024
  percyCSS: ".ads { display: none; }"

Migration handles:

Schema version updates
Option renames (css → percyCSS)
Structure changes (flat → nested)
Deprecated option warnings

Format Conversion

# Convert JSON to YAML
percy config migrate .percy.json .percy.yml

# Convert package.json to standalone config
percy config migrate package.json .percy.yml

# Convert JavaScript to JSON
percy config migrate percy.config.js .percy.json

Validation Examples

Valid Configuration

version: 2
snapshot:
  widths: [375, 768, 1280]
  minHeight: 1024
discovery:
  networkIdleTimeout: 100

Invalid Configurations

# Missing version
snapshot:
  widths: [375, 768, 1280]
# Error: Missing required 'version' field

# Invalid width values  
version: 2
snapshot:
  widths: [-100, 0, "invalid"]
# Error: Widths must be positive integers

# Invalid timeout
version: 2  
discovery:
  networkIdleTimeout: "invalid"
# Error: networkIdleTimeout must be a number

Integration Patterns

Development Workflow

# Create initial config
percy config create --yaml

# Edit config file
vim .percy.yml

# Validate before committing
percy config validate

# Test configuration
percy exec -- npm test

CI/CD Integration

# Validate config in CI
percy config validate || exit 1

# Use different configs per environment
PERCY_CONFIG=.percy.staging.yml percy exec -- npm test  # Staging
PERCY_CONFIG=.percy.prod.yml percy exec -- npm test     # Production

Team Collaboration

# Standardize team config
percy config create --yaml
git add .percy.yml
git commit -m "Add Percy configuration"

# Validate in pre-commit hook
percy config validate || {
  echo "Percy config validation failed"
  exit 1
}

Install with Tessl CLI