Integrate Percy with Selenium and CSharp

Learn how to integrate Selenium with CSharp automated tests and Percy to catch visual differences in your website.

Percy integrates with your tests using both Percy and BrowserStack SDK. To establish this integration, choose the appropriate SDK and refer to the following section accordingly:

BrowserStack SDK
Percy SDK

You can integrate your tests using the BrowserStack SDK and manage browsers through either Automate or Percy. Percy supports the latest versions of modern browsers, including Chrome, Firefox, Edge, and Safari. With Automate, you can configure various browser names and versions using the Automate capability builder.

To establish this integration, choose the appropriate option and refer to the following section accordingly:

Manage Browsers with Automate
Manage Browsers with Percy

To integrate your CSharp based test suite with Percy using the BrowserStack SDK, follow these steps:

Prerequisites

Before you start, ensure that you have a BrowserStack Automate account using the BrowserStack SDK to integrate your test script.

Set BrowserStack credentials

Save your BrowserStack credentials as environment variables. It simplifies running your test suite from your local or CI environment. You can export the environment variables for the Username and Access Key of your BrowserStack account or you can set it in the config file.

Install BrowserStack SDK using Maven Archetype

Run the given command to install the BrowserStack SDK and create a browserstack.yml file in the root directory of your project.

The browserstack.yml config file holds all the required capabilities to run tests on BrowserStack.
The BrowserStack.TestAdapter works on top of your framework test adapter to run parallel tests on BrowserStack across multiple platforms mentioned on the browserstack.yml file.

Update your BrowserStack config file

In the browserstack.yml file:

Set percy: true.
Set a projectName.
After you run a test, an Automate project and a Percy project are created with the project name you set here.
If a Percy project by the name you set in the browserstack.yml file already exists, your screenshots are added to the same project. However, if the name matches an App Percy project, your visual tests will continue to run, but an error message will appear in your logs. Your functional tests still run as expected.
Set percyCaptureMode: manual.

Below sample browserstack.yml file shows how to set the percy, the projectName, and the percyCaptureMode parameters.

Manually add Percy screenshot method to update test script

To manually capture screenshots alongside the auto mode, implement the following steps in your test script:

Import the BrowserStack Percy SDK in your test script.
Add the PercySDK.screenshot(driver, name) method at required points in your test script to get the screenshots you want.

Here’s an example:

Run your test script

Congratulations!

You have successfully integrated Percy with BrowserStack SDK and created your first build. To see the build with snapshots of your application, visit your project in Percy.

When you run another build with visual changes to your application, Percy takes new screenshots. You can then see the comparisons between the two runs on the new build. You can access the Percy dashboard directly from the Automate dashboard.

To integrate your CSharp based test suite with Percy using the BrowserStack SDK, follow these steps:

Create Project

Create a Percy Web project using the Percy dashboard. Explore creating a Percy Web project.

Update your BrowserStack config file

In the browserstack.yml file:

Set percy: true.
Set a projectName.
Use the same projectName specified when creating the Percy Web Project.
Set percyCaptureMode: auto.
There are other supported automated capture modes in the percyCaptureMode parameter. The table below lists and describes all the acceptable modes.

Percy snapshot capture mode	Description
`auto`	Automatically capture snapshots on common events such as snapshot, click, and sendKeys.
`testcase`	Automatically capture snapshots at the end of each test case.
`click`	Automatically capture snapshots on every click.
`snapshot`	Automatically capture snapshots on every driver.snapshot call.
`manual`	This gives you more control over the snapshots you want captured. When used, you have to add the `PercySDK.snapshot(driver, name)` method at required points in your test script.

Below sample browserstack.yml file shows how to set the percy, the projectName, percyCaptureMode and the browserstackAutomation parameters.

Update your test script

To manually capture snapshot alongside the auto mode, implement the following steps in your test script:

Import the BrowserStack Percy SDK in your test script.
Add the PercySDK.snapshot(driver, name) method at required points in your test script to get the snapshot you want.

Here’s an example:

Run your test script

Your script is ready to execute visual tests, and Percy is prepared to receive the build. After the tests runs, the snapshots are added to the same Percy project.

A build with the same project name and platform configuration mentioned in the BrowserStack config file appears on the Automate dashboard.

You can integrate your tests using PercySDK with Percy Web or Percy with Automate. Choose Percy if you want to perform visual tests solely on the newest browsers; choose Automate if you want to run visual tests on a range of desktop, mobile, and browser combinations.

To establish this integration, choose the appropriate option and refer to the following section accordingly:

Percy Web
Percy with Automate

We recommend using our BrowserStack SDK for Percy integration.

Integrate Percy with your test suite to run visual tests. To do that, follow these steps:

Create a Percy project
Sign in to Percy. In Percy, create a project of the type, Web, and then name the project. After the project is created, Percy generates a token. Make a note of it. You have to use it set your environment variable in the next step.

For details on creating a project, see Create a Percy project.

Set the project token as an environment variable
Run the given command to set PERCY_TOKEN as an environment variable:

To learn about environment variables in Percy, see Percy environment variables.

Install Percy dependencies
Install the following components to establish the integration environment for your test suite.

Install Percy CLI by running the following command:

Install the percy-selenium CSharp package by running the following command:

Update your test script
Import the Percy library to use the method and attributes required to take screenshots.

In the following code, the Percy.Snapshot method is used:

We are passing the required argument which is name, and are using an <https://example.com> web application. CSharp example as the name of the snapshot within the Percy.Snapshot method.

To learn more, visit Percy snapshot.

Run Percy
Run your tests using percy exec command as shown below:

If you are unable to use the percy:exec command or prefer to run your tests using IDE run options, you can use the percy exec:start and percy exec:stop commands. To learn more, visit Run Percy.

This command starts Percy, create a new Percy build, takes snapshots and uploads them to your project, and stops Percy:

Congratulations!

You have successfully created your first build on Percy. To see the build with snapshots of your application, visit your project in Percy.

When you run another build with visual changes to your application, Percy takes new snapshots. You can then see the comparisons between the two runs on the new build.

Advanced topics

Percy Snapshot command

In the preceding steps, we used the Percy Snapshot command for capturing snapshots. Percy provides various configurations to use with Percy snapshot command. To learn more visit, Percy snapshot command.

Base build selection

By default, Percy uses the previous build for comparison however, you always have the option to configure the base build for comparison as needed. To learn more, visit base build selection logic.

Before you begin, ensure your Automate script’s capabilities are using Selenium version 3.11.0 and above.

We recommend using Selenium 4 with Percy on Automate to boost performance and ensure increased stability while capturing screenshots.
Capture a full-page screenshot using the full-page parameter. By default, Percy On Automate captures a single tile, for the full-page screenshot, refer to full page screenshot on Percy with Automate.

Integrate Percy on Automate with your test suite to run visual tests. To do that, follow these steps:

Step 1 - Install the latest Percy CLI

Step 2 - Install the SDK

Update the .csproj file as shown below:

Step 3 - In the Percy dashboard make selections as below:

Select Web as the platform.
Select Automate to handle browser selection.
Click Create Project.

Available Integrations

Step 4 - Export the Percy token.

A Percy token is generated when you create a project. Export this token environment variables.

Step 5 - Update your Automate test script.

(1) Import percy_screenshot from Percy library using the below code:

(2) Use the Percy screenshot command to take required screenshots in your Automate session.

For example, in the following CSharp code, the Percy.Screenshot("name", "options") method is called twice. In the first instance, we are passing only the required argument which is “name”. In the second instance, we are passing both the required and optional “options”.

(3) Add the browser capabilities to your test script

We recommend running your build using a single browser like Chrome or Firefox, to begin with. Once you have achieved stability with Chrome or Firefox, you can set up cross-browser testing.

// Set this in your App.config file
<configuration>
 <environments>
    <chrome>
      <add key="browserName" value="chrome" />  
    </chrome>
  </environments>
</configuration>

// Set this in your App.config file
<configuration>
 <environments>
    <chrome>
      <add key="browser" value="chrome" />  
    </chrome>
  </environments>
</configuration>

Step 6 - Run the build

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

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

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!