# Selenium Grid

> Distributed browser testing infrastructure.

- Category: Development Tools
- Difficulty: intermediate
- Components: selenium-hub, chrome, firefox
- Tags: selenium, testing, browser, automation
- Source: https://docker.recipes/development/selenium-grid

## 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.

## 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

## Use cases

- Continuous integration pipelines requiring parallel cross-browser testing for web applications
- Large-scale regression testing suites that need to execute hundreds of test cases simultaneously
- Quality assurance teams performing compatibility testing across multiple browser versions and configurations
- Development teams implementing shift-left testing practices with automated browser testing in feature branches
- Performance testing scenarios requiring multiple concurrent user sessions across different browser types
- Automated testing in enterprise environments where test execution time directly impacts release cycles
- Cross-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

## docker-compose.yml

```yaml
services:
  selenium-hub:
    image: selenium/hub:latest
    container_name: selenium-hub
    restart: unless-stopped
    ports:
      - "4442:4442"
      - "4443:4443"
      - "4444:4444"

  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:
    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
```

## .env

```bash
# Scale browsers with replicas
```

## Usage notes

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

## 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

