How to Get Started with Applitools and Robot Framework
Set up Applitools Eyes with Robot Framework, configure your API key, add visual checks, and review baselines with this beginner walkthrough.
To get started with Applitools and Robot Framework, install Applitools EyesLibrary in your Python environment, configure an Applitools API key, run the official quickstart, then add Eyes session keywords around the browser or app actions in your own suite. EyesLibrary connects Robot Framework tests to the Applitools Eyes Python SDK; SeleniumLibrary and AppiumLibrary can drive browser and mobile application tests respectively. Start with Applitools’ Robot Framework quickstart and check the current EyesLibrary keyword reference for exact arguments.
1. Prepare a Python and Robot Framework environment
Use a virtual environment so the package installation and test run use the same Python interpreter. Robot Framework’s getting-started documentation covers environment setup and library selection. Choose the automation library appropriate to the application: EyesLibrary’s reference names SeleniumLibrary and AppiumLibrary as companion libraries.
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install robotframework eyes_robotframeworkThe official Applitools quickstart documents installing eyes_robotframework. Package releases and compatibility can change, so check its current instructions and lock the versions that work in your CI environment. On Windows, activate the environment with .venv\\Scripts\\activate.
2. Get the official sample running
The quickstart repository provides a sample suite and its configuration workflow. Its documented commands are:
git clone https://github.com/applitools/robotframework-quickstart.git
cd robotframework-quickstart
python3 -m pip install eyes_robotframework
python3 -m EyesLibrary init-config
python3 -m robot web.robotRun these in the environment you intend to use. If you already installed the package in a project environment, activate that environment before running the commands. The sample is the quickest way to see a working suite and configuration together.
3. Configure the Applitools API key
EyesLibrary supports an APPLITOOLS_API_KEY environment variable and an applitools.yaml configuration file. Prefer an environment variable or your CI secret store for shared environments so a real key does not enter source control.
export APPLITOOLS_API_KEY="YOUR_API_KEY"
python3 -m EyesLibrary lint-config applitools.yamlThe lint command is documented by the library reference. Use the configuration file initialized by init-config, and follow the current reference for the accepted YAML fields. Do not commit a real key in the YAML file. Ensure the process launching Robot Framework receives the environment variable; setting it in an interactive shell does not automatically make it available to every IDE or CI job.
4. Add Eyes checks to a Robot Framework suite
The general lifecycle is: start the browser or app with its automation library, open an Eyes session, make the relevant visual check, then close the Eyes session asynchronously. The exact keyword names, required arguments, and configuration vary with the installed library version and whether the test targets a browser or native app. Use the current EyesLibrary keyword reference when adapting this outline; avoid copying arguments from an older tutorial without checking them.
*** Settings ***
Library SeleniumLibrary
Library EyesLibrary
*** Test Cases ***
Check the home page visually
Open Browser https://example.com chrome
# Open an Eyes session using the current EyesLibrary keyword and required arguments.
# Check the intended window, region, or frame after the page reaches its expected state.
# Close the Eyes session asynchronously using the current reference keyword.
Close BrowserThis is a structural outline, not a complete runnable Eyes test: the dossier’s official reference does not establish one universal set of keyword arguments for every browser, app, and SDK configuration. The quickstart’s web.robot is the runnable example to adapt. Keep the browser setup, Eyes lifecycle, and cleanup in a predictable order so failures are easier to diagnose.
Choose the visual check scope
- Whole window: use when the complete visible page or application view is the intended assertion.
- Region: use when the test should focus on a specific part of the screen.
- Frame: use when the content under test is inside a frame and the supported keyword configuration calls for a frame check.
Pick the narrowest scope that matches the behavior you want to protect. A region can reduce irrelevant changes outside the component under test; a whole-window check can catch layout changes that affect the broader page. Confirm the exact region and frame syntax in the current keyword reference.
5. Review the first baseline and test result
Applitools’ first-steps material describes the first test as creating a provisional baseline. Review that result in Eyes Test Manager and approve it only after confirming the page, data, viewport, and state are the ones the test is meant to preserve. A first run is not automatically a correct baseline. Later runs surface visual differences for review; determine whether each is an intended design change or a regression before updating a baseline.
The vendor’s Robot Framework tutorial demonstrates a basic run and then a deliberately changed page. It was published in 2021, so use it as background and follow current Applitools documentation for present dashboard labels and review workflow.
6. Keep runs repeatable
- Use the same locked Python, Robot Framework, EyesLibrary, browser automation library, and browser versions locally and in CI.
- Keep test data and page state stable before taking a visual check.
- Run the suite with the same environment variables and configuration source in each environment.
- Review baseline changes intentionally; do not accept visual differences only to make a build green.
- Use the documented asynchronous close behavior and make sure the suite reaches cleanup even when an earlier action fails.
Exact dependency compatibility changes over time. The surfaced EyesLibrary reference identifies version 5.6.0, but that does not establish it as the latest release or prove compatibility with every current Python and Robot Framework version. Consult current release documentation and pin versions after validating your own environment.
7. Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
No module named EyesLibrary or package import failure |
The package was installed into a different Python environment from the one running Robot Framework. | Activate the intended virtual environment; use python3 -m pip show eyes_robotframework and launch with python3 -m robot from that same interpreter. |
| API key missing or authentication failure | The test process cannot see the key, or the configuration source is missing or invalid. | Check that APPLITOOLS_API_KEY is set in the shell/CI job that starts Robot Framework, or inspect the configuration without exposing the secret. Run the documented config lint command. |
| Unknown keyword or wrong argument count | The suite uses syntax from another EyesLibrary release or an older tutorial. | Check the installed package’s current keyword documentation and align the suite with its exact keyword names and arguments. |
| Browser or app fails before the visual check | The companion automation library, driver, application, or target environment is not ready. | First run the browser/app setup without Eyes and confirm that it reaches the intended page or screen. Then add Eyes keywords back into the lifecycle. |
| Unexpected visual differences between runs | The test is capturing a different page state, viewport, data set, or environment. | Stabilize the application state and test inputs, compare the intended capture scope, and review the difference before changing a baseline. |
| Config lint reports invalid configuration | The file does not match the schema expected by the installed library or has a formatting error. | Initialize or update configuration using the current package workflow, check YAML indentation and field names against the matching reference, then lint again. |
8. Performance, reliability, and cost considerations
Visual checks add work to a UI test because the application must reach the capture state and the Eyes session must complete. Keep each check purposeful: broad screenshots catch broad changes but can include unrelated page variability, while focused regions make the assertion narrower. Stable page state and repeatable dependencies help make results actionable.
The research sources do not establish current Applitools pricing, plan limits, or a compatibility matrix, so check the vendor’s current documentation and account details for those decisions. This guide does not claim a measured runtime or reliability figure.
Or skip the browser setup
If you need a screenshot artifact without wiring up browser automation and a visual-testing session, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF, and its screenshot options include full-page capture, CSS selector element capture, viewport presets, custom CSS and JavaScript, wait conditions, and more. See the ScreenshotNeo API docs for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);ScreenshotNeo accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. Sign up for 1,000 free screenshots a month with no card.
FAQ
Can I use EyesLibrary without SeleniumLibrary?
The reference names both SeleniumLibrary and AppiumLibrary as companion automation libraries. Which one fits depends on whether the suite drives a browser or an app; check current setup guidance for your target.
Should the first visual result be approved automatically?
No. Treat the first baseline as provisional and review the captured state and intended design before approval.
Where should I look for current keyword syntax?
Use the EyesLibrary keyword reference that corresponds to the installed package version. The older tutorial is supplementary and may not match current labels or syntax.
