Applitools Eyes Visual Testing in GitLab CI for Indian Teams
Integrate Applitools Eyes into GitLab CI using your existing test framework, protect API credentials, review baselines, and account for India-specific deployment questions.
To use Applitools Eyes visual testing in GitLab CI, add the Eyes SDK that matches your existing test framework, store the API key as a protected CI variable, and add visual checkpoints to tests that run in your pipeline. The SDK captures screens at those checkpoints and sends them to the Eyes Server for comparison with baselines. Review differences in Eyes and update a baseline only after deciding that the change is intentional.
For teams in India, the integration steps are much the same as elsewhere. The available Applitools material describes public cloud, dedicated cloud, and on-premises configurations, but does not establish an India service region, data residency commitment, local latency, or India-specific price. Confirm those points for your account and plan before relying on them.
1. Understand the integration
Applitools describes Eyes as a visual testing service designed to add checks to existing test frameworks. Its integration catalog lists GitLab as a source control integration and CI/CD integrations separately. In practice, GitLab CI runs your normal test command; the Eyes SDK inside that test suite captures and submits the visual checkpoints.
- Your GitLab runner checks out the project and installs its dependencies, including the chosen Eyes SDK.
- The job provides the API key to the test process through a protected CI variable.
- Your tests open the application and call Eyes at meaningful screen states.
- The SDK sends captured screens to the Eyes Server for comparison against existing baselines.
- Your team reviews results, decides whether each difference is a defect or an intentional change, and updates baselines when appropriate.
GitLab CI is the job runner in this flow. It does not, by itself, determine where Eyes stores screenshots or what regional data-handling terms apply.
2. Choose the SDK for your existing stack
Start with the language, test runner, and browser automation already in use. Applitools lists SDKs for Playwright, Selenium, Cypress, WebdriverIO, Appium, and other frameworks. Use the official guide for your exact SDK and version; do not copy setup commands or method names from another framework.
| What to identify | Why it matters |
|---|---|
| Language and test framework | Determines the matching Eyes SDK and checkpoint API. |
| Browser and driver | The runner must be able to start the browser your tests use. |
| Existing test command | The GitLab job should run the same project command used locally, with CI-specific configuration as needed. |
| Checkpoint ownership | Your team needs a review process for visual changes and baseline updates. |
| Deployment and data requirements | Service region, retention, contractual handling, and access latency need confirmation if they matter to your organization. |
The official Java Selenium quickstart calls for an Applitools account and API key, Java, Maven, Chrome, and a matching ChromeDriver. Those prerequisites describe that Java Selenium example; other SDK guides can have different requirements.
3. Configure GitLab CI credentials and dependencies
- Create or use an Applitools account and obtain its API key.
- In your GitLab project or group CI/CD variable settings, add a variable such as
APPLITOOLS_API_KEY. Mark it masked and protected where the project’s GitLab configuration allows, and limit which branches and environments can receive it. - Install the Eyes SDK through your project’s normal dependency manager and commit the dependency manifest and lockfile.
- Make the runner image, browser, and browser driver available to the job. Pin compatible versions using your project’s normal dependency management.
- Run the existing test command in a pipeline job, with the key available in the job environment.
There is no universal GitLab YAML template implied by the SDK integration: runner image, browser installation, test command, parallelism, artifact retention, and variable protection depend on the project and GitLab setup. The following is an illustrative shape only. Replace the image and command with values that match your project and chosen SDK; validate the browser and driver availability in your actual runner.
stages:
- test
visual_tests:
stage: test
image: YOUR_PROJECT_TEST_IMAGE
variables:
# Configure your project-specific browser settings here.
CI: "true"
script:
- YOUR_PROJECT_DEPENDENCY_INSTALL_COMMAND
- YOUR_PROJECT_TEST_COMMAND
rules:
- if: '$CI_COMMIT_BRANCH'Configure APPLITOOLS_API_KEY in GitLab’s CI/CD settings rather than placing its value in YAML, source files, command-line arguments, or logs. GitLab exposes configured variables to jobs as environment variables, but the exact protected-branch behavior depends on your project settings.
4. Add visual checkpoints to tests
Open the application and bring it to a stable, representative state before taking a checkpoint. Good checkpoints typically follow the actions that matter to a user: loading a key page, opening a menu, applying a filter, or completing a meaningful workflow step. Avoid capturing transient states such as an animation mid-frame or content that changes unpredictably between runs.
Use the checkpoint calls, test lifecycle, and configuration shown in the official guide for your selected SDK. The available research supports a Java Selenium setup sequence but does not provide enough API detail to publish a verified, runnable checkpoint test for every framework. Do not transplant Java-specific code into a Playwright, Cypress, or other project.
Before relying on a checkpoint, decide which dynamic areas the test should tolerate or stabilize, how the test identifies its baseline, and who is allowed to approve changes. Keep the test’s navigation and data setup deterministic so that a visual difference points to a real UI change rather than inconsistent test state.
5. Run the pipeline and review results
- Run the pipeline on a branch where the CI variable is available.
- Confirm that the normal tests and browser startup complete, and that the Eyes SDK can reach the configured Eyes service.
- Open the run’s results in Eyes and inspect each reported difference in context.
- Classify each difference as an application defect, an expected change, or a test/environment issue.
- Fix defects or unstable test setup. Update a baseline only after review confirms the visual change is intentional.
Assign baseline review ownership explicitly. For example, the team can require a UI owner to review visual changes before a baseline is accepted; the exact approval process is a project decision, not something established by the integration itself.
6. India-specific deployment and commercial checks
Applitools describes public cloud, dedicated cloud, and on-premises configurations. The cited material does not say whether a particular account or plan offers an India endpoint or India data residency. Do not infer screenshot location from your team’s location or from where GitLab runners are hosted.
If your organization has location, latency, or retention requirements, ask Applitools for the actual service region for the account and plan, how screenshots and metadata are handled, available retention controls, contractual commitments, and expected access latency from your environment. Have the vendor confirm the details that apply to your intended deployment before making a compliance or architecture decision.
The vendor pricing page displayed a Starter price of $667 per month when paid annually, alongside checkpoint allowances and CI/CD integrations in the research snapshot. Treat that as volatile USD vendor pricing, not an India quote. Check current plan limits and terms, billing currency, applicable taxes, and local commercial terms with Applitools; the available source does not establish an India-specific amount. Do not convert it to rupees without a dated exchange rate and clarity on taxes and billing.
7. Performance, reliability, and cost planning
- Runner time: Browser startup, application navigation, and the rest of your test suite contribute to job duration. Measure your own pipeline and tune its browser and test setup; the available sources provide no verified performance benchmark.
- Reliability: Keep browser and driver versions compatible, stabilize data and application state, and make CI failures diagnosable. When a run fails, distinguish test or browser startup failures from Eyes connectivity or comparison results.
- Parallel work: Decide how your test framework’s parallel execution maps to your account’s checkpoint allowances and concurrency terms. Confirm plan limits with the vendor rather than assuming a particular allowance.
- Review effort: More checkpoints can provide broader coverage but also create more results for people to inspect. Focus on screens and states where visual regressions matter, and assign baseline review ownership.
- Commercial cost: Verify current pricing, checkpoint limits, support, concurrency, and plan terms for your expected execution volume. The displayed entry-level price is not a quote for an Indian customer.
8. Troubleshooting
| Symptom | Likely cause | What to check or fix |
|---|---|---|
| API key is missing or authentication fails | The variable is unset, misspelled, unavailable to the branch, or not read by the SDK configuration. | Check the variable name and branch protection settings in GitLab. Confirm the job receives it without printing the secret. |
| Browser cannot start in CI | The runner image lacks a browser or required system packages, or the browser and driver do not match. | Use the browser setup required by the selected SDK guide; verify the installed browser and driver versions in the runner. |
| Dependencies install locally but not in the job | The CI image has a different runtime or package-manager setup, or dependencies are not locked. | Use the project’s supported runtime and package manager in CI, and commit its lockfile. |
| No visual result appears | The test may not reach its checkpoint, may exit before the SDK completes its run lifecycle, or may be configured for a different account. | Check test output and the chosen SDK guide’s lifecycle requirements; verify the key and account configuration. |
| Unexpected visual differences recur | Dynamic content, animation, inconsistent data, fonts, browser versions, or viewport differences can make captures unstable. | Stabilize test data and screen state, keep browser configuration consistent, and follow the framework’s supported handling for dynamic regions. |
| CI variable is unavailable on a branch | A protected variable may only be exposed to protected branches or environments. | Review GitLab’s variable protection and branch rules; keep secrets restricted to the intended jobs. |
| India residency or regional routing is unclear | The available deployment descriptions do not identify an India region for a given plan. | Get written, plan-specific confirmation from Applitools about service region, data handling, retention, and contractual terms. |
| Budget estimate does not match expected spend | Displayed pricing may have changed, and taxes, currency, allowances, or plan terms may differ. | Check the current vendor offer and request an India-specific commercial quote where needed. |
9. Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server for developers, made by Yorker Media. For visual regression work that needs page captures, its API can return a screenshot in one GET request. It is an alternative to try first when you want a screenshot capture service rather than setting up browser capture code yourself. It does not replace Eyes’ baseline comparison and review workflow.
See the ScreenshotNeo API documentation. Example request for a capture:
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}`);Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed; an MCP server lets AI agents take screenshots; and 1,000 screenshots a month are free with no card, with paid plans starting at $5 for 3,000. Sign up for ScreenshotNeo’s free plan to try it.
FAQ
Can I use Eyes with Playwright or Selenium in GitLab CI?
Choose the Eyes SDK guide that matches the framework already used by your tests. Applitools lists both Playwright and Selenium among its SDK options; setup details and prerequisites differ by SDK.
Where are Applitools screenshots stored for an Indian team?
The available sources do not establish a specific region or residency commitment for a given account. Ask Applitools to confirm service region and screenshot handling for your plan and deployment.
Does running the runner in India keep screenshots in India?
That cannot be inferred from runner location. Confirm the service region and data-handling terms with Applitools.
Is the listed price an India quote?
No. The researched page displayed a USD amount for an annual-billing offer; verify current pricing and India-specific billing and tax terms with the vendor.
