How to configure Applitools Eyes with Selenium in IntelliJ
Set up Applitools Eyes in a Selenium Java project in IntelliJ, run a visual test, and review baselines and mismatches.
To configure Applitools Eyes with Selenium in IntelliJ, start with Applitools’ official Maven sample, set APPLITOOLS_API_KEY in the test process environment, confirm Chrome and ChromeDriver are compatible, then run the sample test and review its result in the Applitools dashboard. The sample provides a reproducible project structure and its current dependencies; IntelliJ includes Maven support, so a separate Maven installation is not required for this setup.
1. Check the prerequisites
Before opening the project, make sure you have:
- An Applitools account and API key.
- JDK 8 or later.
- IntelliJ IDEA.
- Chrome and a ChromeDriver whose major version matches Chrome.
- The official Applitools Selenium Java basic sample.
IntelliJ bundles Maven, and the sample’s pom.xml declares the dependencies. Let IntelliJ import and resolve the Maven project, or run mvn install from the project directory. The current quickstart does not establish a fixed SDK dependency coordinate or version; use the sample’s pom.xml or current official documentation rather than copying an unverified version.
2. Get the sample project into IntelliJ
- Open the sample repository in a browser and clone or download it.
- In IntelliJ, open the project directory containing
pom.xml. - Allow IntelliJ to import the Maven project and download its dependencies. If resolution does not begin, use the IDE’s Maven project reload action.
- Check that the project is using a JDK 8-or-later installation.
The sample test is src/test/java/com/applitools/example/AcmeBankTests.java. Its source and the repository’s pom.xml are the reference for the exact APIs and dependency versions used by that sample.
3. Set the Applitools API key
Eyes reads the key from the environment variable APPLITOOLS_API_KEY. Set it for the process that starts the test. Do not commit a real key into source code, a checked-in run configuration, or a screenshot.
macOS or Linux
export APPLITOOLS_API_KEY=YOUR_API_KEYIf you launch IntelliJ from this shell, its test processes can inherit the variable. If IntelliJ was already open, a shell export will not update that existing application process. Set the variable in the test’s run configuration, or restart IntelliJ from the shell after exporting it.
Windows Command Prompt
set APPLITOOLS_API_KEY=YOUR_API_KEYThis sets the variable for programs launched from that Command Prompt. Alternatively, add it to the IntelliJ test run configuration’s environment variables so the test process receives it.
Set it in IntelliJ
Create or edit the run configuration for AcmeBankTests and add an environment variable named APPLITOOLS_API_KEY with your key as its value. IntelliJ’s precise menu labels can change across versions; look for the environment variables field in the test run configuration. Keep the value local and do not commit a configuration file that exposes it.
4. Make ChromeDriver available
Selenium must start Chrome successfully before Eyes can capture a checkpoint. The ChromeDriver major version should match the installed Chrome major version. Put the driver executable on your system PATH; the quickstart gives /usr/local/bin as a macOS/Linux location. Check the installed browser and driver versions if initialization fails, since current browser releases and supported driver details change over time.
On macOS or Linux, also confirm that the driver file is executable. On any operating system, verify that the account running IntelliJ can find and execute the driver. A driver mismatch or missing executable is a WebDriver startup problem, not an Eyes baseline problem.
5. Run the visual test
In IntelliJ, run AcmeBankTests after setting the API key in that test’s run configuration. You can also run the sample’s documented Maven command from its root directory:
mvn exec:exec@run-the-tests -Dexec.classpathScope=testThat command runs the test entry point configured by the sample. If Maven cannot resolve dependencies, confirm that IntelliJ or Maven has imported the project and that dependency downloads completed.
6. Understand the Eyes and Selenium lifecycle
Selenium controls the browser and application under test. The Eyes SDK works with the driver to capture screenshots at visual checkpoints, sends those images to Eyes Server for comparison with baselines, and makes results available for review in Test Manager. Applitools’ system overview puts it simply: “The Eyes SDK also uses the driver to capture screenshots.” See the official System Overview and the current Selenium Java quickstart.
The current quickstart’s lifecycle is:
- Create and configure an
Eyesobject. - Start the visual test with
eyes.open. - Use Selenium to navigate to the page and exercise the application.
- Add a visual checkpoint with the current
eyes.checkAPI. - Close the test when its checks are complete.
- In cleanup, abort a test that did not close and quit the WebDriver.
Follow the API shown by the current sample and current SDK documentation. Older examples may use methods such as checkWindow; do not substitute an older snippet for the API in the sample without checking compatibility.
7. Review the first baseline and later differences
On the first run, when no baseline exists for the test, Eyes records the test and uses its images as a baseline. On later runs, it compares checkpoint images against the saved baseline. Open the result in the Applitools dashboard or Test Manager to inspect detected differences. Review a change before accepting it as a new baseline: a changed image can represent a real regression, an intentional design update, or expected dynamic content.
8. Choose a match level for the page
The quickstart describes three principal match levels:
| Match level | What it emphasizes | When it can fit |
|---|---|---|
| Strict | Detailed visual comparison; this is the default. | Stable pages where appearance, including color, matters. |
| Ignore Colors | Disregards color changes while comparing other visual details. | Checks where color variation is expected but other visual changes still matter. |
| Layout | Focuses on overall structure and relative positioning. | Dynamic content areas where text or imagery can vary while layout should remain sound. |
Choose a level based on what the test needs to catch. For changing regions, the quickstart demonstrates using Layout matching on selected page regions. That keeps checks for structure and presence in scope instead of removing all visual validation. Exact APIs and configuration placement are SDK-version dependent, so use the current Java quickstart for the syntax that matches your project.
9. Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| Eyes reports a missing API key or authentication fails. | APPLITOOLS_API_KEY is absent from the test process, misspelled, or unavailable to an already-running IntelliJ process. |
Add the variable to the test run configuration, check its exact name, and rerun. If using a shell export, start IntelliJ from that shell or restart the IDE. |
| WebDriver cannot initialize Chrome. | ChromeDriver is missing, not executable, not on PATH, or has a different major version from Chrome. |
Check both installed versions, make their major versions match, ensure the driver is executable, and make it available on the test process’s PATH. |
| The project shows unresolved Maven dependencies. | Maven import or dependency resolution has not completed, or the environment cannot download the declared dependencies. | Reload the Maven project in IntelliJ. From the project root, try mvn install and inspect the error for the specific dependency or network issue. |
| The test runs but no visual result appears. | The wrong test or run configuration was launched, the checkpoint was not reached, or the test did not close normally. | Run the sample test, confirm its navigation reaches the check, inspect the test output for errors, and verify its cleanup closes or aborts the Eyes test and quits the driver. |
| A later run reports many differences. | The page changed, a baseline needs review, the wrong match level is being used, or dynamic content varies between runs. | Inspect the changed regions in Test Manager. Decide whether the change is intended, then update the baseline only when appropriate. For dynamic regions, consider a suitable match level such as Layout rather than dropping the region from visual checks. |
| The driver starts but a checkpoint captures an unexpected state. | The page may not have reached the intended state when the check runs. | Review the sample’s Selenium navigation and interactions so the checkpoint occurs after the intended application state is ready. Consult current SDK documentation for supported waiting and check configuration. |
10. Reliability, speed, and cost considerations
- Keep setup failures separate from visual failures. Chrome/driver startup and Maven dependency resolution happen before useful visual comparisons. Resolve those first when a run fails early.
- Make checkpoints intentional. Capture after the application reaches a meaningful state; otherwise a technically successful test can compare a loading or transitional page.
- Plan for changing pages. Dynamic content can create noisy differences. Use the match strategy that preserves the aspects you want checked, and review changes before accepting a baseline.
- Protect the API key. Use local environment configuration and avoid putting secrets in source control or shared screenshots.
- Check current compatibility guidance. Browser and driver versions, IDE controls, and SDK APIs can change. The reviewed setup material does not establish current pricing, an uptime figure, a benchmark, or a browser support matrix, so consult Applitools’ current documentation and account details for those decisions.
Or skip the browser setup
If your goal is to capture a page image from code rather than run a Selenium visual regression test, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF. See the ScreenshotNeo API documentation 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}`);ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo’s free plan and get 1,000 screenshots a month with no card.
Frequently asked questions
Can I add Eyes to an existing Selenium Maven project?
Yes. The official sample is a useful reference for dependencies and test lifecycle. Compare its current pom.xml and test setup with your project, and use the current Java SDK documentation for the version and configuration you adopt.
Does creating a baseline mean the page is correct?
No. A first run establishes the comparison point. Review the captured page and later differences in Test Manager so an incorrect first state does not become an accepted reference.
Is ScreenshotNeo a replacement for Applitools Eyes?
They address different workflows. Eyes participates in Selenium visual tests and compares checkpoints against baselines. ScreenshotNeo provides screenshot and PDF capture by API and MCP; the one-call capture does not itself establish the Eyes baseline comparison workflow.
