Configure your environment variables to allow Percy builds to run seamlessly
Percy integrates with your tests using both Percy and BrowserStackSDK. To establish this integration, choose the appropriate SDK and refer to the following section accordingly:
To seamlessly integrate your visual and functional testing processes for your website, execute your Percy tests on BrowserStack’s Automate. If you’re already an Automate user and wish to explore Percy, you can do so as well. Leveraging BrowserStack SDK for running your tests fulfills all requirements.
Supported parameters
Percy client libraries retrieve additional details from the environment they are running in, including the branch name, commit SHA, GitHub Pull Request number, and more. You can modify certain aspects of Percy’s behavior by configuring these environment variables within your CI environment:
Environment Variable
Description
PERCY_BRANCH
The branch in which the build is being executed. Default is the current git branch.
PERCY_PULL_REQUEST
The pull request number to link with the build, if any.
PERCY_PARALLEL_TOTAL
The total number of parallel builds to expect. \n- In most setups this is automatically discovered and does not need to be set. To know more, read Parallel test suites.
PERCY_PARALLEL_NONCE
A unique identifier used to group parallel builds. This can be any string that is shared between parallel runners, such as the CI build number. \n - In most setups this is automatically discovered and does not need to be set. To know more, read Parallel test suites.
PERCY_PARTIAL_BUILD
Set to 1 to indicate the build is a partial build, and that it intentionally will be a subset of the snapshots from a full build.
HTTP_PROXY
Set http proxy that Percy cli should use in case you need to access internet over a corporate proxy.
HTTPS_PROXY
Set https proxy that Percy cli should use in case if you need to access internet over a corporate proxy
In most cases setting only HTTP_PROXY should suffice, but if you have separate proxies for HTTP and HTTPS feel free to set both.
The format for proxy’s is http[s]://<username>:<password>@<domain.com>:<port>/ [username and password is optional].
PERCY_COMMIT
Set this to the Git commit SHA to ensure that visual tests and snapshots taken by Percy are correctly linked to a specific commit in the version control system.
PERCY_GZIP
Set this to true to potentially optimize resource size within the 25 MB threshold limit. The default is set to false.
PERCY_DO_NOT_USE_CAPTURED_COOKIES
Set this to true to stop the use of auto-captured cookies. The default is set to false.
Percy is designed to integrate with your tests locally and with your CI environment. To establish this integration, set the PERCY_TOKEN environment variable by following these steps:
IMPORTANT
Keep your Percy token secret. Anyone with access to your token can consume your account quota.
The “write-only” token can only be used to make changes, not to view your data.
Get PERCY_TOKEN
A Percy token is generated when you create a Percy project. The token is a write-only API key that is unique for each project. You can find this on the Project Settings page.
You can set a project-specific token with three access levels:
Read-only: With this, you can retrieve project information using the GET API call.
Write-only: This serves as a project-specific API key, allowing you to create builds, snapshots, and upload resources to the project.
Full-access: This serves as a project-specific read/write API key, allowing you to read build information, download snapshots, create builds and snapshots, and upload resources to the project.
To learn about how to set your Percy token as an environment variable, see the relevant section.
Note
Percy works best when triggered automatically from your CI environment, but can also be run from your local development environment. This is helpful during the initial integration of Percy.
As of CLI version 1.26.7, the default configuration for all users involves automatically sending terminal logs to Percy to enhance support and improve services. However, we value your privacy and offer an option to opt out of this feature using an environment variable. You can use the following command to opt out: export PERCY_CLIENT_ERROR_LOGS=false
Run Percy locally
To run Percy locally, set the PERCY_TOKEN environment variable using the export keyword as shown:
When running in your local environment, it is recommended to set the PERCY_BRANCH environment variable to “local” to prevent unintentionally overwriting of your project’s master baseline in Percy. While not compulsory, this measure ensures the preservation of any baselines established by CI.
If you don’t use the PERCY_BRANCH variable while you run local tests and you happen to be on the master branch, then it will result in setting the baseline for your project in Percy as the master branch.
Run from your CI setup
To run Percy from your CI workflow, update both the CI configuration file and the pipeline script. For more information, see Configure CI environment variables.
Percy works best when integrated into your CI workflow, running continuously alongside your test suite. It seamlessly integrates with major CI providers and offers configurability for custom environments.
Note
We recommend to run Percy via your CI workflow.
Supported parameters
Percy client libraries retrieve additional details from the environment they are running in, including the branch name, commit SHA, GitHub Pull Request number, and more. You can modify certain aspects of Percy’s behavior by configuring these environment variables within your CI environment:
Environment Variable
Description
PERCY_TOKEN
A Percy token is a project-specific, write-only API key.
PERCY_BRANCH
The branch in which the build is being executed. Default is the current Git branch.
PERCY_CLIENT_ERROR_LOGS
Set this to false to prevent the test script from sending error logs to Percy.
PERCY_TARGET_BRANCH
The branch for comparison. Default is set to master. If the Percy build is associated with a GitHub Pull Request, setting this value will have no effect and the target branch will be automatically determined based on the GitHub PR. For more information, see the base build selection.
PERCY_TARGET_COMMIT
The full commit SHA of an existing Percy build to be used as the reference baseline. For more information, see the base build selection.
PERCY_PULL_REQUEST
The pull request number to link with the build, if applicable.
PERCY_PARALLEL_TOTAL
The total number of expected parallel builds. - In most setups this is automatically discovered and does not need to be set. For more information, see the Parallel test suites.
PERCY_PARALLEL_NONCE
A unique identifier used to group parallel builds. This can be any string that is shared between parallel runners, such as the CI build number. - In most setups this is automatically discovered and does not need to be set. For more information, see the Parallel test suites.
PERCY_PARTIAL_BUILD
Set to 1 to indicate the build is a partial build, and that it intentionally will be a subset of the snapshots from a full build.
PERCY_ENABLE
Set to 0 to prevent Percy from running in your CI environment. This is useful if you want to disable Percy in certain scenarios.
PERCY_DEBUG
Set to true to debug asset discovery and do not upload snapshots.
PERCY_LOGLEVEL
Set this variable to one of the following values: info, silent, warn or debug.
HTTP_PROXY
Set the HTTP proxy that Percy CLI should use in case you need to access internet over a corporate proxy.
HTTPS_PROXY
Set the HTTPS proxy that the Percy CLI should use if you need to access the internet through a corporate proxy.
In most cases, setting only HTTP_PROXY is sufficient. However, if you have separate proxies for HTTP and HTTPS, you can set both.
The format for proxies is http[s]://<username>:<password>@<domain.com>:<port>/ [username and password is optional].
PERCY_PAC_FILE_URL
Use this variable to specify the path to your PAC config file, this enables proxy functionality based on the specified path. Note: If the PERCY_PAC_FILE_URL environment variable is set, it will take precedence over other Percy proxy variables. How to use this variable: - Example of the file path in storage: pac+file://C:/Users/<username>/.proxy/pac_file.pac - Example of fetching the file from the web: pac+http://localhost:8000/app_proxy.pac.
PERCY_NETWORK_IDLE_WAIT_TIMEOUT
Specifies the maximum time the Percy CLI’s resource discovery browser waits for the networkIdleTimeout to occur. The default value is 30000ms (30 seconds).
PERCY_PAGE_LOAD_TIMEOUT
Specifies the maximum time the Percy CLI’s resource discovery browser waits for the page to load. The default value is 30000ms [ 30 seconds ].
PERCY_SKIP_UPDATE_CHECK
Set this to true to skip CLI update checks. By default, the CLI queries api.github.com for newer release tags unless this environment variable is set to false.
PERCY_COMMIT
Set this to the Git commit SHA to ensure that visual tests and snapshots taken by Percy are correctly linked to a specific commit in the version control system.
PERCY_DO_NOT_CAPTURE_RESPONSIVE_ASSETS
Set this to true, and it will not capture responsive assets like images for that page. The default is set to false.
PERCY_EXIT_WITH_ZERO_ON_ERROR
Set this variable to true to exit with code 0 for any Percy-related errors and generate the error logs. The default value is false.
PERCY_GZIP
Set this to true to potentially optimize resource size within the 25 MB threshold limit. The default is set to false.
PERCY_DO_NOT_USE_CAPTURED_COOKIES
Set this to true to stop the use of auto-captured cookies. The default is set to false.
RESPONSIVE_CAPTURE_SLEEP_TIME
Set this variable to specify the time in seconds to explicitly wait after each resize if you notice your webpage is not loading properly at certain widths. The default value is 0. For more information, see Capturing responsive snapshots.
Note
With the latest version of @percy/cli, any of the environment variables defined on this page can be specified within a .env file in current working directory.
PERCY_TOKEN access levels
Components of Feature
Read
Write
Full
Synchronous Comparison Results
No
No
Yes
Percy Screenshot
No
Yes
Yes
Percy Snapshot
No
Yes
Yes
Upload screenshots
No
Yes
Yes
CI Integration
No
Yes
Yes
API Reference - GET
Yes
No
Yes
API Reference - PUT/POST
No
Yes
Yes
Every feature that uses the Percy Screenshot and Percy Snapshot commands will have the same access, except for Synchronous CLI.
We recommend using the ‘Write’ access mode for CI integration.
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
Thank you for your valuable feedback
ON THIS PAGE
Is this page helping you?
Yes
No
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
