Set Environment Variables

Configure your environment variables to allow App Percy builds to run seamlessly.

App 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:

BrowserStack SDK
Percy SDK

Run tests in parallel on BrowserStack App Infra

If you are using BrowserStack (App Automate) for your mobile device infra with Percy, then you can run multiple tests at the same time across various devices. This is called parallel testing. Parallel testing gives you the same benefits as running a multi-threaded application. More parallel tests speed up the time taken to complete a test suite.

BrowserStack App Automate plan supports running the number of parallel tests (5 during free trial). You can purchase more parallels as per your need. To learn more about parallel testing on Browserstack infra, visit here.

Supported parameters

App 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 App 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_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_TMP_DIR`	Set an absolute path accessible locally where screenshots will be stored.
`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.

App 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 an App 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.

Learn more about which feature works with which access levels.

Set PERCY_TOKEN as environment variable
You can run App Percy:

To learn about how to set your Percy token as an environment variable, see the relevant section.

Note

App 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 App 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 App Percy locally

To run App Percy locally, set the PERCY_TOKEN environment variable using the export keyword as shown:

Copy

Alternatively, you can set the PERCY_TOKEN environment variable locally in a single line. For example:

Copy

Now you can run your tests locally.

Note

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 App 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 App Percy as the master branch.

Run from your CI setup

To run App Percy from your CI workflow, update both the CI configuration file and the pipeline script. Learn more.

App 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 App Percy via your CI workflow.

Supported parameters

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 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 App 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 App 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 any.
`PERCY_PARALLEL_TOTAL`	The total number of expected parallel builds. - In most setups this is automatically discovered and does not need to be set.
`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.
`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_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_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_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 App 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 SDK/CLI and do not upload screenshots.
`PERCY_LOGLEVEL`	Set this variable to one of the following values: `info`, `silent`, `warn` or `debug`.
`PERCY_TMP_DIR`	Set an absolute path accessible locally where screenshots will be stored.
`PERCY_COMMIT`	Set this to the Git commit SHA to ensure that visual tests and snapshots taken by App Percy are correctly linked to a specific commit in the version control system.

Note
With the latest version of @percy/agent, 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

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!