Set Environment Variables
Configure your environment variables to allow Percy builds to run seamlessly
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.
-
Set PERCY_TOKEN as environment variable
You can run Percy: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.
Run Percy locally
To run Percy locally, set the PERCY_TOKEN environment variable using the export keyword as shown:
Alternatively, you can set the PERCY_TOKEN environment variable locally using the export keyword in a single line:
Note
- When running in your local environment, it is recommended to set the
PERCY_BRANCHenvironment variable to “local” to prevent unintentionally overwriting of your project’smasterbaseline in Percy. While not compulsory, this measure ensures the preservation of any baselines established by CI.
- If you don’t use the
PERCY_BRANCHvariable 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 with BrowserStack Automate
To run Percy tests on a variety of desktop and mobile browsers, select the Automate option while creating Percy project and set the PERCY_TOKEN environment variable using export keyword. Learn more.
Run from your CI setup
To run Percy from your CI workflow, update both the CI configuration file and the pipeline script. Learn more.
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.
Other 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_TARGET_BRANCH |
The branch for comparison. Default set to master. \n- If the Percy build is associated to a GitHub Pull Request, setting this value will have no effect and the target branch will be automatically determined from the GitHub PR. To know more, read base build docs. |
PERCY_TARGET_COMMIT |
The full commit SHA of an existing Percy build to be used as the reference baseline. To know more, read base build docs. |
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. |
PERCY_ENABLE |
Set to 0 to prevent Percy running in your CI environment. This can be useful to set conditionally if you want Percy to be disabled in certain scenarios. |
PERCY_DEBUG |
Set to true to debug asset discovery and do not upload snapshots. |
PERCY_LOGLEVEL |
Set it to any of the following: ‘info’, ‘silent’, ‘warn’ or ‘debug’. |
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_NETWORK_IDLE_WAIT_TIMEOUT |
This is maximum amount of time Percy cli’s resource discovery browser would wait for networkIdleTimeout to hit. This is defaulted to 30000ms [ 30 sec ]. |
PERCY_PAGE_LOAD_TIMEOUT |
This is maximum amount of time Percy cli’s resource discovery browser would wait for page to load. This is defaulted to 30000ms [ 30 sec ]. |
PERCY_SKIP_UPDATE_CHECK |
Set to true to skip CLI update checks we queryapi.github.com for newer CLI releases tags, if this env is not set false. |
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.
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
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
Thank you for your valuable feedback!
