Applitools Eyes Core SDK Server (Python Client)

Warnings

• gotcha Direct import and usage of `core-universal` is generally not intended for end-users. It serves as an internal communication layer for higher-level Applitools SDKs (e.g., `applitools.selenium`, `applitools.playwright`). Developers should use the appropriate specialized SDK for their testing framework.
  Fix: Use a specialized Applitools SDK (e.g., `applitools-eyes-selenium`, `applitools-eyes-playwright`) that wraps `core-universal` for end-to-end visual testing.
• breaking Applitools Core Tools (which `core-universal` is a part of) version 4.8.0+ no longer supports Python 3.7 and 3.8. Attempting to use these Python versions with newer Core Tools may result in errors.
  Fix: Upgrade your Python environment to version 3.10 or higher. Python 3.7 and 3.8 are End-of-Life (EOL).
• gotcha The Applitools API Key (`APPLITOOLS_API_KEY`) is crucial for authenticating with the Applitools service. Forgetting to set it, or setting it incorrectly, will prevent tests from running or uploading results.
  Fix: Ensure the `APPLITOOLS_API_KEY` environment variable is correctly set with your valid Applitools API key before running tests. Alternatively, set it programmatically using `eyes.api_key = 'YOUR_API_KEY'`.
• gotcha Mutable default arguments in Python functions (e.g., `def func(arg=[]):`) can lead to unexpected shared state across function calls. While not specific to `core-universal`, this is a common Python footgun that can affect custom helper functions in test automation.
  Fix: Initialize mutable default arguments inside the function if a fresh object is needed for each call, typically by using `None` as the default and checking for it: `def func(arg=None): if arg is None: arg = []`.

Install

• pip install core-universal Install core-universal

Imports

• Eyes

  from applitools.selenium import Eyes

  End-users typically import from specific Applitools SDKs (e.g., selenium, playwright, appium) that utilize `core-universal` internally, rather than importing directly from `core-universal`.
• ClassicRunner

  from applitools.selenium import ClassicRunner

  Used for managing multiple Eyes sessions without the Ultrafast Grid.
• VisualGridRunner

  from applitools.selenium import VisualGridRunner

  Used for managing multiple Eyes sessions with the Ultrafast Grid for cross-browser testing.

Quickstart

This quickstart demonstrates a basic visual test using `applitools.selenium`, which is a common way to interact with Applitools Eyes functionality. It initializes a Selenium WebDriver, opens an Applitools Eyes test, performs visual checkpoints on different pages, and then closes the test. Remember to set the `APPLITOOLS_API_KEY` environment variable.

import os
from selenium import webdriver
from applitools.selenium import Eyes, ClassicRunner, Target

def run_applitools_test():
    # Set your Applitools API key from environment variable
    # For a quickstart, ensure APPLITOOLS_API_KEY is set in your environment
    api_key = os.environ.get('APPLITOOLS_API_KEY', 'YOUR_APPLITOOLS_API_KEY_HERE')
    if not api_key or api_key == 'YOUR_APPLITOOLS_API_KEY_HERE':
        print("Warning: APPLITOOLS_API_KEY environment variable not set. Test might fail.")
        # In a real scenario, you'd raise an error or handle this more robustly

    runner = ClassicRunner()
    eyes = Eyes(runner)
    eyes.api_key = api_key

    # Configure Eyes to log to console for debugging
    eyes.log_handler = None # Set to StreamMessageLogger() for console output

    driver = None
    try:
        # Initialize a headless Chrome browser (ensure chromedriver is in PATH)
        options = webdriver.ChromeOptions()
        options.add_argument('--headless')
        driver = webdriver.Chrome(options=options)

        # Start the Applitools Eyes test
        driver = eyes.open(driver=driver, app_name='My Python App', test_name='Simple Login Test', viewport_size={'width': 800, 'height': 600})

        # Navigate to a URL and perform visual checkpoints
        driver.get('https://demo.applitools.com')
        eyes.check('Login Page', Target.window().fully())

        # Perform some actions (e.g., filling a form, clicking buttons)
        # For this example, just navigate to another page
        driver.find_element_by_id('log-in').click()
        eyes.check('App Page', Target.window().fully())

        # Close the Eyes test and get results
        results = eyes.close(raise_exception=True)
        print(f"Applitools Test Results: {results}")

    except Exception as e:
        print(f"Applitools test failed: {e}")
    finally:
        if driver:
            driver.quit()
        # Always abort the test if it's open, even if an exception occurred
        eyes.abort_if_not_closed()

if __name__ == '__main__':
    run_applitools_test()