Python Integration

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()

Visual Snapshot Options & Examples

Full Page Screenshots

By default, only the current viewport is capture when taking a screenshot. By passing a FullPageConfig instance in the full_page_config named param you can enable and customize the behavior for our scroll-and-stitch snapshots. View the FullPageConfig class in our visual SDKs for up to date inline docs for all properties.

note

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

from saucelabs_visual.typing import FullPageConfig
# ...
visual_client.create_snapshot_from_webdriver(
    "Inventory Page",
    session_id=session_id,
    full_page_config=FullPageConfig(
        # Can customize full page behavior by customizing values here. Or omit completely to
        # disable full page screenshots:
        # ex:
        # scrollLimit=10,
        # hideAfterFirstScroll=['.fixed-header', '#cookie-banner']
        # delayAfterScrollMs=200,
    ),
)

DOM Capture

You can use the capture_dom named param with a value of True to enable DOM capture during a snapshot.

visual_client.create_snapshot_from_webdriver(
    "Inventory Page",
    session_id=session_id,
    capture_dom=True,
)

Clip to an Element

If you'd like to test a specific component or area of a page you can use the clip_selector named param in combination with a CSS selector to clip the screenshot and DOM comparison. When enabled, we'll crop the screenshot to the coordinates of the element and constrain our DOM comparison to that area. We accept any document.querySelector compatible string / CSS selector as the value.

visual_client.create_snapshot_from_webdriver(
    "Inventory Page",
    session_id=session_id,
    clip_selector='.my-css-selector',
)

Alternatively, you can also pass an element directly if you've already queried one from selenium using the clip_element named param:

add_to_cart_button = driver.find_element(By.CSS_SELECTOR, '.btn_inventory')
visual_client.create_snapshot_from_webdriver(
    "Inventory Page",
    session_id=session_id,
    clip_element=add_to_cart_button,
)

Ignore Regions

You can ignore one or more areas on the page by using the ignore_regions named param. Ignore regions accepts an array of full region definitions (width, height, x & y coordinates). We also support passing elements directly using the ignore_elements named param to bypass region calculation / creation. See below for examples for both.

Regions:

from saucelabs_visual.typing import IgnoreRegion
# ...
visual_client.create_snapshot_from_webdriver(
    "Inventory Page",
    session_id=session_id,
    # Use coordinates on a page to create manual regions.
    ignore_regions=[
        IgnoreRegion(x=100, y=100, width=100, height=100)
    ],
)

Elements:

from saucelabs_visual.typing import IgnoreElementRegion
# ...
add_to_cart_button = driver.find_element(By.CSS_SELECTOR, '.btn_inventory')
visual_client.create_snapshot_from_webdriver(
    "Inventory Page",
    session_id=session_id,
    # Ignore certain areas of a page using elements / selectors.
    ignore_elements=[
        IgnoreElementRegion(
            # Ignore one or more elements returned by find_elements/find_element.
            element=driver.find_elements(By.CSS_SELECTOR, '.inventory_item_img'),
        ),
        IgnoreElementRegion(
            # Can also pass an element that has been previously found via the driver
            element=add_to_cart_button,
        ),
    ],
)

Selective Diffing

Sauce Visual allows selective diffing that permits to ignore changes from a certain kind (more information here).

warning

Selective diffing is only available with Balanced diffing method AND with DOM capture enabled.

Area-specific configuration

Sauce Visual Binding allows to configure which kinds of changes should be effective specific regions of the snapshot.

Example:

    visual_client.create_snapshot_from_webdriver(
        "login-page",
        session_id=session_id,
        diffing_method=DiffingMethod.BALANCED,        
        capture_dom=True,
        ignore_elements=[
            # Any change will be ignored.
            IgnoreElementRegion(
                element=driver.find_element(By.NAME, "user-name")
                enable_only=[]
            ),
            # Only style changes won't be ignored.
            IgnoreElementRegion(
                element=driver.find_element(By.NAME, "password")
                enable_only=['style']
            ),
        ],
    )

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

Introduction​

Frameworks​

Installation​

Usage​

Step 1 - Import and instantiate the Client​

Step 2 - Create the Build​

Step 3 - Take a Snapshot​

Step 4 - Finish the Build​

Visual Snapshot Options & Examples​

Full Page Screenshots​

DOM Capture​

Clip to an Element​

Ignore Regions​

Selective Diffing​

Area-specific configuration​

Environment variables​

Examples​