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

Static Snapshots

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

Capture visual snapshots of static directories, file lists, or sitemaps without requiring a test runner. Perfect for static sites, documentation sites, or when you have pre-built assets to test.

Capabilities

Percy Snapshot

Snapshot static content from directories, configuration files, or sitemaps. This command discovers and captures visual snapshots of web content without needing to run a full test suite.

/**
 * Snapshot static directory, file list, or sitemap
 * Discovers web content and captures visual snapshots
 * 
 * Usage: percy snapshot <dir|file|sitemap>
 * 
 * Arguments:
 *   dir|file|sitemap    Static directory path, snapshots file, or sitemap URL (required)
 * 
 * Options:
 *   --base-url, -b <url>       Base URL for hosted pages
 *   --include <pattern>        Glob patterns to include (multiple)
 *   --exclude <pattern>        Glob patterns to exclude (multiple)
 *   --clean-urls               Remove file extensions from snapshot names
 */
percy snapshot <dir|file|sitemap>

Static Directory Snapshots

Snapshot all HTML files in a directory, typically used for static site generators or pre-built sites.

Usage Examples:

# Snapshot a build directory
percy snapshot ./dist
percy snapshot ./public
percy snapshot ./build

# With base URL for absolute links
percy snapshot ./dist --base-url https://example.com

# Include/exclude specific patterns
percy snapshot ./dist --include "**/*.html" --exclude "**/admin/**"

# Clean URLs (remove .html extensions)
percy snapshot ./dist --clean-urls

Directory Structure Example:

dist/
├── index.html           → snapshot: "/"
├── about.html           → snapshot: "/about"
├── products/
│   ├── index.html       → snapshot: "/products"
│   └── laptop.html      → snapshot: "/products/laptop"
└── assets/
    ├── style.css        → discovered as asset
    └── app.js           → discovered as asset

Configuration File Snapshots

Use configuration files to define complex snapshot scenarios with custom options per page.

JavaScript Configuration

// snapshots.js
export default [
  {
    name: 'Homepage',
    url: 'http://localhost:3000/',
    widths: [375, 768, 1280]
  },
  {
    name: 'Product Page',
    url: 'http://localhost:3000/products/laptop',
    percyCSS: '.dynamic-content { display: none; }'
  },
  {
    name: 'Dashboard',
    url: 'http://localhost:3000/dashboard',
    additionalSnapshots: [
      { suffix: ' - Mobile', widths: [375] },
      { suffix: ' - Desktop', widths: [1280] }
    ]
  }
];

# Use JavaScript config
percy snapshot snapshots.js

JSON Configuration

{
  "snapshots": [
    {
      "name": "Homepage",
      "url": "http://localhost:3000/",
      "widths": [375, 768, 1280]
    },
    {
      "name": "About Page", 
      "url": "http://localhost:3000/about",
      "minHeight": 1024
    }
  ]
}

# Use JSON config
percy snapshot snapshots.json

YAML Configuration

# snapshots.yaml
snapshots:
  - name: Homepage
    url: http://localhost:3000/
    widths: [375, 768, 1280]
  - name: Contact Form
    url: http://localhost:3000/contact
    percyCSS: |
      .captcha { display: none; }
      .timestamp { visibility: hidden; }

# Use YAML config
percy snapshot snapshots.yaml

Sitemap Snapshots

Automatically discover pages from XML sitemaps, perfect for large sites with dynamic content.

Usage Examples:

# Snapshot from sitemap URL
percy snapshot https://example.com/sitemap.xml

# Local sitemap file
percy snapshot ./sitemap.xml

# With filtering
percy snapshot https://example.com/sitemap.xml --include "**/blog/**" --exclude "**/admin/**"

Sitemap Example:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/</loc>
    <priority>1.0</priority>
  </url>
  <url>
    <loc>https://example.com/about</loc>
    <priority>0.8</priority>
  </url>
  <url>
    <loc>https://example.com/products/laptop</loc>
    <priority>0.6</priority>
  </url>
</urlset>

Configuration Options

Base URL Option

When snapshots reference relative links, use --base-url to resolve them correctly:

# Static files with relative links
percy snapshot ./dist --base-url https://mysite.com

# Local development server
percy snapshot ./public --base-url http://localhost:3000

Include/Exclude Patterns

Use glob patterns to control which content gets snapshotted:

# Include only specific patterns
percy snapshot ./dist --include "**/*.html" --include "**/pages/**"

# Exclude admin or private sections
percy snapshot ./dist --exclude "**/admin/**" --exclude "**/private/**"

# Complex filtering
percy snapshot ./dist \
  --include "**/*.html" \
  --exclude "**/test/**" \
  --exclude "**/temp/**"

Clean URLs

Remove file extensions from snapshot names for cleaner URLs:

# Without clean URLs
percy snapshot ./dist
# Creates: "index.html", "about.html", "contact.html"

# With clean URLs  
percy snapshot ./dist --clean-urls
# Creates: "/", "/about", "/contact"

Advanced Configuration

Per-Snapshot Options

In configuration files, you can specify detailed options for each snapshot:

// advanced-snapshots.js
export default [
  {
    name: 'Homepage - Desktop',
    url: 'http://localhost:3000/',
    widths: [1280],
    minHeight: 800,
    percyCSS: `
      .ads { display: none; }
      .dynamic-timestamp { visibility: hidden; }
    `
  },
  {
    name: 'Homepage - Mobile',
    url: 'http://localhost:3000/',
    widths: [375],
    enableLayout: true,
    additionalSnapshots: [
      { 
        suffix: ' - Menu Open',
        execute: () => {
          document.querySelector('.menu-button').click();
        }
      }
    ]
  }
];

Discovery Options

Control how Percy discovers and processes assets:

# Custom discovery settings
percy snapshot ./dist \
  --allowed-hostname "*.example.com" \
  --disallowed-hostname "ads.example.com" \
  --network-idle-timeout 1000 \
  --disable-cache

Integration Examples

Static Site Generators

# Gatsby
gatsby build
percy snapshot ./public --base-url https://mysite.com

# Next.js static export
next build
next export
percy snapshot ./out --clean-urls

# Jekyll
bundle exec jekyll build
percy snapshot ./_site --base-url https://mysite.com

# Hugo
hugo
percy snapshot ./public --base-url https://mysite.com

Documentation Sites

# GitBook
gitbook build
percy snapshot ./_book

# VuePress
vuepress build
percy snapshot ./.vuepress/dist --clean-urls

# Docusaurus
npm run build
percy snapshot ./build --base-url https://docs.example.com

Multi-Environment Testing

# Test multiple environments
percy snapshot https://staging.example.com/sitemap.xml
percy snapshot https://production.example.com/sitemap.xml

# Local vs production comparison
percy snapshot ./dist --base-url http://localhost:3000
percy snapshot https://mysite.com/sitemap.xml