Applitools Eyes Integration with Jenkins for Web Screenshots
Connect Applitools Eyes visual tests to Jenkins, link each run to its build report, and troubleshoot the batch ID, pipeline, and server setup.
To connect Applitools Eyes visual test results to a Jenkins build, install the Applitools Eyes Plugin, enable it for a freestyle job or wrap the test command in the plugin’s Applitools() pipeline block, then set the Eyes SDK batch from the Jenkins-provided APPLITOOLS_BATCH_ID and APPLITOOLS_BATCH_NAME environment variables. The plugin links that batch to the Jenkins build report; Eyes captures checkpoints through your test framework, compares them with baselines, and reports visual differences for review. The official Jenkins walkthrough dates to March 6, 2021, so check current plugin maintenance and Jenkins compatibility before relying on version-specific details.
What this integration does
Jenkins runs the application test job; the Eyes plugin associates the job with an Eyes batch; and the Eyes SDK in your test captures visual checkpoints. The SDK sends screenshots to the Eyes server, which compares them with stored baselines and returns differences. You review the results and manage baselines in Eyes Test Manager. See Applitools’ system overview.
This integration does not create visual tests by itself. Your existing driver and test code must open the application, place the application in the state you want to check, and invoke an Eyes checkpoint. Visual testing is a regression workflow: the first run establishes baselines; later runs report changes. Accept a difference when it represents an intended UI change, and reject or investigate a difference that indicates a defect. See Applitools’ visual testing overview.
Before you configure Jenkins
- You have a Jenkins job that runs a web test suite using an Eyes-supported SDK and application driver.
- Your test process can access the Eyes server you intend to use.
- Your Eyes API key is available to the test process through your normal secret-management approach. Do not commit it to source control.
- You know whether the project is freestyle or pipeline, and whether it uses the public cloud, dedicated cloud, or an on-premises Eyes server.
- You have checked the current plugin release and its compatibility with your Jenkins installation. The 2021 Jenkins walkthrough does not provide a current version matrix.
Eyes supports SDKs across web, mobile, and desktop automation frameworks. The Jenkins plugin is the CI link between a test batch and a build report; it is not a replacement for your test framework. The current SDK documentation covers framework-specific setup.
Install and configure the plugin
Freestyle project
- In Jenkins, open Manage Jenkins → Manage Plugins and search for Applitools Eyes Plugin.
- Install the plugin using the process supported by your Jenkins and plugin versions. The historical Applitools article describes installing without restart; confirm that this applies to your environment.
- Open the freestyle job and choose Configure.
- Under Build Environment, enable Applitools support.
- For the public cloud, use the configured default URL. For a dedicated or private server, set the URL to that Eyes server’s address.
- Save the job and ensure the build step invokes your visual test suite within the job environment configured by the plugin.
Pipeline project
Wrap the command that runs the tests with the Jenkins Pipeline Applitools() directive:
node {
stage('Applitools build') {
Applitools() {
sh 'mvn clean test'
}
}
}For a dedicated Eyes server, pass its server URL to the directive:
node {
stage('Applitools build') {
Applitools('https://myprivateserver.com') {
sh 'mvn clean test'
}
}
}Replace the example URL with the address for your deployment. The sh command is a Unix-like agent example; use the shell step appropriate to your Jenkins agent and pipeline. The plugin syntax and environment-variable behavior come from the Applitools Jenkins integration guide.
Link the Eyes SDK batch to the Jenkins build
The plugin exposes APPLITOOLS_BATCH_ID and APPLITOOLS_BATCH_NAME to the test process. Set the batch once for the Jenkins job before starting its visual tests. This is the key step that lets the plugin associate the Eyes results with the relevant Jenkins job/build report.
Python example from the plugin guide
import os
from applitools.eyes import BatchInfo
# Set once per Jenkins job, before starting the tests.
batch_info = BatchInfo(os.environ['APPLITOOLS_BATCH_NAME'])
batch_info.id_ = os.environ['APPLITOOLS_BATCH_ID']
eyes.batch = batch_infoThis uses the API shown in the Jenkins integration article. Confirm the import and batch API against the version of the Python Eyes SDK used by your project.
Java example from the plugin guide
// Set once per Jenkins job, before starting the tests.
BatchInfo batch = new BatchInfo(System.getenv("APPLITOOLS_BATCH_NAME"));
batch.setId(System.getenv("APPLITOOLS_BATCH_ID"));
eyes.setBatch(batch);Use the matching imports and initialization pattern for your Java SDK version.
JavaScript example from the plugin guide
// Set once per Jenkins job, before starting the tests.
eyes.setBatch(
process.env.APPLITOOLS_BATCH_NAME,
process.env.APPLITOOLS_BATCH_ID
);The exact SDK setup varies by framework and release. Applitools’ current Playwright integration documentation, for example, shows an Eyes-enhanced test fixture and eyes.check() checkpoint. That is framework-level test setup, not an extra Jenkins plugin installation step.
Run the job and review the visual results
- Run the Jenkins job and confirm the test command completes with access to the Eyes server.
- Open the Jenkins build report and follow the Eyes batch link supplied by the plugin.
- In Eyes, inspect changed checkpoints against their baselines. Determine whether each difference is an expected product change or a regression.
- Accept intentional changes to update the baseline, or reject suspected defects and investigate them. Keep baseline approval within your team’s review process.
- For a dedicated cloud or on-premises deployment, check that reviewers are signing into the correct Eyes account/server if the report link returns an access error.
Configuration choices and practical details
| Choice | What to configure | What to verify |
|---|---|---|
| Freestyle or pipeline | Enable Applitools support in the freestyle build environment, or wrap the test command with Applitools() in a pipeline. |
The plugin’s environment variables reach the process that runs the Eyes tests. |
| Public cloud or private server | Use the default public-cloud URL or set the dedicated/private Eyes server URL in the job configuration or pipeline directive. | The test SDK and the browser/build report link target the intended server. |
| Test language and framework | Set batch metadata using the relevant Eyes SDK API; write checkpoints through the framework integration. | SDK API names can differ by language and release. Use the docs for the installed SDK. |
| Batch scope | Apply the Jenkins batch ID/name once for the job’s test run. | Parallel workers or multiple suites should retain the intended build batch association. |
| Baseline decisions | Review diffs and approve intended changes. | Do not accept unexplained visual changes simply to clear a build. |
Reliability, performance, and cost considerations
Reliability: The integration depends on the Jenkins plugin being compatible with Jenkins, the test process receiving the batch environment, and the SDK reaching the configured Eyes server. Keep the plugin and SDK versions deliberate, and verify compatibility before upgrades. The available Jenkins article is dated 2021 and does not document a current compatibility matrix.
Performance: The documented flow adds screenshot capture, upload, server comparison, and result review to the existing test run. The research sources provide no timing benchmark, so do not assume a fixed build-time overhead. Measure your own pipeline with representative pages and checkpoint counts. Capture checkpoints at meaningful UI states and avoid redundant checks that do not improve regression coverage.
Cost: The cited integration and product documentation do not establish current Eyes pricing. Check the vendor’s current commercial terms for your account and deployment; do not infer a price from the Jenkins plugin setup. Your CI resource usage also depends on the browser tests and checkpoint workload.
Network and privacy: The Eyes SDK sends captured screenshots to the configured Eyes server. Confirm that the selected public, dedicated, or on-premises deployment fits your network and data-handling requirements. Applitools describes these server options and the SDK/server architecture in its system overview.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| No Eyes link appears in the Jenkins build report. | The plugin was not enabled for the job, or the test process did not use the batch ID supplied by Jenkins. | Check the plugin configuration for the project type; confirm APPLITOOLS_BATCH_ID and APPLITOOLS_BATCH_NAME are present in the test process; set the SDK batch before opening tests. |
| The environment variables are missing or empty. | The command ran outside the plugin’s configured block/context, or a wrapper/container did not pass its environment through. | Run the test command inside Applitools() for pipeline jobs, and inspect environment propagation at the process boundary without printing secrets into logs. |
| Eyes results open on the wrong server or cannot be found. | The job uses the public default while the account is on a private server, or the private URL is incorrect. | Set the matching server URL in the freestyle configuration or Applitools('server-url') pipeline directive, and ensure the SDK uses the same intended deployment. |
| Results exist in Eyes but are not associated with this build. | The test SDK used its own batch metadata instead of the Jenkins-provided batch values, or batch setup happened after a test started. | Set the batch once before any test/checkpoint begins; verify ID and name values in the process environment. |
| The batch link returns Access Denied. | The browser session may be signed into a different account, especially with a dedicated deployment. | Sign into the account for the configured Eyes server and reopen the report. The historical guide also suggests signing out and back in, or clearing browser cookies, if access remains denied. |
| The SDK reports missing or incompatible batch APIs. | The sample API differs from the installed SDK version. | Use that SDK version’s official documentation and adapt only the batch initialization; retain the Jenkins-provided ID and name as the values to associate. |
| Visual diffs appear on every build. | The page may contain dynamic content or the test may capture before it reaches a stable state. | Stabilize the app state before the checkpoint, use meaningful checkpoints, and apply framework-supported region handling where appropriate. Review the difference before changing a baseline. |
| The plugin cannot be installed or Jenkins requests a restart. | The installation behavior in the 2021 guide may not match the current Jenkins/plugin release. | Follow the current Jenkins plugin manager’s compatibility and restart instructions; check the plugin’s current release information before deployment. |
Or skip the browser setup
If your task is to capture a page image rather than compare application states against visual baselines, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. For this title’s visual regression workflow, Eyes provides the documented baseline comparison and review; ScreenshotNeo is an alternative for producing clean page captures.
See the ScreenshotNeo API documentation for the request options. This cURL example saves a WebP screenshot of Stripe:
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webpPython:
import 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)Node.js:
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 import('node:fs/promises').then(fs => fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));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 shots. Sign up for 1,000 free screenshots a month, no card required.
FAQ
Does the Jenkins plugin take the screenshots?
No. Your test framework and Eyes SDK create the visual checkpoints; the Jenkins plugin associates the resulting batch with the build report.
Can I use the integration with an on-premises Eyes server?
The documented integration supports a private/dedicated server URL. Set the corresponding address in the Jenkins configuration and verify that the test SDK targets the same deployment.
Does Jenkins decide whether a visual change is correct?
No. Jenkins runs the job and links to results. A person reviews differences and accepts intended changes or investigates regressions.
Where can I find the current compatibility requirements?
Check the current Applitools Jenkins plugin and Jenkins release information before installation. The cited integration walkthrough is dated March 6, 2021 and does not state a current compatibility matrix.
