Core Operations

/**
 * Execute command with Percy visual testing environment
 * Starts Percy server, runs the specified command, then stops Percy
 * 
 * Usage: percy exec -- <command>
 * 
 * Options:
 *   --parallel          Mark as parallel build (sets PERCY_PARALLEL_TOTAL=-1)
 *   --partial           Mark as partial build (sets PERCY_PARTIAL_BUILD=1)
 *   --testing           Internal testing flag (hidden)
 * 
 * Environment variables set:
 *   PERCY_SERVER_ADDRESS    Local Percy server URL
 *   PERCY_BUILD_ID          Current build identifier
 *   PERCY_BUILD_URL         Percy dashboard URL for build
 *   PERCY_LOGLEVEL          Current logging level
 */
percy exec -- <command>

# Run tests with Percy
percy exec -- npm test
percy exec -- yarn test
percy exec -- pytest

# Run specific test files
percy exec -- npm test -- --grep "visual tests"
percy exec -- jest tests/visual/

# Run with parallel builds
percy exec --parallel -- npm test

# Run partial build (for CI matrix builds)
percy exec --partial -- npm run test:unit

/**
 * Start Percy process in background
 * Initializes Percy server and creates a new build
 * Must be paired with 'percy stop' to finalize the build
 * 
 * Usage: percy start
 * 
 * Returns: Process continues running until 'percy stop' is called
 */
percy start

# Start Percy in background
percy start

# Run your tests (Percy server is available at $PERCY_SERVER_ADDRESS)
npm test

# Stop Percy when done
percy stop

/**
 * Stop Percy process and finalize build
 * Uploads pending snapshots and marks build as complete
 * Should be called after 'percy start' and test execution
 * 
 * Usage: percy stop
 * 
 * Returns: Process exits after build finalization
 */
percy stop

# Stop Percy and finalize build
percy stop

# Can be used in scripts
percy start
npm test
percy stop

/**
 * Check if Percy process is running
 * Tests connectivity to local Percy server
 * 
 * Usage: percy ping
 * 
 * Exit codes:
 *   0 - Percy is running and responsive
 *   1 - Percy is not running or not responsive
 */
percy ping

# Check if Percy is running
percy ping
echo $?  # 0 if running, 1 if not

# Use in conditional scripts
if percy ping; then
  echo "Percy is running"
else
  echo "Percy is not running"
  percy start
fi

# Basic CI workflow
percy exec -- npm test

# Parallel CI workflow (run across multiple machines)
percy exec --parallel -- npm test

# Partial builds (for matrix builds)
percy exec --partial -- npm run test:chrome

# Long development session
percy start

# Run tests multiple times during development
npm test
npm test
npm test

# Stop when done
percy stop

# In Dockerfile or docker-compose
ENV PERCY_TOKEN=your-token
RUN percy exec -- npm test

# Set by 'percy exec' and 'percy start'
PERCY_SERVER_ADDRESS           # Local Percy server URL (e.g., http://localhost:5338)
PERCY_BUILD_ID                 # Current build identifier
PERCY_BUILD_URL                # Percy dashboard URL for current build
PERCY_LOGLEVEL                 # Current logging level

# Configuration variables (can be set by user)
PERCY_PARALLEL_TOTAL           # Number of parallel processes (-1 for auto)
PERCY_PARALLEL_NONCE           # Unique identifier for parallel builds
PERCY_PARTIAL_BUILD            # Mark build as partial (1 to enable)

# Percy exec handles errors gracefully
percy exec -- npm test
# If tests fail, Percy still finalizes the build properly

# Manual error handling with start/stop
percy start
if npm test; then
  echo "Tests passed"
else
  echo "Tests failed"
fi
percy stop  # Always finalize, regardless of test results

# Force cleanup (if percy stop hangs)
pkill -f percy