Commands Overview

This page provides App Percy commands overview.

Use this reference guide to understand and implement the essential App Percy commands that enhance your visual testing workflow.

Commands

percy config - manage configuration files.
percy build - interact with Percy builds.
percy exec- Use Percy exec command to capture and upload snapshots
percy options - use Percy options as a part of the device capability
run percy - run your tests on Percy using either your make file or by utilizing the Percy start and stop commands.

This applies only when using the Percy SDK.

percy config

Percy CLI commands for creating, validating, and updating Percy configuration files:

percy config:create
percy config:validate
percy config:migrate

percy config:create

Create a Percy config file

Copy

    ```
Usage:
  $ percy config:create [options] [filepath]
Arguments:
  filepath       Optional config filepath
Options:
  --rc           Create a .percyrc file
  --yaml         Create a .percy.yaml file
  --yml          Create a .percy.yml file
  --json         Create a .percy.json file
  --js           Create a .percy.js file
Global options:
  -v, --verbose  Log everything
  -q, --quiet    Log errors only
  -s, --silent   Log nothing
  -h, --help     Display command help
Examples:
  $ percy config:create
  $ percy config:create --yaml
  $ percy config:create --json
  $ percy config:create --js
  $ percy config:create --rc
  $ percy config:create ./config/percy.yml

  

percy config:validate

Validate a Percy config file

Copy

    ```
Usage:
  $ percy config:validate [options] [filepath]
Arguments:
  filepath       Config filepath, detected by default
Global options:
  -v, --verbose  Log everything
  -q, --quiet    Log errors only
  -s, --silent   Log nothing
  -h, --help     Display command help
Examples:
  $ percy config:validate
  $ percy config:validate ./config/percy.yml

  

percy config:migrate

Migrate a Percy config file to the latest version Validate a Percy config file

Copy

    ```
Usage:
  $ percy config:migrate [options] [filepath] [output]
Arguments:
  filepath       Current config filepath, detected by default
  output         New config filepath to write to, defaults to 'filepath'
Options:
  -d, --dry-run  Print the new config without writing it
Global options:
  -v, --verbose  Log everything
  -q, --quiet    Log errors only
  -s, --silent   Log nothing
  -h, --help     Display command help
Examples:
  $ percy config:migrate
  $ percy config:migrate --dry-run
  $ percy config:migrate ./config/percy.yml
  $ percy config:migrate .percy.yml .percy.js

  

percy build

Commands for interacting with Percy builds:

percy build:finalize
percy build:wait

percy build:finalize

Finalize parallel Percy builds

Copy

    ```
Usage:
  $ percy build:finalize [options]
Global options:
  -v, --verbose  Log everything
  -q, --quiet    Log errors only
  -s, --silent   Log nothing
  -h, --help     Display command help

  

percy build:wait

Wait for a build to be finished

Copy

    ```
Usage:
  $ percy build:wait [options]
Options:
  -b, --build <id>       Build ID
  -p, --project <slug>   Build project slug, requires '--commit'
  -c, --commit <sha>     Build commit sha, requires '--project'
  -t, --timeout <ms>     Timeout before exiting without updates, defaults to 10 minutes
  -i, --interval <ms>    Interval at which to poll for updates, defaults to 10 second
  -f, --fail-on-changes  Exit with an error when diffs are found
  --pass-if-approved     Doesn't Exit with an error if the build is approved, requires '--fail-on-changes'
Global options:
  -v, --verbose          Log everything
  -q, --quiet            Log errors only
  -s, --silent           Log nothing
  -h, --help             Display command help
Examples:
  $ percy build:wait --build 2222222
  $ percy build:wait --project org/project --commit HEAD

  

percy exec

The Percy CLI is used to capture and upload snapshots to percy.io from the command line.

Installation

Copy

    ```sh-session
$ npm install --save-dev @percy/cli @percy/appium-app

Command

percy app:exec - Start and stop Percy around a supplied command
percy app:exec:start - Starts a local Percy snapshot server
percy app:exec:stop - Stops a local running Percy snapshot server
percy app:exec:ping - Pings a local running Percy snapshot server

percy exec

Copy

    ```sh-session
Usage:
  $ percy app:exec [options] -- <command>
Subcommands:
  app:exec:start [options]               Starts a local Percy snapshot server
  app:exec:stop [options]                Stops a local running Percy snapshot server
  app:exec:ping [options]                Pings a local running Percy snapshot server
  help [command]                     Display command help
Options:
  -P, --port [number]                Local CLI server port (default: 5338)
  --parallel                         Marks the build as one of many parallel builds
  --partial                          Marks the build as a partial build
Percy options:
  -c, --config <file>                Config file path
  -d, --dry-run                      Print snapshot names only
  -h, --allowed-hostname <hostname>  Allowed hostnames to capture in asset discovery
  -t, --network-idle-timeout <ms>    Asset discovery network idle timeout
  --disable-cache                    Disable asset discovery caches
  --debug                            Debug asset discovery and do not upload snapshots
Global options:
  -v, --verbose                      Log everything
  -q, --quiet                        Log errors only
  -s, --silent                       Log nothing
  --help                             Display command help
Examples:
  $ percy app:exec -- echo "percy is running around this echo command"
  $ percy app:exec -- yarn test

  

percy app:exec:start

Copy

    ```sh-session
Usage:
  $ percy app:exec:start [options]
Options:
  -P, --port [number]                Local CLI server port (default: 5338)
Percy options:
  -c, --config <file>                Config file path
  -d, --dry-run                      Print snapshot names only
  -h, --allowed-hostname <hostname>  Allowed hostnames to capture in asset discovery
  -t, --network-idle-timeout <ms>    Asset discovery network idle timeout
  --disable-cache                    Disable asset discovery caches
  --debug                            Debug asset discovery and do not upload snapshots
Global options:
  -v, --verbose                      Log everything
  -q, --quiet                        Log errors only
  -s, --silent                       Log nothing
  --help                             Display command help
Examples:
  $ percy app:exec:start &> percy.log

  

percy app:exec:stop

Copy

    ```sh-session
Usage:
  $ percy app:exec:stop [options]
Options:
  -P, --port [number]  Local CLI server port (default: 5338)
Global options:
  -v, --verbose        Log everything
  -q, --quiet          Log errors only
  -s, --silent         Log nothing
  -h, --help           Display command help

  

percy app:exec:ping

Copy

    ```sh-session
Usage:
  $ percy app:exec:ping [options]
Options:
  -P, --port [number]  Local CLI server port (default: 5338)
Global options:
  -v, --verbose        Log everything
  -q, --quiet          Log errors only
  -s, --silent         Log nothing
  -h, --help           Display command help

  

percy options

Percy Options is part of the device capability configured for App Automate or any similar service.

Copy

    ```json
desiredCaps = {
  // Set BStack options that would allow App Automate to run
  'bstack:options': {
    userName: process.env.AA_USERNAME,
    accessKey: process.env.AA_ACCESS_KEY
  },
  // Percy Options (defaults)
  'appium:percyOptions': {
    enabled: true, // true by default, decides if percy is enabled for particular session or device
    ignoreErrors: true // true by default, decides whether to ignore errors occurred during test
  },
  // Set URL of the application under test
  app: process.env.APP,
  // Specify device and os_version for testing
  device: 'Google Pixel 6',
  os_version: '12',
  // Set other BrowserStack capabilities
  project: 'First App Percy test',
  build: 'App Percy test',
  name: 'first_visual_test'
};

  

Available Percy options

Copy

    ```json
'appium:percyOptions': {
  enabled: true, // true by default, decides if percy is enabled for particular session or device
  ignoreErrors: true // true by default, decides whether to ignore errors occurred during test
}

  

Copy

    ```json
var capabilties = {
   ...,
   "deviceName": "iPhone 14",
   "percy.enabled": true/false,
   "percy.ignoreErrors": true/false,
   ...
}

  

      
            JSON
          
            JSONWire
          
          Copy
        
'appium:percyOptions': {
  enabled: true, // true by default, decides if percy is enabled for particular session or device
  ignoreErrors: true // true by default, decides whether to ignore errors occurred during test
}
var capabilties = {
   ...,
   "deviceName": "iPhone 14",
   "percy.enabled": true/false,
   "percy.ignoreErrors": true/false,
   ...
}

run percy

You can run your tests on Percy using either your make file or by utilizing the Percy start and stop commands.

Run test using exec command

Add the percy app exec command in your make file for executing tests on Percy, as shown below:

Percy CLI command to upload a directory of static images to Percy for diffing.

Copy

    ```bash
npx percy app:exec python test.py

Run test using Percy start stop commands

If you cannot use the percy app:exec command in your configuration file or you want to run your test via IDE, use the percy app:exec:start and percy app:exec:stop commands.

(1) Execute the below command to start Percy.

Percy CLI command to upload a directory of static images to Percy for diffing.

Copy

    ```bash
npx percy app:exec:start # starts percy CLI tool, percy is ready to receive screenshots

(2) Run your tests using the IDE’s run option.
(3) On test completion, you can stop Percy.

Percy CLI command to upload a directory of static images to Percy for diffing.

Copy

    ```bash
npx percy app:exec:start # starts percy CLI tool, percy is ready to receive screenshots

Did this page help you?

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Is this page helping you?

Yes

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback!