Selenium Grid 4: Complete Guide to Distributed Testing

Why Selenium Grid 4 Changes Everything

I have been running Selenium Grid infrastructure since version 2. The jump to Grid 4 was the most significant upgrade yet. Built on a modern architecture with better observability and Docker-native support, Grid 4 is production-ready distributed testing.

Selenium Grid 4 Architecture

Components Overview

• Router: Entry point that routes requests to appropriate components.
• Distributor: Maintains model of available nodes and distributes sessions.
• Session Map: Tracks which session is running on which node.
• Session Queue: Holds incoming session requests in FIFO order.
• Event Bus: Internal communication between components.
• Nodes: Where browsers actually run.

Deployment Modes

Mode	Components	Use Case
Standalone	All-in-one	Development, small teams
Hub and Node	Hub + Nodes	Traditional distributed setup
Distributed	All separate	Large scale, Kubernetes

Quick Start: Standalone Mode

# Download Selenium Server
wget https://github.com/SeleniumHQ/selenium/releases/download/selenium-4.16.0/selenium-server-4.16.0.jar

# Run standalone mode
java -jar selenium-server-4.16.0.jar standalone

# Access Grid console
open http://localhost:4444

Hub and Node Setup

Start the Hub

java -jar selenium-server-4.16.0.jar hub

# With custom port
java -jar selenium-server-4.16.0.jar hub --port 4455

Start Nodes

# Node with Chrome
java -jar selenium-server-4.16.0.jar node --hub http://hub-ip:4444

# Node with Firefox
java -jar selenium-server-4.16.0.jar node \
  --hub http://hub-ip:4444 \
  --driver-implementation "firefox"

# Node with specific capabilities
java -jar selenium-server-4.16.0.jar node \
  --hub http://hub-ip:4444 \
  --max-sessions 5

Docker Deployment

Docker Compose Configuration

version: '3.8'
services:
  selenium-hub:
    image: selenium/hub:4.16.0
    container_name: selenium-hub
    ports:
      - "4442:4442"
      - "4443:4443"
      - "4444:4444"

  chrome-node:
    image: selenium/node-chrome:4.16.0
    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
      - SE_NODE_MAX_SESSIONS=4
    deploy:
      replicas: 3

  firefox-node:
    image: selenium/node-firefox:4.16.0
    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

  edge-node:
    image: selenium/node-edge:4.16.0
    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

Launch and Verify

# Start Grid
docker-compose up -d

# Scale Chrome nodes
docker-compose up -d --scale chrome-node=5

# Check status
curl http://localhost:4444/status

Connecting Tests to Grid

Python Example

from selenium import webdriver
from selenium.webdriver.chrome.options import Options

options = Options()
options.add_argument('--headless')

driver = webdriver.Remote(
    command_executor='http://localhost:4444/wd/hub',
    options=options
)

driver.get('https://example.com')
print(driver.title)
driver.quit()

Java Example

ChromeOptions options = new ChromeOptions();
options.addArguments("--headless");

WebDriver driver = new RemoteWebDriver(
    new URL("http://localhost:4444/wd/hub"),
    options
);

driver.get("https://example.com");
System.out.println(driver.getTitle());
driver.quit();

Advanced Configuration

Node Configuration File

[node]
detect-drivers = false
max-sessions = 5

[[node.driver-configuration]]
display-name = "Chrome"
stereotype = '{"browserName": "chrome", "platformName": "linux"}'
max-sessions = 3

[[node.driver-configuration]]
display-name = "Firefox"
stereotype = '{"browserName": "firefox", "platformName": "linux"}'
max-sessions = 2

Session Queue Configuration

# Set request timeout
java -jar selenium-server-4.16.0.jar hub \
  --session-request-timeout 300 \
  --session-retry-interval 5

Monitoring and Observability

GraphQL API

# Query grid status
{
  grid {
    totalSlots
    usedSlots
    nodes {
      id
      status
      sessionCount
    }
  }
}

# Query sessions
{
  sessions {
    id
    capabilities
    nodeId
  }
}

Metrics and Tracing

• Enable OpenTelemetry for distributed tracing
• Prometheus metrics available at /metrics endpoint
• Grafana dashboards for visualization

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: selenium-hub
spec:
  replicas: 1
  selector:
    matchLabels:
      app: selenium-hub
  template:
    metadata:
      labels:
        app: selenium-hub
    spec:
      containers:
      - name: selenium-hub
        image: selenium/hub:4.16.0
        ports:
        - containerPort: 4444
        - containerPort: 4442
        - containerPort: 4443
---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: chrome-node-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: chrome-node
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

Troubleshooting

• Session not created: Check node capacity and browser compatibility
• Timeouts: Increase session-request-timeout
• Memory issues: Increase shm_size in Docker
• Browser crashes: Add --disable-dev-shm-usage flag

Key Takeaways

• Grid 4 offers modern architecture with better scalability
• Choose deployment mode based on scale requirements
• Docker makes Grid deployment reproducible and scalable
• Use GraphQL API for advanced monitoring
• Kubernetes enables auto-scaling for CI/CD pipelines