@percy/cli-doctor

@percy/cli-doctor

Percy CLI sub-command that diagnoses network, authentication, configuration, and CI readiness for running Percy builds.

Installation

@percy/cli-doctor is bundled with @percy/cli. If you use the Percy CLI you already have it:

npx percy doctor

To install standalone:

npm install --save-dev @percy/cli-doctor
# or
yarn add --dev @percy/cli-doctor

Usage

percy doctor [options]

Options:
  --proxy-server  <url>   Proxy server to test alongside direct connectivity
                          e.g. http://proxy.corp.example.com:8080
  --url           <url>   URL to open in Chrome for network activity analysis
                          (default: https://percy.io)
  --timeout       <ms>    Per-request timeout in milliseconds
                          (default: 10000, max: 300000)
  --quick                 Run only connectivity, SSL, and token auth checks
                          (~4 seconds instead of a full diagnostic run)
  --output-json   <path>  Write the full diagnostic report to a JSON file
  -v, --verbose           Show detailed debug output
  -h, --help              Show help

What it checks

1 · Configuration Validation

Detects and validates Percy configuration files (.percy.yml, .percy.yaml, percy.config.js, etc.) via cosmiconfig:

• Reports file location and format
• Warns on missing or outdated version field (recommends version 2)
• Detects project-type/config mismatches (e.g., automate-only keys like fullPage used with a web token)

Category	Meaning
config_not_found	No Percy config file detected
config_found	Config file located and loaded
config_parse_error	Config file has YAML/JSON syntax errors
config_version_invalid	version field is missing or non-numeric
config_version_outdated	Config uses an outdated version (< 2)
config_key_automate_only	Config contains Automate-only keys but token is not Automate
config_key_web_only	Config contains Web-only keys but token is not a Web token

2 · CI Environment Detection

Detects your CI provider and validates CI-related settings:

• Identifies 10+ CI systems (GitHub Actions, GitLab CI, Jenkins, CircleCI, Travis, etc.)
• Validates git availability for commit/branch detection
• Checks parallel build configuration (PERCY_PARALLEL_TOTAL + PERCY_PARALLEL_NONCE)

Category	Meaning
ci_not_detected	Not running in a CI environment
ci_detected	CI system identified
ci_commit_missing	Commit SHA could not be detected
ci_commit_found	Commit SHA available
ci_branch_missing	Branch name could not be detected
ci_parallel_nonce_missing	PERCY_PARALLEL_TOTAL set without PERCY_PARALLEL_NONCE
ci_parallel_config_valid	Both parallel env vars are set correctly
ci_git_available	Git repository detected
ci_git_check_skipped	Git check suppressed via PERCY_SKIP_GIT_CHECK=true
ci_git_unavailable	Git not installed or not in a git repository

3 · Environment Variable Audit

Inventories all Percy-specific environment variables:

• Lists all set PERCY_* vars (names only — values are never exposed)
• Validates PERCY_PARALLEL_TOTAL is a positive integer
• Flags manual overrides (PERCY_COMMIT, PERCY_BRANCH, PERCY_PULL_REQUEST)
• Warns when NODE_TLS_REJECT_UNAUTHORIZED=0 disables SSL validation

Category	Meaning
env_system_info	OS, Node version, CPU, and RAM summary
env_no_percy_vars	No PERCY_* environment variables detected
env_vars_listed	Lists names of all set PERCY_* variables
env_parallel_total_invalid	PERCY_PARALLEL_TOTAL is not a valid positive integer
env_manual_overrides	Manual override vars active (e.g. PERCY_COMMIT, PERCY_BRANCH)
env_tls_disabled	NODE_TLS_REJECT_UNAUTHORIZED=0 — SSL validation globally disabled

4 · Network Connectivity

Probes each required Percy / BrowserStack domain:

Domain	Purpose
https://percy.io	Percy API
https://www.browserstack.com	BrowserStack API
https://hub.browserstack.com	BrowserStack Automate

Failure modes are classified as:

• ENOTFOUND → DNS resolution failure; suggest whitelisting on corporate DNS
• ETIMEDOUT / ECONNRESET → Firewall dropping packets; list CIDRs to whitelist
• via proxy only → Proxy required, suggests setting HTTPS_PROXY

5 · SSL / TLS

Scenario	Outcome
NODE_TLS_REJECT_UNAUTHORIZED=0 is set	Warning – SSL verification is disabled globally
SSL certificate error connecting to percy.io	Fail – likely a MITM proxy/VPN; suggests remediation
SSL handshake succeeds	Pass

When a certificate error is detected, the command prints actionable suggestions (contact network admin, add proxy cert to trust store, set NODE_EXTRA_CA_CERTS).

6 · Proxy Detection

Detects proxy configuration from (in priority order):

• Environment variables: HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, NO_PROXY
• macOS system proxy: scutil --proxy, networksetup -getautoproxyurl
• Linux (GNOME): gsettings org.gnome.system.proxy
• Linux (/etc): /etc/environment
• Windows registry: HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings

Each discovered proxy is validated by attempting connections to percy.io and browserstack.com through it.

7 · PAC / WPAD Auto-Proxy Configuration

Detects PAC file URLs from:

Source	Detection method
macOS system	networksetup -getautoproxyurl <interface>
macOS plist	/Library/Preferences/SystemConfiguration/preferences.plist
Linux GNOME	gsettings org.gnome.system.proxy autoconfig-url
Windows	HKCU\…\Internet Settings\AutoConfigURL
Chrome / Chromium	Default/Preferences JSON (macOS, Linux, Windows)
Firefox	~/.mozilla/firefox/*/prefs.js (network.proxy.autoconfig_url)

The PAC script is fetched and evaluated in a sandboxed Node.js vm context using shims for all standard PAC helper functions. The result of FindProxyForURL("https://percy.io/", "percy.io") is reported.

If a PAC file routes percy.io through a proxy the command surfaces the exact HTTPS_PROXY=… export statement to add to your CI environment.

8 · Token Authentication

Validates the PERCY_TOKEN environment variable:

• Presence: Checks the token is set
• Format: Detects project type from token prefix (web_, auto_, app_, ss_, vmw_, res_) and suggests the correct CLI command
• Authentication: Makes a live API call to percy.io/api/v1/tokens to verify the token is valid (uses proxy if one was discovered in earlier checks)

Token values are never included in output — only the project type and pass/fail status.

Category	Meaning
token_missing	PERCY_TOKEN is not set or is blank
token_type_info	Token prefix decoded — project type and suggested CLI command
token_auth_pass	Token authenticated successfully; role shown
token_auth_fail	Token rejected (HTTP 401 or 403)
token_auth_unexpected_status	Percy API returned an unexpected HTTP status
token_auth_network_error	Could not reach Percy API to validate token
check_skipped	Token validation skipped because percy.io is unreachable

9 · Browser Network (Chrome CDP)

Launches headless Chrome to test end-to-end network connectivity through the browser process, including proxy and PAC resolution as Chrome would see it.

Quick Mode

Use --quick to run only the essential checks (connectivity, SSL, and token auth) in ~4 seconds:

npx percy doctor --quick

This is useful for fast triage in CI pipelines or when you just want to verify your token and network are working.

Auto-Doctor on Build Failure

Set PERCY_AUTO_DOCTOR=true to automatically run diagnostics when a Percy build fails:

export PERCY_AUTO_DOCTOR=true
npx percy exec -- your-test-command

When enabled, a build failure triggers a diagnostic run and prints actionable findings inline. This is opt-in and has no effect on successful builds.

Example output

  Percy Doctor — diagnostic check

── Configuration
  ℹ Configuration file detected: /project/.percy.yml
  ✔ Config version: 2 (current)

── CI Environment
  ℹ CI system detected: GitHub Actions
  ✔ Git is available for commit detection.

── Environment Variables
  ℹ Percy environment variables set: PERCY_TOKEN, PERCY_PARALLEL_TOTAL

── SSL / TLS
  ✔ SSL handshake with percy.io succeeded (47ms).

── Network Connectivity
  ✔ Percy API is reachable directly (HTTP 200, 51ms).
  ✔ BrowserStack API is reachable directly (HTTP 200, 72ms).
  ✔ BrowserStack Automate is reachable directly (HTTP 200, 89ms).

── Proxy Configuration
  ℹ No proxy configuration detected in environment or system settings.

── PAC / Auto-Proxy Configuration
  ℹ No PAC (Proxy Auto-Configuration) file detected.

── Token Authentication
  ℹ Token detected (project type: web). Use `percy exec` to run snapshots.
  ✔ Token authentication successful.

── Browser Network
  ✔ Chrome loaded percy.io successfully.

  ✔ 8 passed · 0 warnings · 0 failures (4.2s)

License

MIT