Percy on Automate Integration Tutorial (Selenium)

This tutorial provides step-by-step guidance on integrating Percy with Automate using the BrowserStack SDK.


To follow this tutorial ensure you have the below installations on your system:

  • Git is installed.
  • Node 14+ with npm is installed.
  • For Java, you need to have the below additional dependencies:
    • TestNG v6.8+ is installed.
    • Java v8+ is installed.
    • Selenium v2.5+ (W3C/JSON Wire) is installed.
    • Maven is installed, environment variables are set and bin is added to the system path.

Run a sample build

Get Sample Project

Step 1) Get our sample project via Git.

Clone our sample repository and install the dependencies.

$ git clone
$ cd example-percy-automate-selenium-python

# create virtual environment
$ python3 -m venv env
$ source env/bin/activate

# install the required packages
$ pip3 install -r requirements.txt
$ npm install
$ git clone
$ cd example-percy-automate-selenium-javascript
$ cd selenium-webdriver
$ npm install
$ git clone [email protected]:percy/example-percy-automate-selenium-java.git
$ cd example-percy-automate-selenium-java
$ mvn compile
$ git clone [email protected]:percy/example-percy-automate-selenium-dotnet.git
$ cd example-percy-automate-selenium-dotnet
$ dotnet build

Step 2) Create Percy on Automate project and export the Percy token.

Step 3) Get your BrowserStack credentials and update the sample script.

  1. Sign up with BrowserStack for a free trial or purchase a plan.
  2. Get your "username" and "access key" from the BrowserStack profile page.
  3. Use the userName and accessKey variables to set BrowserStack environment variables to authenticate your tests.
$ export BROWSERSTACK_USERNAME="<your browserstack user_name>"
$ export BROWSERSTACK_ACCESS_KEY="<your browserstack access_key>"
$ set BROWSERSTACK_USERNAME="<your browserstack access_key>"
$ set BROWSERSTACK_ACCESS_KEY="<your browserstack access_key>"

# PowerShell
$ $Env:BROWSERSTACK_USERNAME="<your browserstack access_key>"
$ $Env:BROWSERSTACK_ACCESS_KEY="<your browserstack access_key>"

Alternatively, you can also update USER_NAME, and ACCESS_KEY in the test file.

Step 4) Run a sample test to generate your first Automate and Percy builds.

$ npx percy exec --verbose -- python3 tests/
$ npx percy exec --verbose -- npm run test
$ npx percy exec --verbose -- mvn test -P sample-percy-test
$ npx percy exec --verbose -- dotnet test --filter "Category=sample-percy-test"

Your first Percy on Automate build is created. As this is the first time running the script, the captured screenshots will be considered new; therefore, no comparisons will be available.


  • The Percy screenshot command is used to capture screenshots in your Automate session. Refer to the tests mentioned in the git repository.
  • You need to approve the first build to have a base build for future comparisons.

Step 5) Introduce visual changes.

There are two options available to introduce visual changes

Option 1: You can directly run the test file provided in the project using the run command in Step 4. In this case you can skip the Step 6 and directly visit the Automate and the Percy dashboards to see your functional and visual builds.

Option 2: You can search for the below line in the test file and replace the @id="1" to @id="3".

WebDriverWait(driver, 10).until(EC.visibility_of_element_located(
        (By.XPATH, '//*[@id="1"]/div[4]'))).click() 
await driver.findElement(By.xpath('//*[@id="1"]/div[4]')).click();
WebDriverWait(driver, 10).until(EC.visibility_of_element_located(
    (By.XPATH, '//*[@id="1"]/div[4]'))).click()

Step 6) Follow Step 4 to generate your second builds.

After the script execution is finished, the current build will be compared to the previous approved build.

Step 7) Visit the Automate and the Percy dashboards to see your functional and visual builds.


Next steps

After you have successfully run your first test on Percy on Automate, try integrating your test suite with Percy on Automate.