Applitools Eyes SDK for Python (Common Code)

6.7.2 · active · verified Mon Apr 13

Applitools `eyes-common` is the foundational, common code package for the Applitools Eyes Python SDK. It provides core functionalities for visual testing that are leveraged by specific integration packages like `eyes-selenium`, `eyes-playwright`, and `eyes-appium`. The library is actively maintained, with frequent updates to its dependent SDKs, reflecting a continuous release cadence. The current version on PyPI is 6.7.2.

Warnings

breaking Migration from Applitools Eyes Python SDK v3 to v4 (specifically for `eyes-selenium`) introduced significant API changes, moving from a 'Classic API' (e.g., `check_window()`) to a 'Fluent API' (`check()`). Users migrating older tests will need to update their checkpoint calls.
Fix: Rewrite visual checkpoints using the `eyes.check(name, Target.window())` or `eyes.check(name, Target.region(...))` fluent API. Refer to the Applitools migration guides for specific SDKs.
gotcha Failing to set the `APPLITOOLS_API_KEY` environment variable will prevent tests from running and uploading results to the Applitools Test Manager. The SDK requires this key for authentication.
Fix: Ensure `APPLITOOLS_API_KEY` is set in your environment before running tests. For example: `export APPLITOOLS_API_KEY='your_api_key'`.
gotcha Not calling `eyes.close()` at the end of a test (e.g., due to an unhandled exception) can result in tests being marked as 'Aborted' in the Applitools Test Manager and test results not being finalized or reported correctly.
Fix: Always wrap your test execution in a `try...finally` block to ensure `eyes.close()` is called. Additionally, `runner.get_all_test_results(raise_exception=True)` should be called in the final block to retrieve and report all test results, especially when using a `Runner`.
gotcha `eyes-common` is a shared dependency. Users should install and use the specific Applitools Eyes SDK for their testing framework (e.g., `eyes-selenium` for Selenium, `eyes-playwright` for Playwright, `eyes-appium` for Appium). Directly importing from `eyes-common` for core functionality is generally not the intended pattern, though some common utilities might be exposed.
Fix: Install the appropriate Applitools SDK for your test framework (e.g., `pip install eyes-selenium`). All core `Eyes` objects and configurations should be imported from the specific SDK package (e.g., `from applitools.selenium import Eyes`).
gotcha When using `VisualGridRunner` for the Ultrafast Grid, concurrency might be limited to 1 for free Applitools accounts, which can affect the parallel execution benefits.
Fix: Be aware of your Applitools account's concurrency limits. For increased concurrency with the Ultrafast Grid, a paid Applitools account is typically required.

Install

pip install eyes-selenium Install with Selenium WebDriver integration (most common)
pip install eyes-playwright Install with Playwright integration
pip install eyes-appium Install with Appium integration

Imports

Eyes
```
from applitools.selenium import Eyes
```
The primary class for interacting with Applitools Eyes. The specific import path depends on the integration (e.g., applitools.selenium, applitools.playwright).
Configuration
```
from applitools.selenium import Configuration
```
Used to configure the Eyes object, including API key, batch info, and server URL. Path depends on integration.
BatchInfo
```
from applitools.common.batch_info import BatchInfo
```
BatchInfo is a common component; import from `applitools.common.batch_info` is generally preferred, although it might be re-exported by specific SDKs.
Target
```
from applitools.selenium import Target
```
Used to define what part of the application is being visually checked (e.g., window, element, region). Path depends on integration.
ClassicRunner
```
from applitools.selenium import ClassicRunner
```
Manages multiple Eyes sessions without the Ultrafast Grid. Path depends on integration.
VisualGridRunner
```
from applitools.selenium import VisualGridRunner
```
Manages Eyes sessions when using the Ultrafast Grid for parallel cross-browser/device testing. Path depends on integration.

Quickstart

This quickstart demonstrates a basic visual test using `eyes-selenium` to integrate with Selenium WebDriver. It initializes Applitools Eyes, navigates to a webpage, performs a visual checkpoint, and then closes the test. The `APPLITOOLS_API_KEY` must be set as an environment variable for authentication. It also correctly handles the `runner` and `eyes` object lifecycle.

import os
from selenium import webdriver
from applitools.selenium import Eyes, Target, Configuration, ClassicRunner
from applitools.common.batch_info import BatchInfo

# Set your Applitools API key as an environment variable APPLITOOLS_API_KEY
# For example: export APPLITOOLS_API_KEY='YOUR_API_KEY'
APPLITOOLS_API_KEY = os.environ.get('APPLITOOLS_API_KEY', '')

if not APPLITOOLS_API_KEY:
    raise ValueError("APPLITOOLS_API_KEY environment variable not set.")

runner = ClassicRunner()
eyes = Eyes(runner)

config = Configuration()
config.set_api_key(APPLITOOLS_API_KEY)
config.set_app_name('Hello World App')
config.set_test_name('My First Visual Test')
config.set_batch(BatchInfo('Python Quickstart Batch'))
eyes.set_configuration(config)

driver = None
try:
    # Initialize a Chrome WebDriver (ensure you have chromedriver installed and in PATH)
    driver = webdriver.Chrome()

    # Navigate to a URL
    driver.get('https://applitools.com/helloworld')

    # Start the visual test
    eyes.open(driver)

    # Visual checkpoint #1.
    eyes.check('Hello World Page', Target.window())

    # Click a button to change content (example for a second checkpoint)
    # driver.find_element_by_css_selector('button').click()
    # eyes.check('Hello World Page after click', Target.window())

    # End the test
    eyes.close(raise_exception=True)

finally:
    # Close the browser
    if driver:
        driver.quit()
    # Close the Eyes runner if it's still open (e.g., due to an aborted test)
    runner.get_all_test_results(raise_exception=True)

print("Visual test completed. Check Applitools Test Manager for results.")

view raw JSON →