Applitools Eyes SDK for Selenium Python

Warnings

• breaking The GitHub repository `applitools/eyes.selenium.python` has been deprecated. While the `eyes-selenium` PyPI package remains the correct installation, users should refer to `applitools/eyes.sdk.python` for the latest source and potentially more up-to-date examples if direct repository interaction is needed.
  Fix: Ensure you are using the `eyes-selenium` PyPI package for installation and consult the Applitools documentation (applitools.com/docs) for the latest usage patterns.
• gotcha The version of `ChromeDriver` (or any other browser driver) used with Selenium WebDriver must precisely match the installed version of the Chrome browser to avoid `WebDriverException` errors during initialization.
  Fix: Regularly update `ChromeDriver` to match your Chrome browser version. Consider using `webdriver-manager` for automated driver management if not already in use.
• gotcha Applitools tests require the `APPLITOOLS_API_KEY` environment variable to be set for authentication with the Applitools Eyes server.
  Fix: Set `APPLITOOLS_API_KEY` in your environment (e.g., `export APPLITOOLS_API_KEY='YOUR_API_KEY'`). Optionally, `eyes.api_key` can be set programmatically, but environment variables are recommended.
• gotcha Every Applitools Eyes test session must begin with `eyes.open()` and conclude with `eyes.close()` to ensure proper test execution and result reporting. Failing to call `close()` can lead to abandoned tests.
  Fix: Always wrap your visual test logic within a `try...finally` block to ensure `eyes.close()` is called, even if exceptions occur. For runners, ensure `runner.get_all_test_results()` is called at the end of all tests.
• deprecated The synchronous `eyes.close()` method returns a single test result. For parallel execution or when using runners (like `VisualGridRunner`), it's recommended to use asynchronous closing mechanisms (`eyes.close_async()`) followed by `runner.get_all_test_results()` to retrieve all results efficiently.
  Fix: When using `VisualGridRunner` or `ClassicRunner`, call `eyes.close()` for each test instance (this will internally handle async if needed), and then `runner.get_all_test_results()` once after all tests have completed.

Install

• pip install eyes-selenium Install latest version

Imports

• Eyes

  from applitools.selenium import Eyes

  Main class for Applitools Eyes functionality.
• Target

  from applitools.selenium import Target

  Used to define what to check in a visual test (e.g., `Target.window()`).
• VisualGridRunner

  from applitools.selenium import VisualGridRunner

  Manages multiple Eyes test sessions, especially with the Ultrafast Grid. Recommended for parallel execution.
• ClassicRunner

  from applitools.selenium import ClassicRunner

  Manages multiple Eyes test sessions without the Ultrafast Grid.
• BatchInfo

  from applitools.common import BatchInfo

  Groups related test runs together in the Applitools Test Manager.

Quickstart

This quickstart demonstrates a basic visual test using `eyes-selenium` with `pytest` and Selenium WebDriver. It initializes a `VisualGridRunner` for efficient test management, sets the Applitools API key, and performs visual checkpoints on a web page. The `APPLITOOLS_API_KEY` must be set as an environment variable. The example includes navigating to a demo site, logging in, and performing visual checks on both the login and dashboard pages.

import os
import pytest
from selenium import webdriver
from applitools.selenium import Eyes, Target, VisualGridRunner, 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.")

@pytest.fixture(scope='session')
def applitools_runner():
    runner = VisualGridRunner()
    yield runner
    # Wait for all visual tests to complete and get results
    print("\nVisual test results:\n", runner.get_all_test_results(raise_exception=True))

@pytest.fixture(scope='function')
def driver():
    # Ensure your ChromeDriver version matches your Chrome browser version
    options = webdriver.ChromeOptions()
    # options.add_argument('--headless') # Uncomment for headless execution
    driver = webdriver.Chrome(options=options)
    driver.implicitly_wait(10)
    yield driver
    driver.quit()

def test_applitools_example(driver, applitools_runner):
    eyes = Eyes(runner=applitools_runner)
    eyes.api_key = APPLITOOLS_API_KEY
    eyes.batch = BatchInfo('My Python App') # Group tests in Test Manager
    
    try:
        # Open Eyes with the WebDriver, application name, test name, and viewport size
        eyes.open(driver=driver, app_name='My App', test_name='Login Page Test', viewport_size={'width': 800, 'height': 600})
        
        driver.get('https://demo.applitools.com/')
        eyes.check('Login Window', Target.window().fully())
        
        driver.find_element('id', 'username').send_keys('user')
        driver.find_element('id', 'password').send_keys('password')
        driver.find_element('id', 'log-in').click()
        
        eyes.check('App Dashboard', Target.window().fully())
        
    finally:
        # Close Eyes to finish the test session
        eyes.close()