Docker Selenium Grid — Containerized Browser Testing at Scale

Introduction

Docker Selenium packages Selenium Grid components as container images, eliminating the complexity of installing browsers, drivers, and Grid infrastructure manually. It enables teams to spin up disposable browser testing environments in seconds, whether locally with Docker Compose or at scale on Kubernetes.

What Docker Selenium Does

• Provides ready-to-use containers for Chrome, Firefox, and Edge with matching WebDriver binaries
• Packages Selenium Grid Hub, Router, Distributor, and Node as separate images for distributed setups
• Includes noVNC for live browser session viewing and debugging
• Supports video recording of test sessions per container
• Integrates with KEDA for event-driven autoscaling on Kubernetes

Architecture Overview

Docker Selenium follows the Selenium Grid 4 architecture: a Router receives test requests and forwards them to the Distributor, which assigns sessions to available Nodes. Each Node runs a browser inside a container with Xvfb (virtual framebuffer). The Session Map tracks active sessions, and the Event Bus coordinates components. In standalone mode, all components run in a single container.

Self-Hosting & Configuration

• Use docker compose with the provided sample files for Hub-Node or fully distributed topologies
• Set SE_NODE_MAX_SESSIONS to control concurrent browser sessions per node
• Configure --shm-size="2g" to prevent browser crashes from shared memory exhaustion
• Deploy on Kubernetes using the official Helm chart with autoscaling via KEDA
• Enable video recording by adding selenium/video sidecar containers

Key Features

• Dynamic Grid mode creates and destroys browser containers per test session
• Built-in noVNC and VNC access for real-time visual debugging of test runs
• Tracing integration with OpenTelemetry for Grid observability
• Relay support allows connecting external WebDriver services (e.g., Appium)
• Multi-architecture images (amd64, arm64) for diverse infrastructure

Comparison with Similar Tools

• Playwright — includes its own browser binaries and does not require Selenium Grid
• Cypress — runs tests inside the browser directly, no Grid needed, but Chrome-family only
• Selenoid — lightweight Go-based Selenium hub with per-session containers and built-in video
• Moon — commercial Selenium/Playwright cluster manager by Aerokube
• BrowserStack/Sauce Labs — cloud-hosted browser grids with no self-hosting required

FAQ

Q: How many concurrent sessions can a single node handle? A: By default one per container. Set SE_NODE_MAX_SESSIONS to increase, though browser stability decreases with too many sessions sharing resources.

Q: How do I record test videos? A: Add a selenium/video container linked to each Node. Videos are saved to a configurable output directory.

Q: Does Docker Selenium support ARM architecture? A: Yes. Multi-arch images are available for amd64 and arm64 platforms.

Q: Can I use this with Kubernetes? A: Yes. The project provides a Helm chart and supports KEDA-based autoscaling for elastic test infrastructure.

Sources

• https://github.com/SeleniumHQ/docker-selenium
• https://www.selenium.dev/documentation/grid/