docker.recipes

Selenium Grid

intermediate

Distributed browser testing infrastructure.

Overview

Selenium Hub serves as the central coordinator in a Selenium Grid architecture, managing the distribution of test execution across multiple browser nodes. Originally developed by Selenium to address the limitations of running automated tests on a single machine, the hub acts as a registry and load balancer that receives test requests from WebDriver clients and routes them to available browser nodes based on desired capabilities. The hub maintains knowledge of all registered nodes, their browser types, versions, and availability status, enabling efficient parallel test execution across diverse browser environments. This stack combines the Selenium Hub with dedicated Chrome and Firefox nodes to create a distributed testing infrastructure that can handle multiple concurrent browser sessions. The hub communicates with browser nodes through an event bus system using ports 4442 and 4443 for publishing and subscribing to events, while port 4444 serves as the main WebDriver endpoint. Each browser node registers itself with the hub and reports its capabilities, allowing the hub to intelligently route incoming test requests to appropriate browsers based on the requested browser type, version, and platform requirements. Development teams, QA engineers, and DevOps professionals who need to run automated browser tests at scale will benefit from this configuration. The distributed nature allows for horizontal scaling of browser capacity, reduced test execution times through parallelization, and isolation of browser processes to prevent interference between concurrent tests. This setup is particularly valuable for organizations implementing continuous integration pipelines where fast, reliable cross-browser testing is essential for maintaining development velocity while ensuring application quality across different browser environments.

Key Features

  • Event bus architecture with dedicated publish/subscribe ports for real-time node communication and status updates
  • Dynamic browser node registration supporting mixed browser environments with automatic capability detection
  • Shared memory allocation of 2GB per browser node to handle memory-intensive modern web applications
  • Web-based grid console providing real-time visibility into node status, session counts, and queue depth
  • Selenium 4 distributed mode with improved session management and reduced resource overhead compared to legacy versions
  • Cross-browser test execution with automatic routing based on desired capabilities matching
  • Horizontal scaling support allowing runtime addition of browser nodes without service interruption
  • Container-level browser isolation preventing session interference and improving test reliability

Common Use Cases

  • 1Continuous integration pipelines requiring parallel cross-browser testing for web applications
  • 2Large-scale regression testing suites that need to execute hundreds of test cases simultaneously
  • 3Quality assurance teams performing compatibility testing across multiple browser versions and configurations
  • 4Development teams implementing shift-left testing practices with automated browser testing in feature branches
  • 5Performance testing scenarios requiring multiple concurrent user sessions across different browser types
  • 6Automated testing in enterprise environments where test execution time directly impacts release cycles
  • 7Cross-platform web application validation requiring consistent testing across Chrome and Firefox browsers

Prerequisites

  • Docker Engine 20.10+ with at least 8GB available RAM for multiple concurrent browser sessions
  • Available ports 4442, 4443, and 4444 on the host system for hub communication and WebDriver endpoints
  • Basic understanding of Selenium WebDriver architecture and desired capabilities configuration
  • Familiarity with WebDriver client libraries in your preferred programming language (Java, Python, JavaScript, etc.)
  • Knowledge of browser automation concepts including element selection, page object patterns, and wait strategies
  • Understanding of test parallelization strategies and thread-safe test design patterns

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  selenium-hub: 
3    image: selenium/hub:latest
4    container_name: selenium-hub
5    restart: unless-stopped
6    ports: 
7      - "4442:4442"
8      - "4443:4443"
9      - "4444:4444"
10
11  chrome: 
12    image: selenium/node-chrome:latest
13    container_name: selenium-chrome
14    restart: unless-stopped
15    shm_size: "2gb"
16    depends_on: 
17      - selenium-hub
18    environment: 
19      SE_EVENT_BUS_HOST: selenium-hub
20      SE_EVENT_BUS_PUBLISH_PORT: 4442
21      SE_EVENT_BUS_SUBSCRIBE_PORT: 4443
22
23  firefox: 
24    image: selenium/node-firefox:latest
25    container_name: selenium-firefox
26    restart: unless-stopped
27    shm_size: "2gb"
28    depends_on: 
29      - selenium-hub
30    environment: 
31      SE_EVENT_BUS_HOST: selenium-hub
32      SE_EVENT_BUS_PUBLISH_PORT: 4442
33      SE_EVENT_BUS_SUBSCRIBE_PORT: 4443

.env Template

.env
1# Scale browsers with replicas

Usage Notes

  1. 1Docs: https://www.selenium.dev/documentation/grid/
  2. 2Grid console at http://localhost:4444 - view registered nodes
  3. 3Connect WebDriver to http://localhost:4444
  4. 4Scale browsers: docker-compose up --scale chrome=4
  5. 5VNC available: selenium/standalone-chrome-debug for debugging
  6. 6Selenium 4 with distributed mode (hub/node) or standalone

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

selenium-hub
selenium-hub:
  image: selenium/hub:latest
  container_name: selenium-hub
  restart: unless-stopped
  ports:
    - "4442:4442"
    - "4443:4443"
    - "4444:4444"
chrome
chrome:
  image: selenium/node-chrome:latest
  container_name: selenium-chrome
  restart: unless-stopped
  shm_size: 2gb
  depends_on:
    - selenium-hub
  environment:
    SE_EVENT_BUS_HOST: selenium-hub
    SE_EVENT_BUS_PUBLISH_PORT: 4442
    SE_EVENT_BUS_SUBSCRIBE_PORT: 4443
firefox
firefox:
  image: selenium/node-firefox:latest
  container_name: selenium-firefox
  restart: unless-stopped
  shm_size: 2gb
  depends_on:
    - selenium-hub
  environment:
    SE_EVENT_BUS_HOST: selenium-hub
    SE_EVENT_BUS_PUBLISH_PORT: 4442
    SE_EVENT_BUS_SUBSCRIBE_PORT: 4443

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  selenium-hub:
5    image: selenium/hub:latest
6    container_name: selenium-hub
7    restart: unless-stopped
8    ports:
9      - "4442:4442"
10      - "4443:4443"
11      - "4444:4444"
12
13  chrome:
14    image: selenium/node-chrome:latest
15    container_name: selenium-chrome
16    restart: unless-stopped
17    shm_size: "2gb"
18    depends_on:
19      - selenium-hub
20    environment:
21      SE_EVENT_BUS_HOST: selenium-hub
22      SE_EVENT_BUS_PUBLISH_PORT: 4442
23      SE_EVENT_BUS_SUBSCRIBE_PORT: 4443
24
25  firefox:
26    image: selenium/node-firefox:latest
27    container_name: selenium-firefox
28    restart: unless-stopped
29    shm_size: "2gb"
30    depends_on:
31      - selenium-hub
32    environment:
33      SE_EVENT_BUS_HOST: selenium-hub
34      SE_EVENT_BUS_PUBLISH_PORT: 4442
35      SE_EVENT_BUS_SUBSCRIBE_PORT: 4443
36EOF
37
38# 2. Create the .env file
39cat > .env << 'EOF'
40# Scale browsers with replicas
41EOF
42
43# 3. Start the services
44docker compose up -d
45
46# 4. View logs
47docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/selenium-grid/run | bash

Troubleshooting

  • Browser nodes not appearing in grid console: Verify SE_EVENT_BUS_HOST environment variable points to correct hub container name and event bus ports are accessible
  • WebDriver connection refused on port 4444: Ensure hub container is fully started before browser nodes attempt registration, check hub logs for binding errors
  • Browser sessions hanging or timing out: Increase shm_size beyond 2gb for memory-intensive applications or add session timeout configurations
  • Node capacity showing 0 available slots: Browser nodes may be overwhelmed, scale horizontally or restart nodes to clear stuck sessions
  • Cross-browser test failures with capability matching errors: Verify desired capabilities match exact browser versions available on registered nodes
  • Hub showing registered nodes but tests not distributing: Check for network connectivity between hub and nodes, verify event bus port communication is not blocked

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

selenium-hubchromefirefox

Tags

#selenium#testing#browser#automation

Category

Development Tools

Related Recipes

Ad Space