Applitools Eyes Selenium Java Setup for a Website
Add visual checkpoints to a Selenium Java website test, run the official Maven example, and review browser targets, match levels, and baseline changes.
To set up Applitools Eyes with Selenium Java, configure an Eyes runner and API key, wrap an existing Selenium WebDriver test with an Eyes test, and call eyes.check() at the page states you want to compare. The quickest starting point is Applitools’ official Selenium Java quickstart and its Maven example project.
Selenium still drives the website. Eyes captures visual checkpoints through the driver, compares them with baselines, and presents differences in the Eyes Test Manager. [Applitools system overview]
1. Check the prerequisites
- An Applitools account and API key.
- JDK 8 or later, Maven, and an up-to-date Google Chrome.
- A ChromeDriver whose major version matches your installed Chrome major version. A mismatch can cause Selenium WebDriver initialization to fail.
These are the prerequisites in the current official quickstart. Check the quickstart again if your project uses a different browser or a newer SDK; dependency and API examples can change.
2. Set the API key outside your source code
Set the environment variable APPLITOOLS_API_KEY in the shell or CI environment where Maven will run. Do not commit a real key to the repository.
# macOS or Linux
export APPLITOOLS_API_KEY=<your-api-key>
# Windows Command Prompt
set APPLITOOLS_API_KEY=<your-api-key>For CI, add the key through the CI platform’s secret-variable mechanism, then expose it to the test process using the same variable name.
3. Clone and run the official Java example
The official project provides a concrete Maven setup and sample test at src/test/java/com/applitools/example/AcmeBankTests.java. Start there to avoid guessing a dependency version or copying an outdated SDK API.
git clone https://github.com/applitools/example-selenium-java-basic.git
cd example-selenium-java-basic
mvn install
mvn exec:exec@run-the-tests -Dexec.classpathScope=testThe quickstart invocation runs the example test. The first run can create the baseline for the test; subsequent runs compare checkpoints against it. Keep the API key available in the same environment for both Maven commands.
4. Understand the Eyes test flow
An Eyes test surrounds the WebDriver work that you already perform. Configure the runner and test, open Eyes around the driver, navigate and interact with the site through Selenium, call eyes.check() at meaningful states, then close Eyes and shut down the browser. The quickstart’s sample includes full-window checkpoints and demonstrates Layout matching for selected dynamic elements.
- Configure: create the Eyes runner and a test configuration, including the API key and batch name.
- Open: associate the test with the Selenium driver, application name, and test name.
- Drive the site: use Selenium to navigate, sign in with test data, and reach a stable state.
- Check: capture a named checkpoint with
eyes.check(). - Close and clean up: close the Eyes test on success; abort an open Eyes test if an earlier operation fails, and always quit the browser.
Use the code in the current Java quickstart as the compilable implementation of those steps. The precise SDK classes and configuration methods are version-sensitive, so retain the dependency versions and API shape from that sample rather than mixing snippets from different SDK generations.
Where to put checkpoints
Add a checkpoint after the page has reached the state that matters to the user, such as the landing page after login, a completed form, or a confirmation view. Give each checkpoint a stable descriptive name. A checkpoint is a visual test step; the Eyes dashboard uses those steps to show where a difference occurred.
Wait for meaningful readiness conditions before checking: a key element is visible, a loading indicator has disappeared, or the application has finished a relevant action. Fixed sleeps can make tests slower and still capture too early when the page is delayed.
5. Choose browser targets and match levels
Choose browser and viewport targets to represent environments your site supports and your team intends to cover. The quickstart demonstrates desktop browser/viewport targets and Chrome device emulation. There is no universal target list: start with the environments that matter to your users and add coverage when it addresses a real risk.
| Match level | What it is for | Use it when |
|---|---|---|
| Strict (default) | Flags visual differences intended to be perceptible, including content, color, and position changes. | The page is relatively stable and those changes matter. |
| Ignore Colors | Like Strict while ignoring color changes. | Color variation is expected, but text, graphics, and layout should still be checked. |
| Layout | Focuses on page structure and relative element positions; dynamic content is not flagged as a content difference. | Content changes frequently but structural movement or missing elements should remain visible. |
These are the three main levels described by the current Selenium Java quickstart. See also Applitools’ match-level guidance. The choice changes which differences are reported. Prefer a narrowly scoped Layout rule for known dynamic regions, while keeping the rest of the page at the level that catches the regressions you care about. Do not make an entire page permissive just to eliminate one noisy region.
6. Review the results and manage baselines
Open the Applitools Dashboard after the run. The quickstart describes a batch list, test status, test steps corresponding to eyes.check() calls, and browser/device information. The system overview explains that the Eyes Server compares captured images with stored baselines and the Test Manager is where reviewers inspect differences and manage baselines. [System overview]
- Find the batch and test name you ran.
- Open each checkpoint and inspect the baseline, new checkpoint, and highlighted differences in context.
- Decide whether each change is an intended product update or a regression.
- Save a new baseline only when the change is intentional and the reviewed result is the desired future reference.
A first run may establish the baseline. Later runs compare against it. Avoid approving every difference automatically: an updated baseline changes what future runs treat as expected.
7. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| WebDriver fails during startup | Chrome and ChromeDriver major versions do not match, or the driver is unavailable. | Check the installed Chrome version and use a corresponding ChromeDriver. Confirm the executable is available to the test process. |
| Eyes cannot authenticate or the run is not associated with the expected account | APPLITOOLS_API_KEY is missing, misspelled, or not inherited by Maven. |
Set the variable in the shell or CI job that launches Maven. Verify its presence without printing the secret into build logs. |
| Maven cannot resolve dependencies or the test does not compile | Dependency download failed, or code and dependency versions are from different SDK generations. | Run the official project’s Maven commands and use its matching source and dependency configuration. Check network access to the configured Maven repositories. |
| The checkpoint is blank, incomplete, or inconsistent | The test captured before the relevant page state was ready, or the application is still loading. | Wait for a stable, meaningful page condition before eyes.check(). Use deterministic test data and avoid capturing transient states unless those states are the subject of the test. |
| Many differences appear on every run | Dynamic content, changing test data, animation, or unstable page readiness is changing the capture. | Stabilize test data and timing. For known dynamic areas, consider a targeted Layout rule as shown in the official example; preserve stricter checking elsewhere. |
| A difference is flagged after an expected release | The baseline represents the previous intended design. | Review the diff in context and update the baseline only after confirming that the new appearance is correct. |
8. Performance, reliability, and cost considerations
- Runtime: browser startup, navigation, and page readiness are usually part of the work around a visual checkpoint. Avoid duplicate checkpoints that do not answer a distinct visual question, and wait on application conditions rather than long fixed delays.
- Reliability: use stable test data, consistent viewport targets, and predictable page state. Ensure browser shutdown and Eyes cleanup happen even when Selenium actions fail, following the cleanup pattern in the official sample.
- Coverage: every additional browser/device target adds execution coverage and work to review. Select targets based on supported environments, not a maximal list by default.
- Review effort: broad permissive matching can hide changes; overly strict checks on volatile content can create noise. Scope matching decisions to the content that actually varies.
- Service cost: the supplied setup documentation establishes the account and API-key workflow but does not establish current pricing or plan limits. Check Applitools’ current account and billing information before estimating project cost.
Or skip the browser setup
If you need website screenshots rather than visual regression baselines, ScreenshotNeo is a website screenshot API and MCP server for developers. A single GET request captures a URL as PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for parameters.
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 capture. 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 per month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.
FAQ
Does Eyes replace Selenium?
No. Selenium drives the application; Eyes adds visual checkpoints to that test flow.
Should I approve every new baseline after the first run?
No. Review the visual change and update the baseline only when it represents the intended appearance.
Can I use Layout matching for the whole site?
You can configure matching for your intended scope, but Layout tolerates content differences. Apply it where that behavior is appropriate so important visual changes remain detectable elsewhere.
Where do I see which checkpoint failed?
In the Eyes Dashboard, open the batch and test to inspect status, checkpoint steps, and browser/device details.
