{"id":5620,"library":"eyes-common","title":"Applitools Eyes SDK for Python (Common Code)","description":"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.","status":"active","version":"6.7.2","language":"en","source_language":"en","source_url":"https://applitools.com/docs/api-ref/sdk-api-reference-python/","tags":["visual testing","applitools","selenium","playwright","appium","ui testing","automation"],"install":[{"cmd":"pip install eyes-selenium","lang":"bash","label":"Install with Selenium WebDriver integration (most common)"},{"cmd":"pip install eyes-playwright","lang":"bash","label":"Install with Playwright integration"},{"cmd":"pip install eyes-appium","lang":"bash","label":"Install with Appium integration"}],"dependencies":[{"reason":"Required if using the 'eyes-selenium' integration package for web browser automation.","package":"selenium","optional":true},{"reason":"Required if using the 'eyes-playwright' integration package for web browser automation.","package":"playwright","optional":true},{"reason":"Required if using the 'eyes-appium' integration package for mobile app automation.","package":"Appium-Python-Client","optional":true}],"imports":[{"note":"The primary class for interacting with Applitools Eyes. The specific import path depends on the integration (e.g., applitools.selenium, applitools.playwright).","symbol":"Eyes","correct":"from applitools.selenium import Eyes"},{"note":"Used to configure the Eyes object, including API key, batch info, and server URL. Path depends on integration.","symbol":"Configuration","correct":"from applitools.selenium import Configuration"},{"note":"BatchInfo is a common component; import from `applitools.common.batch_info` is generally preferred, although it might be re-exported by specific SDKs.","wrong":"from applitools.selenium import BatchInfo","symbol":"BatchInfo","correct":"from applitools.common.batch_info import BatchInfo"},{"note":"Used to define what part of the application is being visually checked (e.g., window, element, region). Path depends on integration.","symbol":"Target","correct":"from applitools.selenium import Target"},{"note":"Manages multiple Eyes sessions without the Ultrafast Grid. Path depends on integration.","symbol":"ClassicRunner","correct":"from applitools.selenium import ClassicRunner"},{"note":"Manages Eyes sessions when using the Ultrafast Grid for parallel cross-browser/device testing. Path depends on integration.","symbol":"VisualGridRunner","correct":"from applitools.selenium import VisualGridRunner"}],"quickstart":{"code":"import os\nfrom selenium import webdriver\nfrom applitools.selenium import Eyes, Target, Configuration, ClassicRunner\nfrom applitools.common.batch_info import BatchInfo\n\n# Set your Applitools API key as an environment variable APPLITOOLS_API_KEY\n# For example: export APPLITOOLS_API_KEY='YOUR_API_KEY'\nAPPLITOOLS_API_KEY = os.environ.get('APPLITOOLS_API_KEY', '')\n\nif not APPLITOOLS_API_KEY:\n    raise ValueError(\"APPLITOOLS_API_KEY environment variable not set.\")\n\nrunner = ClassicRunner()\neyes = Eyes(runner)\n\nconfig = Configuration()\nconfig.set_api_key(APPLITOOLS_API_KEY)\nconfig.set_app_name('Hello World App')\nconfig.set_test_name('My First Visual Test')\nconfig.set_batch(BatchInfo('Python Quickstart Batch'))\neyes.set_configuration(config)\n\ndriver = None\ntry:\n    # Initialize a Chrome WebDriver (ensure you have chromedriver installed and in PATH)\n    driver = webdriver.Chrome()\n\n    # Navigate to a URL\n    driver.get('https://applitools.com/helloworld')\n\n    # Start the visual test\n    eyes.open(driver)\n\n    # Visual checkpoint #1.\n    eyes.check('Hello World Page', Target.window())\n\n    # Click a button to change content (example for a second checkpoint)\n    # driver.find_element_by_css_selector('button').click()\n    # eyes.check('Hello World Page after click', Target.window())\n\n    # End the test\n    eyes.close(raise_exception=True)\n\nfinally:\n    # Close the browser\n    if driver:\n        driver.quit()\n    # Close the Eyes runner if it's still open (e.g., due to an aborted test)\n    runner.get_all_test_results(raise_exception=True)\n\nprint(\"Visual test completed. Check Applitools Test Manager for results.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"Introduced in v4.x, impacts users upgrading from v3.x or older."},{"fix":"Ensure `APPLITOOLS_API_KEY` is set in your environment before running tests. For example: `export APPLITOOLS_API_KEY='your_api_key'`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of your Applitools account's concurrency limits. For increased concurrency with the Ultrafast Grid, a paid Applitools account is typically required.","message":"When using `VisualGridRunner` for the Ultrafast Grid, concurrency might be limited to 1 for free Applitools accounts, which can affect the parallel execution benefits.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}