# Selenium Grid Testing Farm

> Browser testing infrastructure with Selenium Grid and multiple browsers.

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

## Overview

Selenium Grid is a distributed testing framework that allows automated browser tests to run simultaneously across multiple machines and browsers. Originally developed to solve the scalability limitations of single-instance Selenium WebDriver testing, Selenium Grid operates on a hub-node architecture where the selenium-hub acts as a central registry and router, while browser nodes (chrome-node, firefox-node, edge-node) provide actual browser automation capabilities. This distributed approach enables massive parallel test execution and cross-browser validation at scale.

This Selenium Grid stack creates a robust browser testing farm with dedicated Chrome, Firefox, and Edge nodes connected through an event bus system. The selenium-hub coordinates test distribution using ports 4442 and 4443 for internal communication, while exposing the grid interface on port 4444. Each browser node can handle multiple concurrent sessions, with Chrome and Firefox nodes scaled to two replicas each for increased throughput. The integrated video recording service captures test execution footage for debugging and compliance purposes.

Development teams managing large test suites, QA departments requiring cross-browser validation, and organizations implementing continuous integration pipelines will benefit from this infrastructure. The configuration supports up to 16 simultaneous sessions across multiple browser types, making it ideal for teams that need to validate web applications across different browser engines simultaneously. This setup eliminates the bottleneck of sequential browser testing while providing visual feedback through recorded test sessions.

## Features

- Event bus architecture with dedicated publish/subscribe ports for efficient test distribution
- Multi-browser node support with Chrome, Firefox, and Edge automation capabilities
- Session-based load balancing with configurable maximum sessions per node
- Horizontal scaling through Docker replicas for Chrome and Firefox nodes
- Integrated video recording with automatic file naming for test session capture
- Grid web interface for real-time monitoring of node status and active sessions
- Timeout management with 300-second session limits to prevent hanging tests
- Independent browser engine isolation preventing cross-contamination between test runs

## Use cases

- Cross-browser compatibility testing for web applications across Chrome, Firefox, and Edge
- Parallel execution of large Selenium test suites to reduce CI/CD pipeline duration
- Remote browser automation for teams working with headless server environments
- Load testing web applications with multiple concurrent browser sessions
- Automated regression testing with video evidence for bug reproduction
- Multi-tenant testing infrastructure for development teams sharing browser resources
- Integration testing for web applications requiring multiple browser contexts simultaneously

## Prerequisites

- Docker Engine with at least 8GB RAM available for multiple browser node containers
- Network ports 4442, 4443, and 4444 available for Selenium Grid communication
- Understanding of Selenium WebDriver RemoteWebDriver configuration and capabilities
- Sufficient disk space in ./videos directory for video recording storage
- Basic knowledge of browser automation and test framework integration
- Docker Compose version supporting deploy.replicas for node scaling

## docker-compose.yml

```yaml
services:
  selenium-hub:
    image: selenium/hub:latest
    ports:
      - "4442:4442"
      - "4443:4443"
      - "4444:4444"
    environment:
      - GRID_MAX_SESSION=16
      - GRID_TIMEOUT=300
    networks:
      - selenium_net

  chrome:
    image: selenium/node-chrome:latest
    environment:
      - SE_EVENT_BUS_HOST=selenium-hub
      - SE_EVENT_BUS_PUBLISH_PORT=4442
      - SE_EVENT_BUS_SUBSCRIBE_PORT=4443
      - SE_NODE_MAX_SESSIONS=4
    depends_on:
      - selenium-hub
    networks:
      - selenium_net
    deploy:
      replicas: 2

  firefox:
    image: selenium/node-firefox:latest
    environment:
      - SE_EVENT_BUS_HOST=selenium-hub
      - SE_EVENT_BUS_PUBLISH_PORT=4442
      - SE_EVENT_BUS_SUBSCRIBE_PORT=4443
      - SE_NODE_MAX_SESSIONS=4
    depends_on:
      - selenium-hub
    networks:
      - selenium_net
    deploy:
      replicas: 2

  edge:
    image: selenium/node-edge:latest
    environment:
      - SE_EVENT_BUS_HOST=selenium-hub
      - SE_EVENT_BUS_PUBLISH_PORT=4442
      - SE_EVENT_BUS_SUBSCRIBE_PORT=4443
      - SE_NODE_MAX_SESSIONS=4
    depends_on:
      - selenium-hub
    networks:
      - selenium_net

  video:
    image: selenium/video:latest
    environment:
      - DISPLAY_CONTAINER_NAME=chrome
      - SE_VIDEO_FILE_NAME=auto
    volumes:
      - ./videos:/videos
    depends_on:
      - chrome
    networks:
      - selenium_net

networks:
  selenium_net:
```

## .env

```bash
# Selenium Grid
# Hub at http://localhost:4444
# Grid console at http://localhost:4444/ui
```

## Usage notes

- Grid UI at http://localhost:4444/ui
- Connect tests to http://localhost:4444
- Chrome, Firefox, Edge nodes
- Video recording available
- Scale nodes as needed

## Troubleshooting

- Browser node shows 'Unable to connect to hub' error: Verify selenium-hub container is running and SE_EVENT_BUS_HOST environment variable matches service name
- Tests fail with 'SessionNotCreatedException': Check node capacity by visiting grid UI at localhost:4444 and verify SE_NODE_MAX_SESSIONS settings
- Video recording produces empty files: Ensure DISPLAY_CONTAINER_NAME matches actual browser container name and ./videos directory has write permissions
- Grid timeout errors during long-running tests: Increase GRID_TIMEOUT environment variable beyond default 300 seconds
- Chrome or Firefox nodes fail to start: Verify sufficient system memory and check Docker logs for browser initialization errors
- Hub becomes unresponsive under load: Reduce GRID_MAX_SESSION value or increase Docker memory limits for selenium-hub container

