Selenium Manager Cache Strategy for Air-Gapped and Hermetic CI

An air-gapped Selenium job should never discover its browser automation dependencies while tests are starting. The dependable design resolves and validates those inputs in a connected build stage, promotes the complete Selenium Manager cache as an immutable artifact, and proves that the isolated stage can create a real browser session without network access.

That distinction matters because a cache hit is an implementation detail, while a reproducible browser session is the outcome the pipeline needs. A stale metadata file, a driver for the wrong CPU architecture, or a browser updated independently from its driver can all leave a populated directory that is operationally useless.

Understand What Selenium Manager Resolves

The official Selenium Manager documentation explains that the bindings invoke Manager as a fallback when a driver has not otherwise been supplied. Manager discovers the installed browser, resolves a compatible driver, downloads missing assets, and stores managed drivers and browsers under its cache path. The default is ~/.cache/selenium, but relying on a home directory in CI makes ownership and restoration ambiguous.

Set a dedicated path such as /opt/selenium-cache and treat it as an input to the test image or job. In a connected stage, Manager may need browser-vendor metadata as well as the actual driver archive. In an isolated stage, SE_OFFLINE=true prevents those network requests and downloads; it does not manufacture missing resolution data. A successful warm-up must therefore exercise the same browser family, version policy, operating system, and architecture as the final runner.

Separate Cache Production from Cache Consumption

Use two pipeline responsibilities. A cache-producer job has tightly controlled outbound access, installs the intended browser or requests a managed browser, starts one representative WebDriver session, records checksums, and publishes the cache. A consumer job restores that artifact into a clean environment, denies outbound traffic, enables offline mode, and starts another session before running tests.

Do not let ordinary test jobs update the promoted artifact. Parallel writers can leave partial downloads or metadata from different browser revisions. Restoring the artifact into a job-private directory also prevents one shard from changing the inputs observed by another shard. The promoted copy remains the source of truth, and a failed consumer is evidence that the artifact or its compatibility contract is incomplete.

Configure a Fixed Cache Contract

Selenium Manager accepts CLI flags, a se-config.toml file in the cache, and SE_ environment variables. Its documented precedence is CLI arguments, configuration file, then environment variables. In CI, environment variables are convenient for switching connected and isolated modes, while a checked-in configuration template makes the intended policy reviewable.

cache-path = "/opt/selenium-cache"
offline = true
avoid-stats = true
avoid-browser-download = true
debug = true

avoid-browser-download is appropriate when the runner image already contains the browser. If the cache producer intentionally uses Selenium Manager to supply the browser too, omit that setting and package the managed browser directory with the driver. Do not put proxy credentials in se-config.toml; inject any proxy only into the connected producer and keep it out of the promoted archive.

Build a Compatibility-Aware Cache Key

A key named only selenium-cache is too broad. At minimum, identify the operating system, CPU architecture, browser family, browser version, Selenium binding dependency, and the revision of the warm-up recipe. Add the driver version when your organization pins it explicitly. A useful logical key looks like linux-x64-chrome-<browser>-selenium-<binding>-recipe-<revision>.

Do not restore a Linux cache on macOS, an x64 cache on ARM64, or a Chrome cache for Firefox. Also avoid a floating browser package in the isolated image. If the image is rebuilt with a newer browser while the old cache artifact is reused, session creation may fail even though restoration reports a hit. Browser image digest and cache artifact should advance through the same review gate.

Warm the Exact Execution Path

The warm-up should create a browser session through the same binding and constructor used by the suite. Merely downloading an archive with a shell script bypasses Manager's directory conventions and metadata. A small Java program is enough to force resolution and provide machine-readable evidence from the returned capabilities.

import org.openqa.selenium.Capabilities;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;

public final class CacheSmoke {
  public static void main(String[] args) {
    ChromeOptions options = new ChromeOptions();
    options.addArguments("--headless=new", "--window-size=1280,800");

    WebDriver driver = new ChromeDriver(options);
    try {
      Capabilities actual = ((ChromeDriver) driver).getCapabilities();
      System.out.printf(
          "browser=%s version=%s platform=%s%n",
          actual.getBrowserName(),
          actual.getBrowserVersion(),
          actual.getPlatformName());
    } finally {
      driver.quit();
    }
  }
}

Set SE_CACHE_PATH before starting the JVM; changing a process environment variable from Java after launch is not a reliable configuration mechanism. Python, JavaScript, .NET, and Ruby bindings invoke the same bundled Manager concept, but each binding release ships its own integration. Warm with the binding that the consumer actually runs.

Promote Evidence with the Artifact

Package the cache only after the connected smoke test succeeds. Generate a checksum manifest for every regular file and store a small build record beside the archive: runner OS, architecture, browser version output, Selenium dependency version, build recipe revision, and creation date. These are not performance metrics; they are provenance needed to explain why a cache should match a consumer.

The artifact repository should provide immutability and retention policy. Sign or attest the artifact if that is already part of the software supply chain. A browser driver is executable code, so promotion deserves the same review as other CI tooling. Avoid printing the entire environment into the record because it can leak credentials or unrelated secrets.

Enforce Offline Consumption

The consumer must fail closed. Restore the exact artifact, verify checksums, export the fixed cache path, and block outbound access before running the Java smoke. A generic CI sequence can express the contract without binding it to one vendor.

steps:
  - name: Restore approved Selenium cache
    run: artifact-client fetch "$SELENIUM_CACHE_KEY" /opt/selenium-cache
  - name: Verify promoted files
    run: sha256sum --check /opt/selenium-cache/SHA256SUMS
  - name: Prove offline session startup
    env:
      SE_CACHE_PATH: /opt/selenium-cache
      SE_OFFLINE: "true"
      SE_AVOID_STATS: "true"
      SE_DEBUG: "true"
    run: ./mvnw -q -DskipTests exec:java -Dexec.mainClass=CacheSmoke
  - name: Run browser tests
    env:
      SE_CACHE_PATH: /opt/selenium-cache
      SE_OFFLINE: "true"
      SE_AVOID_STATS: "true"
    run: ./mvnw test

Network isolation must come from the runner, container policy, or firewall, not from trust in a variable. The negative proof is valuable: if the smoke succeeds while egress is denied, the session path is genuinely self-contained. If it fails, stop before spending time on the complete suite.

Diagnose Cache Failures by Stage

A failure before a driver process starts usually points to resolution: wrong cache path, absent metadata, incompatible platform artifact, or a browser version that differs from the warm-up input. Enable SE_DEBUG=true, capture Manager output, and list the restored directory without exposing unrelated home-directory contents. A message about unavailable metadata in offline mode is a cache-production defect, not a reason to temporarily enable internet access in the consumer.

A driver process that starts but returns session not created moves the investigation to browser-driver compatibility, browser binary location, sandbox policy, or missing operating-system libraries. A session that opens and then fails on the first navigation is no longer a Manager-cache problem. Preserve Manager logs, driver logs, browser version output, and returned capabilities as separate artifacts so the owner can identify the failing boundary.

Choose Between Artifacts and Internal Mirrors

An immutable cache artifact gives the strongest hermetic guarantee and simple auditability, but every supported platform and browser revision needs a new promotion. An internal mirror is more flexible for a broad matrix and keeps downloads inside an approved network. Selenium Manager exposes driver and browser mirror configuration, but a mirror still introduces a runtime network dependency and must reproduce the repository layout Manager expects.

Some teams combine both approaches: an internal mirror supplies a controlled producer, and isolated consumers receive promoted cache artifacts. The extra stage costs storage and pipeline time, but it separates acquisition risk from test execution and gives rollback a concrete artifact identifier.

Operational Checklist

• Pin or record the browser image used by both producer and consumer.
• Give Selenium Manager an explicit cache path owned by the job.
• Key artifacts by OS, architecture, browser, binding, and recipe revision.
• Warm the cache by creating a real session through the production binding.
• Include managed browser files when the runner image has no browser.
• Generate and verify checksums before session startup.
• Restore a private, preferably read-only copy for each parallel job.
• Set SE_OFFLINE=true and disable outbound network access independently.
• Archive Manager output, driver logs, browser version, and capabilities.
• Reject cache misses instead of downloading during the test stage.

Conclusion: Promote a Session, Not a Directory

A hermetic Selenium pipeline is complete only when a clean, network-blocked consumer can restore one approved artifact and start the expected browser. Build the cache on the exact target platform, bind it to explicit browser and Selenium inputs, verify its contents, and make the offline smoke test the admission gate. That turns Selenium Manager from an implicit downloader into a controlled dependency resolver with evidence at every handoff.