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

Build Management

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

Commands for managing Percy builds, including waiting for completion, finalizing parallel builds, and reviewing build results. These commands provide control over the Percy build lifecycle and enable automation workflows.

Capabilities

Build Wait

Wait for a Percy build to complete processing and optionally exit with an error code if visual differences are found.

/**
 * Wait for build to finish processing
 * Polls Percy API until build completes, with configurable timeout and behavior
 * 
 * Usage: percy build wait
 * 
 * Options:
 *   --build, -b <build-id>        Specific build ID to wait for
 *   --project, -p <project>       Build project slug (alternative to build-id)
 *   --commit, -c <sha>            Build commit SHA (alternative to build-id)
 *   --timeout, -t <ms>            Timeout before exiting (default: 10 minutes)
 *   --interval, -i <ms>           Polling interval (default: 10 seconds)
 *   --fail-on-changes, -f         Exit with error code if visual diffs found
 *   --pass-if-approved            Don't fail if build is approved
 * 
 * Exit codes:
 *   0 - Build completed successfully (no diffs or approved)
 *   1 - General error (network, authentication, etc.)
 *   2 - Build has visual differences (with --fail-on-changes)
 */
percy build wait

Usage Examples:

# Wait for current build (uses PERCY_BUILD_ID)
percy build wait

# Wait for specific build
percy build wait --build build_12345

# Wait with timeout
percy build wait --timeout 300000  # 5 minutes

# Fail CI if visual differences found
percy build wait --fail-on-changes

# Wait but pass if build is approved
percy build wait --fail-on-changes --pass-if-approved

# Wait for build by project and commit
percy build wait --project my-app --commit abc123

Build Finalize

Finalize all parallel builds for the current project. Used in parallel build workflows where multiple Percy processes run simultaneously.

/**
 * Finalize parallel builds
 * Marks all parallel build shards as complete and triggers final processing
 * Used when PERCY_PARALLEL_TOTAL is set for parallel builds
 * 
 * Usage: percy build finalize
 * 
 * Options:
 *   --all                         Finalize all builds (not just parallel)
 */
percy build finalize

Usage Examples:

# Finalize parallel builds (typical usage)
percy build finalize

# Finalize all builds
percy build finalize --all

Build ID

Print the build ID from the local Percy process. Useful for scripting and automation.

/**
 * Print build ID from local Percy process
 * Outputs the current build identifier to stdout
 * 
 * Usage: percy build id
 * 
 * Output: Build ID string (e.g., "build_12345")
 */
percy build id

Usage Examples:

# Get current build ID
BUILD_ID=$(percy build id)
echo "Current build: $BUILD_ID"

# Use in scripts
percy start
PERCY_BUILD_ID=$(percy build id)
npm test
percy stop
echo "Build completed: $PERCY_BUILD_ID"

Build Review Commands

Approve, reject, or delete builds using Percy's build review API. Requires authentication credentials.

/**
 * Approve a build
 * Marks all visual differences in the build as approved
 * 
 * Usage: percy build approve <build-id>
 * 
 * Arguments:
 *   build-id                      Build ID to approve (required)
 * 
 * Options:
 *   --username <username>         Authentication username (or BROWSERSTACK_USERNAME env var)
 *   --access-key <key>           Authentication access key (or BROWSERSTACK_ACCESS_KEY env var)
 */
percy build approve <build-id>

/**
 * Reject a build
 * Marks the build as rejected, indicating visual differences are not acceptable
 * 
 * Usage: percy build reject <build-id>
 * 
 * Arguments:
 *   build-id                      Build ID to reject (required)
 * 
 * Options:
 *   --username <username>         Authentication username (or BROWSERSTACK_USERNAME env var)
 *   --access-key <key>           Authentication access key (or BROWSERSTACK_ACCESS_KEY env var)
 */
percy build reject <build-id>

/**
 * Unapprove a build
 * Removes approval status from a previously approved build
 * 
 * Usage: percy build unapprove <build-id>
 * 
 * Arguments:
 *   build-id                      Build ID to unapprove (required)
 * 
 * Options:
 *   --username <username>         Authentication username (or BROWSERSTACK_USERNAME env var)
 *   --access-key <key>           Authentication access key (or BROWSERSTACK_ACCESS_KEY env var)
 */
percy build unapprove <build-id>

/**
 * Delete a build
 * Permanently removes a build and all its snapshots
 * 
 * Usage: percy build delete <build-id>
 * 
 * Arguments:
 *   build-id                      Build ID to delete (required)
 * 
 * Options:
 *   --username <username>         Authentication username (or BROWSERSTACK_USERNAME env var)
 *   --access-key <key>           Authentication access key (or BROWSERSTACK_ACCESS_KEY env var)
 */
percy build delete <build-id>

Usage Examples:

# Approve a build
percy build approve build_12345 --username admin --access-key secret123

# Reject a build with visual differences
percy build reject build_12345 --username reviewer --access-key secret123

# Remove approval from a build
percy build unapprove build_12345 --username admin --access-key secret123

# Delete a test build
percy build delete build_12345 --username admin --access-key secret123

Integration Patterns

CI/CD Workflows

Basic Build Wait

# In CI pipeline
percy exec -- npm test
percy build wait --fail-on-changes

Parallel Build Workflow

# Job 1 (Chrome tests)
PERCY_PARALLEL_TOTAL=3 percy exec -- npm run test:chrome

# Job 2 (Firefox tests)  
PERCY_PARALLEL_TOTAL=3 percy exec -- npm run test:firefox

# Job 3 (Safari tests)
PERCY_PARALLEL_TOTAL=3 percy exec -- npm run test:safari

# Finalization job (runs after all parallel jobs complete)
percy build finalize
percy build wait --fail-on-changes

Matrix Build Strategy

# GitHub Actions example
strategy:
  matrix:
    browser: [chrome, firefox, safari]
    
steps:
  - name: Run tests
    env:
      PERCY_PARALLEL_TOTAL: 3
    run: percy exec -- npm run test:${{ matrix.browser }}
    
  - name: Finalize builds
    if: strategy.job-index == 0  # Only run on first job
    run: |
      percy build finalize
      percy build wait --fail-on-changes

Build Review Automation

# Auto-approve builds on main branch
if [[ "$BRANCH" == "main" ]]; then
  BUILD_ID=$(percy build id)
  percy build wait
  percy build approve "$BUILD_ID" --username ci-bot --access-key "$PERCY_ACCESS_KEY"
fi

# Auto-reject builds with too many changes
percy build wait
if [[ $? -eq 2 ]]; then  # Visual differences found
  BUILD_ID=$(percy build id)
  percy build reject "$BUILD_ID" --username ci-bot --access-key "$PERCY_ACCESS_KEY"
fi

Cleanup Automation

# Delete old test builds
for build_id in $(get_old_test_builds); do
  percy build delete "$build_id" --username cleanup-bot --access-key "$PERCY_ACCESS_KEY"
done

Environment Variables

Build Identification

PERCY_BUILD_ID                     # Current build identifier
PERCY_BUILD_URL                    # Percy dashboard URL for build

Parallel Build Configuration

PERCY_PARALLEL_TOTAL               # Total number of parallel processes
PERCY_PARALLEL_NONCE               # Unique identifier for parallel builds

Authentication

PERCY_TOKEN                        # Percy project token

# Build review authentication (BrowserStack credentials)
BROWSERSTACK_USERNAME              # BrowserStack username for build review operations
BROWSERSTACK_ACCESS_KEY            # BrowserStack access key for build review operations

Build States and Transitions

Build Lifecycle

Created: Build is created but no snapshots yet
Processing: Snapshots are being captured and uploaded
Pending: All snapshots uploaded, waiting for processing
Finished: Processing complete, ready for review
Approved: All visual differences approved
Rejected: Build marked as rejected

Parallel Build States

Parallel Started: Multiple parallel processes begin
Shards Processing: Each parallel process uploads snapshots
Finalization: percy build finalize triggers final processing
Completed: All parallel shards processed together

Error Handling

Common Error Scenarios

# Handle build wait timeout
percy build wait --timeout 600000 || {
  echo "Build timed out after 10 minutes"
  exit 1
}

# Handle authentication errors
percy build approve build_12345 --username user --access-key key || {
  echo "Failed to approve build - check credentials"
  exit 1
}

# Handle missing build
percy build wait --build nonexistent_build || {
  echo "Build not found"
  exit 1
}

Exit Code Handling

# Check for visual differences
percy build wait --fail-on-changes
case $? in
  0) echo "Build passed - no visual differences" ;;
  1) echo "Build error - check logs" ;;
  2) echo "Build has visual differences" ;;
esac

Authentication

Build review commands require BrowserStack credentials beyond the regular PERCY_TOKEN:

Credentials Setup

# Set BrowserStack credentials as environment variables
export BROWSERSTACK_USERNAME="your-browserstack-username"
export BROWSERSTACK_ACCESS_KEY="your-browserstack-access-key"

# Use in commands (credentials can also be passed via flags)
percy build approve build_12345 \
  --username "$BROWSERSTACK_USERNAME" \
  --access-key "$BROWSERSTACK_ACCESS_KEY"