Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 35 ยท Browsers and Scale

Selenium Grid

Understand Selenium Grid 4: standalone, hub and node modes, how capabilities choose a node, RemoteWebDriver, Docker images and running tests in parallel.

One browser on one laptop runs one test at a time. A suite of 400 end-to-end tests that each take 30 seconds needs more than three hours that way, and it still only covers the browser you happen to have installed. Selenium Grid solves both problems: it is a server that accepts session requests from your tests and runs them on browsers living on one or many machines. Your test code barely changes. Instead of starting a local driver, you connect to the Grid's address and describe the browser you want.

A Grid is a real server with real browsers, so none of it runs on this site. Commands, Docker files and client code are read-only. The runnable examples are node stand-ins on the Piston runner: a toy session router that matches capabilities to nodes, and a simulation that shows how parallel slots shorten a run. They model the ideas, not the real Grid code.

Why a Grid?

Speed Many tests at the same time.
Coverage Different browsers and systems.
Isolation Browsers live apart from test code.
1 / 2

The pieces of a Grid

Grid 4 is built from a few components, and it helps to know their names when you read logs or documentation:

  • Router: the front door. It receives every request from the client and forwards it.
  • New Session Queue: holds session requests until a matching slot is free.
  • Distributor: knows all nodes and decides which node gets a new session.
  • Session Map: remembers which node owns which session id, so later commands (click, get title) reach the right browser.
  • Node: a machine with browsers and drivers installed. It advertises its capabilities and how many sessions it can run at once.
  • Event Bus: carries internal messages between the components.
flowchart LR
  T["Test script<br/>RemoteWebDriver"] --> R["Router"]
  R --> Q["New Session Queue"]
  Q --> D["Distributor"]
  D --> N1["Node A<br/>Chrome, Firefox"]
  D --> N2["Node B<br/>Edge"]
  R --> M["Session Map"]
  M -. "later commands" .-> N1

A session request goes through the queue and the distributor to a node; the session map routes later commands to that node.

You rarely deal with these pieces one by one, because the three modes below package them.

Standalone, hub and node

Standalone starts all components in one process on one machine. It is the easiest way to begin, and often enough for a team with one test server:

Terminal
# read-only
java -jar selenium-server-<version>.jar standalone

By default it listens on port 4444. You can open http://localhost:4444/ui for a dashboard of sessions and http://localhost:4444/status for a JSON status.

Hub and node splits the roles. The hub is the entry point and the nodes register themselves with it:

Terminal
# read-only: on the hub machine
java -jar selenium-server-<version>.jar hub

# read-only: on each node machine
java -jar selenium-server-<version>.jar node --hub http://hub-host:4444

A node detects the browsers and drivers on its machine, so the hub learns what it can offer. Fully distributed mode runs router, distributor, session map and queue as separate processes for very large installations. Most teams never need it.

Connecting from a test

On the client side, a Grid session uses Remote, the remote variant of the driver. You pass the Grid address and the same options classes from Headless Mode and Browser Options:

Python
# read-only (Python)
from selenium import webdriver

options = webdriver.ChromeOptions()
options.add_argument("--headless=new")

driver = webdriver.Remote(command_executor="http://localhost:4444", options=options)
driver.get("https://example.test")
print(driver.title)
driver.quit()
Java
// read-only (Java)
ChromeOptions options = new ChromeOptions();
WebDriver driver = new RemoteWebDriver(new URL("http://localhost:4444"), options);

Everything after that, find_element, click and the rest, is the same code you used locally. That is why How WebDriver Works matters: the client always sent HTTP requests to a driver, and a Grid is just a driver address that sits in front of more drivers.

Always call quit() (in a fixture or a finally block). A session that is never closed keeps its slot busy until the Grid's session timeout expires, and one forgotten test can block others.

How capabilities pick a node

Your options produce capabilities, as shown in the previous lesson. The Grid compares them to what each node offers. A node matches when it provides the requested browserName, and also the platformName or browserVersion if you asked for them. If several nodes match, the distributor picks one with a free slot. If no node has a free slot, the request waits in the New Session Queue until a slot opens or the request times out. If no node could ever match (for example you asked for Safari on a Linux grid), the session fails.

The first stand-in is a toy router with exactly this logic.

Node.js A toy session router

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice the three different outcomes for a request: it starts, it waits, or it can never be served. The real Grid reports the last case as a "session not created" error, which usually means your capabilities ask for something no node offers.

Running tests in parallel

A Grid gives you capacity; your test runner must use it. Each parallel test needs its own driver session, so build the driver inside a fixture or setup method, never in a shared global. Python tests usually use pytest-xdist (pytest -n 4) and Java tests use parallel settings of JUnit or TestNG (see Selenium with JUnit and TestNG). Tests must also be independent: if test B needs data created by test A, parallel runs will break it. More on that in Flaky Tests and Debugging and Running in CI.

The speedup is limited by the number of slots. If the Grid has 4 slots, a fifth session waits. The second stand-in simulates a clock and shows how run time depends on slots.

Node.js How many slots do you need?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The last line is the lesson of the simulation: adding slots helps until you hit the longest single test, and a few slow tests set the limit. Splitting a slow test in two often helps more than buying more machines.

Docker images

Installing browsers and drivers by hand on every node is tedious, and mismatched versions cause strange failures. The Selenium project publishes Docker images, including selenium/standalone-chrome, selenium/standalone-firefox, selenium/standalone-edge, and for hub and node setups selenium/hub with selenium/node-chrome and its siblings. A standalone container is one command:

Terminal
# read-only
docker run -d -p 4444:4444 --shm-size="2g" selenium/standalone-chrome

The --shm-size flag gives the browser enough shared memory; browsers in containers can crash when /dev/shm is too small. The images also expose a port for a browser viewer (the image documentation lists it), which is very useful for watching a failing test. For several browsers, teams write a Docker Compose file with one hub service and one service per node type, and scale the nodes with docker compose up --scale. Pin image tags to a specific version, not latest, so a surprise browser update does not break your suite overnight.

When not to build your own Grid

A self-hosted Grid is flexible and cheap per test, but you maintain browsers, updates, memory and cleanup. Vendor clouds trade money for convenience, and are the topic of Cloud Providers and Mobile with Appium. A reasonable rule: begin with standalone Docker in CI, move to a Grid when parallel capacity matters, and consider a cloud when you need many real devices and operating systems.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does a Selenium Grid session request include that lets the Grid choose a node?

    The Grid compares the requested capabilities with what each node offers, then picks a matching node with a free slot.
  2. 2. What happens when all matching nodes are full?

    The queue holds requests while slots are busy. A request fails only if it times out or if no node could ever match.
  3. 3. Which line connects a Python test to a Grid running on this machine?

    Remote sends the same WebDriver commands to the Grid's address instead of starting a local driver.
  4. 4. Why must each parallel test create its own driver?

    One session is one browser with its own state. Parallel tests that share it would click over each other.
  5. 5. Why does forgetting driver.quit() hurt a Grid?

    Slots are limited. An open session holds one, so leaked sessions slow down or stall the whole suite.

Summary

  • Selenium Grid runs sessions on browsers across machines; clients connect with Remote or RemoteWebDriver and use the same code as locally.
  • Standalone runs everything in one process; hub and node splits entry point and browsers; fully distributed splits every component.
  • The router, queue, distributor, session map, nodes and event bus cooperate: capabilities choose a node, the session map routes later commands.
  • Parallel runs need independent tests and one driver per test; speedup is capped by slots and by the longest single test.
  • Docker images make nodes easy to reproduce; pin versions, give browsers enough shared memory and always quit sessions.

Next: Cloud Providers and Mobile with Appium