Selenium Python SDK

For VisualTest’s page on PyPi, go here.


  • Selenium 3+

  • Python 3+


  1. In your Python project, pip install VisualTest:

    pip install visualtest-python
  2. Add your import of VisualTest and hand off your webdriver to VisualTest, replacing 'PROJECT_TOKEN' with your project token:

    from sbvt import VisualTest
    # pip install selenium==3.141
    from selenium import webdriver
    driver = webdriver.Safari()
    settings = {'projectToken': 'PROJECT_TOKEN'}
    visualTest = VisualTest(driver, settings)
  3. At each point within your functional test where you want to capture an image (fullpage, viewport, or element) for regression testing, call the capture method:

    # Fullpage screenshot
    visualTest.capture('Home Page')
    # Viewport screenshot
    visualTest.capture('Home Page Viewport', {'viewport': True})
    # Element screenshot
    menuElement = driver.find_element_by_class_name('menu')
    visualTest.capture('Menu', { 'element': menuElement })
  4. Once your test is complete, VisualTest adds a tile to your Test Runs screen, where you can review and accept any found image differences.


    You can have VisualTest add reporting of results to the console output, including:

    • URLs to the comparisons in the VisualTest app

    • results summaries

    See Customizing VisualTest below for more information.

Customizing VisualTest

VisualTest allows script customizations that improve the quality of your testing. This section provides ways to optimize your test scripts.

Over-ride Comparison Mode

VisualTest is set to the detailed comparison mode by default (see the Comparison Mode section for more information). You can change this setting to layout mode by going to Settings.

If your tests need a combination of detailed and layout modes, you can code a given screen capture to override what you have in Settings. Below is an example. Choose from the following options:








sensitivity (layout mode only)




# Detailed Mode
visualTest.capture('Home Page', {'comparisonMode': 'detailed'})

# Layout Mode with sensitivity (low, medium, high)
visualTest.capture('Home Page', {'comparisonMode': 'layout', 'sensitivity': 'medium'})

Assign Captures to a Test Group Name

To organize your captures, assign them the same test group name by including testGroupName as a setting in the VisualTest constructor:

visualTest = VisualTest(driver, {
  'testGroupName': 'YourTestGroupName',
  'projectToken': "PROJECT_TOKEN",

Explore and manage your grouped test runs effortlessly by clicking the list view icon . Easily review and navigate through the organized test runs, all while retaining access to the detailed specifics of each individual test run.


Lazy-loading Sites

The below runs fullpage regression tests for lazy-loaded websites, setting time to elapse between scrolls. Note that the value (1000) is the number of milliseconds to wait between scrolls:

visualTest.capture('Home Page', {'lazyload': 1000}) # number is milliseconds between scrolls

For code examples that handle dynamic, moving content, see Screenshot Consistency.

Reporting in Console Output

VisualTest can print a summary of the test run results to the console, along with a link to review the results in the VisualTest app.

For this, add the following code at the end of the test:


It produces results in this format:


Assert Comparison Results

You can aggregate all passed and failed VisualTest comparisons with the following assert:

result = visualTest.getTestRunResult()
assertEqual(result['failed'], 0)  

The structure returned in Python is as follows:

{'passed': 1, 'failed': 0} 


Keep VisualTest’s performance optimized, by periodically doing as follows:

See Also

Publication date: