From qa-compatibility
Author and operate Selenium Grid 4 - self-hosted distributed WebDriver. Covers the six-component architecture (Router / Distributor / Session Map / Event Bus / New Session Queue / Node), standalone vs hub-and-node deployment modes, Docker-image stack (selenium/standalone-chrome, selenium/hub, selenium/node-chrome), node registration, session-queue tuning, and observability. Use for self-hosted cross-browser testing - alternative to cloud grids (BrowserStack / Sauce Labs / LambdaTest) when data residency or cost-control require an on-prem solution.
How this skill is triggered — by the user, by Claude, or both
Slash command
/qa-compatibility:selenium-grid-4-runnerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Selenium Grid 4 is the self-hosted distributed WebDriver
Selenium Grid 4 is the self-hosted distributed WebDriver infrastructure - the open-source alternative to cloud-grid SaaS providers. Per selenium.dev/documentation/grid.
Composes with
browser-matrix-strategy-reference
for matrix planning. Routed by
selenium-grid-orchestrator
for cross-grid workflows.
For cloud-hosted alternatives see
browserstack-automate,
saucelabs-automate,
lambdatest-automate.
Per Selenium docs:
| Component | Role |
|---|---|
| Router | Entry point; routes WebDriver requests to the right session |
| Distributor | Allocates new sessions to available Nodes based on capabilities |
| Session Map | Tracks active sessions (session ID → Node URL) |
| Event Bus | Internal messaging between components |
| New Session Queue | Holds pending session requests when no Node available |
| Node | Runs actual browser instances; registers with the Distributor |
All components in one JVM:
# Download from selenium.dev/downloads
java -jar selenium-server-<version>.jar standalone
Default port 4444. WebDriver clients connect to
http://localhost:4444/wd/hub.
Standalone mode is suitable for a single developer's machine or a small CI runner with co-located browsers.
Hub on one machine, Nodes on others:
# Hub
java -jar selenium-server-<version>.jar hub
# Node (on another machine)
java -jar selenium-server-<version>.jar node \
--hub http://hub-host:4444 \
--port 5555
Or distributed (all components separated):
# Event Bus
java -jar selenium-server.jar event-bus --port 5557
# New Session Queue
java -jar selenium-server.jar sessionqueue --port 5559
# Session Map
java -jar selenium-server.jar sessions --port 5556
# Distributor
java -jar selenium-server.jar distributor --port 5553 \
--sessions http://sessions-host:5556 \
--sessionqueue http://queue-host:5559 \
--bind-bus-events false \
--publish-events tcp://event-bus-host:4442 \
--subscribe-events tcp://event-bus-host:4443
# Router
java -jar selenium-server.jar router --port 4444 \
--sessions http://sessions-host:5556 \
--distributor http://distributor-host:5553 \
--sessionqueue http://queue-host:5559
# Node(s)
java -jar selenium-server.jar node \
--publish-events tcp://event-bus-host:4442 \
--subscribe-events tcp://event-bus-host:4443
Per Selenium docs, the fully-distributed mode is for very large deployments; most teams run hub-and-node.
Per Selenium docs Docker images are at selenium/* on Docker Hub:
# docker-compose.yml
services:
selenium-hub:
image: selenium/hub:4.21.0
ports: ["4442:4442", "4443:4443", "4444:4444"]
chrome:
image: selenium/node-chrome:4.21.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=2
firefox:
image: selenium/node-firefox:4.21.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:
image: selenium/node-edge:4.21.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
shm_size: 2gb is required for Chrome (shared-memory bloat with
many tabs).
docker run -d -p 4444:4444 -p 7900:7900 --shm-size="2g" \
selenium/standalone-chrome:4.21.0
Port 7900 exposes noVNC (browser at http://localhost:7900) for live-session viewing.
from selenium import webdriver
driver = webdriver.Remote(
command_executor="http://grid-router:4444/wd/hub",
options=webdriver.ChromeOptions(),
)
driver.get("https://example.com")
# ...
driver.quit()
For Kubernetes-deployed Grid use the cluster-internal DNS:
http://selenium-router.test-ns.svc.cluster.local:4444/wd/hub.
Standard W3C - no grid-specific options needed:
{
"browserName": "chrome",
"browserVersion": "stable",
"platformName": "linux"
}
Per Selenium docs, key knobs:
| Setting | Effect |
|---|---|
--session-request-timeout | How long a queued session waits before failing (default 300s) |
--session-retry-interval | Polling interval for matching capabilities (default 5s) |
SE_NODE_MAX_SESSIONS | Max concurrent sessions per Node (default 1) |
SE_NODE_SESSION_TIMEOUT | Inactive session cleanup (default 300s) |
Tune SE_NODE_MAX_SESSIONS per Node's CPU + memory budget;
typical: 2 Chrome / 1 Firefox per 2-core / 4 GB Node.
Grid 4 exposes:
/graphql for session inspection/status for ready-check/wd/hub/status (Grid health, session
counts)For production add a Grafana dashboard polling Prometheus.
Grid 4 doesn't add session videos / HAR by default - that's the test client's responsibility (or via a sidecar like selenoid + selenoid-ui for Grid 3-style recording).
Logs at /var/log/seluser/ inside Docker containers, exportable
via volume mount.
on: pull_request
jobs:
e2e:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- name: Start Selenium Grid
run: docker-compose -f selenium-grid.yml up -d
- name: Wait for Grid ready
run: |
for i in {1..30}; do
curl -s http://localhost:4444/wd/hub/status | grep -q '"ready":true' && break
sleep 2
done
- name: Run E2E tests
run: pytest tests/e2e/ --grid-url=http://localhost:4444/wd/hub
- name: Tear down Grid
if: always()
run: docker-compose -f selenium-grid.yml down
| Anti-pattern | Why it fails | Fix |
|---|---|---|
shm_size default (64 MB) on Chrome node | Chrome crashes mid-session | Always shm_size: "2g" |
SE_NODE_MAX_SESSIONS too high | OOM / CPU thrashing | Conservative: 2 per 2-core Node |
| Hub-and-node without health check | Failed nodes silently drop sessions | Wait for /status ready before tests start |
| Standalone in production | No HA; single point of failure | Hub-and-node minimum for prod |
| Manually allocating ports for Nodes | Conflicts | Let Docker assign + use service DNS |
| No session-queue timeout | Sessions wait forever; CI hangs | Set --session-request-timeout bounded |
| Mixing Selenium versions across Hub + Nodes | Capability negotiation breaks | Pin same Grid version across all components |
browser-matrix-strategy-reference.browserstack-automate,
saucelabs-automate,
lambdatest-automate.selenium-grid-orchestrator.npx claudepluginhub testland/qa --plugin qa-compatibilityProvides a checklist for code reviews covering functionality, security, performance, maintainability, tests, and quality. Use for pull requests, audits, team standards, and developer training.