C#/.Net WebDriver Integration

Important

Access to this feature is currently limited to Enterprise customers as part of our commitment to providing tailored solutions. We are excited to announce that self-service access is under development and will be released shortly. Stay tuned!

Introduction

This guide requires an existing C# NUnit / xUnit setup.
You can alternatively take a look to our example repository.

Sauce Visual provides a library allowing integration with WebDriver.

Sauce Visual plugin provides a library exposing a VisualClient class that provides actions:

VisualCheck: Takes a screenshot and sends it to Sauce Visual for comparison.
VisualResults: Waits for all diff calculations to complete and returns a summary of results. See Test results summary for more details about summary format and sample usage.

Quickstart

Step 1: Add Sauce Visual dependency

Add Sauce Visual dependency to your .csproj

Windows NuGet CLI
Linux/macOS/.Net Core

Install-Package SauceLabs.Visual

dotnet add package SauceLabs.Visual

Note: You can find the latest versions available here.

Step 2: Configure Visual Testing integration

Declare a RemoteWebDriver and a VisualClient instance as class properties

using OpenQA.Selenium.Remote;
using SauceLabs.Visual;

private RemoteWebDriver Driver { get; set; }
private VisualClient VisualClient { get; set; }

Initialize RemoteWebDriver and VisualClient

NUnit
xUnit

    [OneTimeSetUp]
    public async Task Setup()
    {
      var sauceUsername = "YOUR_USERNAME";
      var sauceAccessKey = "YOUR_ACCESS_KEY";
      var sauceUrl = "https://ondemand.us-west-1.saucelabs.com:443/wd/hub";

      var browserOptions = new ChromeOptions();
      browserOptions.PlatformName = "Windows 11";
      browserOptions.BrowserVersion = "latest";

      var sauceOptions = new Dictionary<string, string>();
      sauceOptions.Add("username", sauceUsername);
      sauceOptions.Add("accessKey", sauceAccessKey);
      browserOptions.AddAdditionalOption("sauce:options", sauceOptions);

      Driver = new RemoteWebDriver(sauceUrl, browserOptions);

      VisualClient = await VisualClient.Create(Driver, Region.UsWest1, new CreateBuildOptions()
      {
          Name = "My Visual Build",
          Project = "csharp-project",
          Branch = "csharp-branch"
      });
      // Enable Dom Capture
      VisualClient.CaptureDom = true;
    }

  class MyTestClass : IAsyncLifetime {
    [...]
    public async Task InitializeAsync()
    {
        var browserOptions = Utils.GetBrowserOptions();
        var sauceOptions = Utils.GetSauceOptions();
        browserOptions.AddAdditionalOption("sauce:options", sauceOptions);

        var sauceUrl = Utils.GetOnDemandURL();
        Driver = new RemoteWebDriver(sauceUrl, browserOptions);
        Driver.ExecuteScript("sauce:job-name=xUnit C#/.Net Visual Session");

        VisualClient = await VisualClient.Create(Driver, Region.UsWest1, new CreateBuildOptions()
        {
            Name = "My Visual Build",
            Project = "csharp-project",
            Branch = "csharp-branch"
        });
        // Enable Dom Capture
        VisualClient.CaptureDom = true;
    }
  }

To enhance efficiency in managing tests, it's important to provide a specific test name and suite name for each test. This practice allows Sauce Visual to effectively organize snapshots into coherent groups. As a result, it simplifies the review process, saving time and effort in navigating through test results and understanding the context of each snapshot.

Don't forget to quit the WebDriver and Dispose VisualClient.

NUnit
xUnit

    [OneTimeTearDown]
    public async Task Teardown()
    {
        Driver?.Quit();
        await VisualClient.Cleanup();
        VisualClient.Dispose();
    }

  public class MyTestClass : IAsyncLifetime
  {
    [...]
    public async Task DisposeAsync()
    {
        Driver?.Quit();
        await VisualClient.Cleanup();
        VisualClient.Dispose();
    }
  }

Step 3: Add visual tests in your tests

Add a check to one of your tests:

NUnit
xUnit

    [Test]
    public async Task SauceDemoHomePage_ShouldRenderLoginCorrectly()
    {
        Driver.Navigate().GoToUrl("https://www.saucedemo.com");
        var wait = new WebDriverWait(Driver, TimeSpan.FromSeconds(15));
        wait.Until(drv => drv.FindElement(usernameLocator));

        await VisualClient.VisualCheck("Sauce Demo Homepage");
    }

    [Fact]
    public async Task SauceDemoHomePage_ShouldRenderLoginCorrectly()
    {
        Driver.Navigate().GoToUrl("https://www.saucedemo.com");
        var wait = new WebDriverWait(Driver, TimeSpan.FromSeconds(15));
        wait.Until(drv => drv.FindElement(usernameLocator));

        await VisualClient.VisualCheck("Sauce Demo Homepage");
    }

Step 4: Configure your Sauce Labs credentials

Sauce Visual relies on environment variables for authentications.
Both SAUCE_USERNAME and SAUCE_ACCESS_KEY need to be set prior starting your .Net job.

Username and Access Key can be retrieved from https://app.saucelabs.com/user-settings.

export SAUCE_USERNAME=__YOUR_SAUCE_USER_NAME__
export SAUCE_ACCESS_KEY=__YOUR_SAUCE_ACCESS_KEY__

Step 5: Run the test

Upon executing your tests for the first time under this step, a visual baseline is automatically created in our system. This baseline serves as the standard for all subsequent WebDriver tests. As new tests are run, they are compared to this original baseline, with any deviations highlighted to signal visual changes. These comparisons are integral for detecting any unintended visual modifications early in your development cycle. All test builds, including the initial baseline and subsequent runs, can be monitored and managed through the Sauce Labs platform at Sauce Visual Builds.

Remember, the baseline is established during the initial run, and any subsequent visual differences detected will be marked for review.

Advanced usage

Customizing Your Builds (Environment Variables)

Below are the environment variables available in the Sauce Visual C# plugin. Keep in mind that the variables defined in CreateBuildOptions configuration have precedence over these.

Variable Name		Description
`SAUCE_USERNAME`	required	Your Sauce Labs username. You can get this from the header of app.saucelabs.com
`SAUCE_ACCESS_KEY`	required	Your Sauce Labs access key. You can get this from the header of app.saucelabs.com
`SAUCE_REGION`		The region you'd like to run your Visual tests in. Defaults to `us-west-1` if not supplied. Can be one of the following: `'eu-central-1'`, `'us-west-1'` or `'us-east-4'`
`SAUCE_VISUAL_BUILD_NAME`		The name you would like to appear in the Sauce Visual dashboard.
`SAUCE_VISUAL_BRANCH`		The branch name you would like to associate this build with. We recommend using your current VCS branch in CI.
`SAUCE_VISUAL_DEFAULT_BRANCH`		The main branch name you would like to associate this build with. Usually `main` or `master` or alternatively the branch name your current branch was derived from. Follow me to learn more
`SAUCE_VISUAL_PROJECT`		The label / project you would like to associated this build with.
`SAUCE_VISUAL_BUILD_ID`		For advanced users, a user-supplied SauceLabs Visual build ID. Can be used to create builds in advance using the GraphQL API. This can be used to parallelize tests with multiple browsers, shard, or more. By default, this is not set and we create / finish a build during setup / teardown.
`SAUCE_VISUAL_CUSTOM_ID`		For advanced users, a user-supplied custom ID to identify this build. Can be used in CI to identify / check / re-check the status of a single build. Usage suggestions: CI pipeline ID.

Test results summary

VisualClient.VisualResults() returns a summary of test results in Dictionary<DiffStatus, int> format where DiffStatus is one of the following:

DiffStatus.QUEUED: Diffs that are pending for processing. Should be 0 in case the test is completed without any timeouts
DiffStatus.EQUAL: Diffs that have no changes detected
DiffStatus.UNAPPROVED: Diffs that have detected changes and waiting for action
DiffStatus.APPROVED: Diffs that have detected changes and have been approved
DiffStatus.REJECTED: Diffs that have detected changes and have been rejected

Sample usage:

var expectedTotalUnapprovedDiffs = 0;

var results = await VisualClient.VisualResults();
Assert.AreEqual(expectedTotalUnapprovedDiffs, results[DiffStatus.Unapproved]);

Build attributes

When creating the service in VisualClient, extra fields can be set to define the context, thus acting on which baselines new snapshots will be compared to. (More info on baseline matching)

It needs to be defined through a CreateBuildOptions object.

Properties available:

string? Name: The name of the build
string? Project: The name of the project
string? Branch: The name of the branch
string? CustomId: A customId to be able to retrieve the current build
string? DefaultBranch: The name of the default branch

Example:

  VisualClient = await VisualClient.Create(Driver, Region.UsWest1, sauceUsername, sauceAccessKey,
      new CreateBuildOptions() { Name = "My Visual Build", Project = "csharp-project", Branch = "feature-branch" });

Ignored regions

Component-based ignored region

Sauce Visual provides a way to ignore a list of components.

An ignored component can be a specific element from the page.

Those ignored components are specified when requesting a new snapshot.

Example:

var btnAction = Driver.FindElement(By.CssSelector(".app_logo"));

await VisualClient.VisualCheck("C# capture",
    new VisualCheckOptions()
    {
        IgnoreElements = new[] { btnAction }
    });

User-specified ignored region

Alternatively, ignored regions can be user-specified areas. A region is defined by four elements.

x, y: The location of the top-left corner of the ignored region
width: The width of the region to ignore
height: The height of the region to ignore

Note: all values are pixels

Example:

await VisualClient.VisualCheck("C# capture",
    new VisualCheckOptions()
    {
        IgnoreRegions = new[] { new IgnoreRegion(10, 10, 100, 100) }
    });

Capturing the DOM snapshot

Sauce Visual does not capture dom snapshot by default. It can be changed when creating the VisualClient object.

Example:

VisualClient = VisualClient.Create(Driver, Region.UsWest1, sauceUsername, sauceAccessKey);
VisualClient.CaptureDom = true;

Full page screenshots

By default, only the current viewport is captured when .VisualCheck is used. You can opt in to capturing the entire page by using the FullPage option. It will capture everything by scrolling and stitching multiple screenshots together. Additionally, you have the option to configure full page settings using the FullPageConfig option.

note

It's recommended to use the HideAfterFirstScroll option for fixed or sticky position elements such as sticky headers or consent banners.

Options:

DelayAfterScrollMs: Delay in ms after scrolling and before taking screenshots. The default value is 0. We recommend using this option for lazy loading content.
HideAfterFirstScroll: Hide elements on the page after first scroll (uses css selectors)

Examples:

await VisualClient.VisualCheck("C# full page",
    new VisualCheckOptions()
    {
        FullPage = true,
    });

await VisualClient.VisualCheck("C# full page config",
    new VisualCheckOptions()
    {
        FullPage = true,
        FullPageConfig = new FullPageConfig()
            {
                DelayAfterScrollMs = 500,
                HideAfterFirstScroll = new List<string> { ".header" }
            }
    });

note

The maximum number of scrolls and stitches in a full page screenshot is 10.

Examples

Two examples are available:

An example project using NUnit
An example project using xUnit

C#/.Net WebDriver Integration

Introduction​

Quickstart​

Step 1: Add Sauce Visual dependency​

Step 2: Configure Visual Testing integration​

Step 3: Add visual tests in your tests​

Step 4: Configure your Sauce Labs credentials​

Step 5: Run the test​

Advanced usage​

Customizing Your Builds (Environment Variables)​

Test results summary​

Build attributes​

Ignored regions​

Component-based ignored region​

User-specified ignored region​

Capturing the DOM snapshot​

Full page screenshots​

Examples​

Introduction

Quickstart

Step 1: Add Sauce Visual dependency

Step 2: Configure Visual Testing integration

Step 3: Add visual tests in your tests

Step 4: Configure your Sauce Labs credentials

Step 5: Run the test

Advanced usage

Customizing Your Builds (Environment Variables)

Test results summary

Build attributes

Ignored regions

Component-based ignored region

User-specified ignored region

Capturing the DOM snapshot

Full page screenshots

Examples