This document describes the browser version management system in the docker-selenium project. It covers how browser versions are tracked, how images for specific browser versions are built and released, version tagging strategies, and backward compatibility testing. This system allows users to run Selenium tests against specific browser versions going back several releases.
For information about the main build and release pipeline, see Release Automation and Deployment. For browser installation and configuration within images, see Browser Node and Standalone Images.
The project maintains YAML matrix files that define supported browser versions and their configuration metadata.
Sources: tests/build-backward-compatible/browser-matrix.yml tests/build-backward-compatible/firefox-matrix.yml tests/build-backward-compatible/selenium-matrix.yml
The browser-matrix.yml file maps major browser version numbers to specific package versions and platform availability:
| Browser Version | Chrome Package | Firefox Package | Edge Package | Firefox Platforms |
|---|---|---|---|---|
| 141 | google-chrome-stable=141.0.7390.54-1 | 141.0.3 | microsoft-edge-stable=141.0.3537.57-1 | linux/amd64,linux/arm64 |
| 140 | google-chrome-stable=140.0.7339.207-1 | 140.0.4 | microsoft-edge-stable=140.0.3485.94-1 | linux/amd64,linux/arm64 |
| 95 | google-chrome-stable=95.0.4638.69-1 | 95.0.2 | microsoft-edge-stable=95.0.1020.40-1 | N/A |
Each entry in the matrix contains:
CHROME_VERSION: Full Chrome/Chromium package name with versionFIREFOX_VERSION: Firefox version numberEDGE_VERSION: Full Edge package name with version (null for older versions)FIREFOX_PLATFORMS: Comma-separated list of supported platforms (added for versions 126+)FIREFOX_DOWNLOAD_URL: Direct download URL for ARM64 Firefox builds (for specific versions)Sources: tests/build-backward-compatible/browser-matrix.yml1-207
The selenium-matrix.yml file tracks Selenium Grid versions and their associated browser version support:
Empty browser arrays indicate all browser versions are supported. Non-empty arrays list specific supported browser major versions.
Sources: tests/build-backward-compatible/selenium-matrix.yml1-206
Three parallel workflows enable building and releasing images for specific browser versions independent of the main release cycle.
Sources: .github/workflows/release-chrome-versions.yml .github/workflows/release-firefox-versions.yml .github/workflows/release-edge-versions.yml
Each release workflow accepts the following inputs:
| Parameter | Description | Default |
|---|---|---|
stable | Use upstream stable Selenium build | true |
reuse-base | Reuse existing base image instead of rebuilding | true |
grid-version | Selenium Grid version (e.g., 4.28.1) | Empty (fetches latest) |
build-date | Build date in YYYYMMDD format | 20251001 |
browser-name | Browser to build (chrome, firefox, edge) | Browser-specific |
browser-versions | JSON array of browser versions to build | Browser-specific list |
push-image | Push images to Docker Hub after successful tests | false |
pr-changelog | Create pull request with changelog | true |
Sources: .github/workflows/release-chrome-versions.yml4-44 .github/workflows/release-firefox-versions.yml4-44 .github/workflows/release-edge-versions.yml4-44
The workflow executes the following steps for each browser version in the matrix:
Environment Setup: Install Docker, configure containerd image store .github/workflows/release-chrome-versions.yml75-82
Version Resolution: Determine Grid version if not provided .github/workflows/release-chrome-versions.yml100-109
Matrix Update: Run make update_browser_versions_matrix to fetch latest version mappings .github/workflows/release-chrome-versions.yml122
Image Build: Execute bootstrap.sh with parameters:
Testing: Run browser-specific test targets:
make test_chrome, make test_firefox, make test_edgemake test_chrome_standalone, make test_firefox_standalone, etc. .github/workflows/release-chrome-versions.yml131-146Image Push: If push-image=true, push images with push flags:
Changelog: Upload changelog markdown files to artifacts .github/workflows/release-chrome-versions.yml152-157
Sources: .github/workflows/release-chrome-versions.yml69-157
Each workflow defines default browser version lists:
Chrome: Versions 95-140 (46 versions)
.github/workflows/release-chrome-versions.yml34
Firefox: Versions 98-142 (45 versions)
.github/workflows/release-firefox-versions.yml34
Edge: Versions 95, 114-140 (28 versions, gap from 96-113)
.github/workflows/release-edge-versions.yml34
Sources: .github/workflows/release-chrome-versions.yml34 .github/workflows/release-firefox-versions.yml34 .github/workflows/release-edge-versions.yml34
Browser-specific images use a multi-level tagging strategy to support various use cases.
Tag Hierarchy:
selenium/node-chrome:latest - Points to most recent Grid version with latest Chromeselenium/node-chrome:4.36.0 - Latest browser for specific Grid versionselenium/node-chrome:140.0 - Specific browser with latest Gridselenium/node-chrome:140.0-20251001 - Specific browser/build combinationselenium/node-chrome:4.36.0-140.0-20251001 - Complete version specificationSources: .github/workflows/deploy.yml173-181
The main deploy.yml workflow generates and pushes browser-specific tags after building the standard release:
This target iterates through all browser nodes and standalone images, creating version-specific tags based on the browser metadata files.
Sources: .github/workflows/deploy.yml173-181
| Image Type | Repository | Tag Examples |
|---|---|---|
| Node Chrome | selenium/node-chrome | 141.0, 141.0-20251001, 4.36.0-141.0-20251001 |
| Node Firefox | selenium/node-firefox | 142.0, 142.0-20251001, 4.36.0-142.0-20251001 |
| Node Edge | selenium/node-edge | 140.0, 140.0-20251001, 4.36.0-140.0-20251001 |
| Standalone Chrome | selenium/standalone-chrome | 141.0, 141.0-20251001, 4.36.0-141.0-20251001 |
| Standalone Firefox | selenium/standalone-firefox | 142.0, 142.0-20251001, 4.36.0-142.0-20251001 |
| Standalone Edge | selenium/standalone-edge | 140.0, 140.0-20251001, 4.36.0-140.0-20251001 |
Sources: .github/workflows/deploy.yml173-181
The bootstrap.sh script in tests/build-backward-compatible/ enables building and testing images with older browser versions against specific Selenium Grid versions.
Sources: .github/workflows/release-chrome-versions.yml115-150
When REUSE_BASE=true (default), the script pulls and reuses an existing base image instead of rebuilding:
This optimization significantly reduces build time when only browser versions differ. The base image contains:
Sources: .github/workflows/release-chrome-versions.yml11-25 .github/workflows/release-chrome-versions.yml128-129
The script sets browser-specific environment variables before building:
These variables are consumed by Dockerfiles to install the correct browser versions.
Sources: tests/build-backward-compatible/browser-matrix.yml14-18
The main deploy.yml workflow integrates browser version management into the release process.
Sources: .github/workflows/deploy.yml134-181
The update_browser_versions_matrix target refreshes browser version metadata before tagging:
This target:
Sources: .github/workflows/deploy.yml172
After the main release images are pushed, browser-specific tags are created and pushed:
This process:
{BROWSER_VERSION}, {BROWSER_VERSION}-{BUILD_DATE}, {GRID_VERSION}-{BROWSER_VERSION}-{BUILD_DATE}Sources: .github/workflows/deploy.yml173-181
The update-dev-beta-browser-images.yml workflow maintains images with development and beta browser channels.
Sources: .github/workflows/update-dev-beta-browser-images.yml1-142
Dev and beta images use channel names as tags:
| Browser | Dev Tag | Beta Tag |
|---|---|---|
| Chrome | selenium/node-chrome:dev | selenium/node-chrome:beta |
| Firefox | selenium/node-firefox:dev | selenium/node-firefox:beta |
| Edge | selenium/node-edge:dev | selenium/node-edge:beta |
Standalone variants follow the same pattern: selenium/standalone-{browser}:{channel}
Sources: .github/workflows/update-dev-beta-browser-images.yml29-37
The Makefile contains targets for each browser/channel combination:
make chrome_dev, make chrome_betamake firefox_dev, make firefox_betamake edge_dev, make edge_betamake standalone_chrome_dev, make standalone_chrome_betaThese targets modify the browser installation commands in Dockerfiles to pull from dev/beta repositories instead of stable.
Sources: .github/workflows/update-dev-beta-browser-images.yml75-78
The Helm chart supports deploying multiple browser versions simultaneously with version-specific autoscaling.
The multiple-nodes-platform-version.yaml file provides a reference configuration for deploying multiple Chrome, Firefox, and Edge versions:
Sources: charts/selenium-grid/multiple-nodes-platform-version.yaml9-46
Sources: charts/selenium-grid/multiple-nodes-platform-version.yaml1-235
KEDA autoscaling triggers match incoming requests to specific browser versions using metadata:
This configuration creates a ScaledObject that only scales when:
browserName capability matches (Chrome)browserVersion capability is 140.0 (or unset for empty string match)platformName capability is LinuxEmpty browserVersion: '' matches requests without explicit version requirements, routing them to the latest browser.
Sources: charts/selenium-grid/multiple-nodes-platform-version.yaml12-25
The configuration file contains complete version matrices:
Each browser version deployment can scale independently based on demand for that specific version.
Sources: charts/selenium-grid/multiple-nodes-platform-version.yaml1-689
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.