Python 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 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.

Frameworks

Currently, we support the following frameworks:

• Robot Framework (View Docs Here)
• Generic Python Client

info

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.

Installation

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

pip install saucelabs_visual

Usage

note

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
client.create_build(
    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
client.create_snapshot_from_webdriver(
    name="Snapshot Name",
    session_id=session_id,
    # Other optional items to customize your snapshots / associate them with the current test run
    # test_name="TEST_NAME_FROM_YOUR_FRAMEWORK",
    # suite_name="SUITE_NAME_FROM_YOUR_FRAMEWORK",
)

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
client.finish_build()

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

Examples

Example projects are available here.