Skip to main content

Python Integration


This document assumes an existing Python 3+ project. Alternatively, you can take a look to our example repository for quick-start projects.

Sauce Visual plugin for Python provides an interface for interacting with Sauce Labs Visual and a running Selenium session on Sauce.

A generic SauceLabsVisual client is exposed by the package to allow interaction with any Python based tooling. We also offer some additional framework-specific options which we'll expand support for over time.


Currently, we support the following frameworks:


If you're looking for support with additional frameworks, you can submit a feature request on our Productboard to help us prioritize which SDKs we roll out first.


  • Install the Sauce Labs Visual python package in your project, and optionally append it to your dependencies.
pip install saucelabs_visual



This client currently requires that you're running an existing Webdriver session on Sauce and can access the session ID for interaction with our Visual API.

For more technical users, we also expose a generic SauceLabsVisual client which can be used to interact with the Visual API for a running Selenium / Webdriver session on Sauce in case your framework is not officially supported yet.

Generally, the workflow would be as follows:

Step 1 - Import and instantiate the Client

Import the client and store it in a variable you can access globally in your tests / framework:

from saucelabs_visual.client import SauceLabsVisual

client = SauceLabsVisual()

Step 2 - Create the Build

  • Either manually or in a beforeAll hook that is only triggered once in your framework, create the Visual build that we'll associate all screenshots with.
# Creates a build and stores the build meta in the client instance for processing & interaction later
name='My Python Build',
# Any other named parameters that are available. See the source / docs for more information on
# options for customizing your build.
# project="my-project",
# branch="my-ci-branch",

Step 3 - Take a Snapshot

Take a visual snapshot in each test where you'd like to check for visual changes

We recommend creating a helper class / function within your framework of choice to reduce the duplication / need to pass the test metadata (such as test / suite name) into each call.

session_id = 'YOUR_SESSION_ID'  # Get your Selenium session ID from your framework
name="Snapshot Name",
# Other optional items to customize your snapshots / associate them with the current test run

Step 4 - Finish the Build

  • Either manually or in an afterAll hook that is only triggered once at the end of your framework, finish the Visual build to let Sauce Visual know we're ready to present the results in the UI.
# Finish the currently opened build associated with this instance

Environment variables

Below are the environment variables available in the Sauce Visual Python plugin. Keep in mind that the variables defined in code / configuration have precedence over these.

Variable NameDescription
SAUCE_USERNAMErequiredYour Sauce Labs username. You can get this from the header of
SAUCE_ACCESS_KEYrequiredYour Sauce Labs access key. You can get this from the header of
SAUCE_REGIONThe 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_NAMEThe name you would like to appear in the Sauce Visual dashboard.
SAUCE_VISUAL_BRANCHThe branch name you would like to associate this build with. We recommend using your current VCS branch in CI.
SAUCE_VISUAL_DEFAULT_BRANCHThe 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_PROJECTThe label / project you would like to associated this build with.
SAUCE_VISUAL_BUILD_IDFor 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_IDFor 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.


Example projects are available here.