What Is Selenium Grid and How Does It Work?

Selenium Grid is Selenium’s system for routing WebDriver scripts to remote browser instances. It lets teams run tests in parallel across machines and cover different browsers, browser versions, and operating systems. In Selenium Grid 4, a new session is queued, matched to an available browser slot, and then routed to the Node that runs it.

The request path is: Router → New Session Queue → Distributor → Node. The Session Map remembers which Node owns each session, so later WebDriver commands reach the right browser. Grid’s Event Bus carries asynchronous messages among components.

1. Why use Selenium Grid?

A local WebDriver session usually runs on the machine where the test process runs. Grid adds a remote execution layer: your test sends WebDriver commands to a Grid endpoint, and Grid starts or reuses browser capacity on one of its Nodes.

Parallel execution: multiple sessions can run at once, subject to available slots and machine resources.
Browser coverage: Nodes can provide different browsers or browser versions.
Platform coverage: Nodes can run on different operating systems and machines.
Centralized routing: tests target a Grid endpoint rather than needing to know which machine will host each session.

Grid is for executing WebDriver sessions and tests. It is not a screenshot-cleaning service or a way to avoid operating browser infrastructure: you provision, configure, secure, and maintain the Grid capacity.

2. How a Grid 4 request works

Router receives the command. The Router is the external entry point. For a new session it forwards the request to the New Session Queue; for an existing session it consults the session mapping and routes commands to the owning Node.
New Session Queue holds the request. Requests wait in FIFO order while Grid looks for a compatible free slot. Queue timeout and retry behavior are configurable.
Distributor finds capacity. The Distributor tracks registered Nodes and their capabilities, then tries to match the requested capabilities to an available slot. If none is available, the request can wait or eventually time out.
Node starts the browser session. A Node hosts browser slots and executes the WebDriver session. A Node can offer one or more browser configurations, depending on its setup.
Session Map records ownership. The session ID is associated with the Node running it, which allows subsequent commands to be routed correctly.
Event Bus carries internal events. Grid components use it for asynchronous communication. Operations that need a direct answer also use synchronous HTTP requests.

The requested capabilities matter: a request that asks for a browser or platform that no registered slot can satisfy will not be assigned to an incompatible slot. Depending on the queue configuration and available capacity, it waits or fails after a timeout.

3. Grid deployment modes

Mode	How components run	Good fit	Trade-offs
Standalone	All Grid components run together in one process on one machine.	Local development, debugging, quick suites, or a simple CI setup.	Simple to start, but capacity and failure boundaries remain on one machine.
Hub-and-Node	A Hub groups the front-end and coordination components; one or more Nodes register browser slots with it.	A single entry point for machines with different operating systems, browsers, or versions, with capacity that can be scaled up or down.	Requires network communication between Hub and Nodes and operational care for each machine.
Fully distributed	Grid components run separately, ideally on different machines.	Teams that need to deploy and operate components independently.	Most infrastructure and networking complexity; component communication and ports must be configured correctly.

Choose based on the browser and OS matrix you need, desired concurrency, number and location of machines, network topology, and the isolation you want between failures. Standalone is a practical starting point; move to multiple Nodes when you need more simultaneous sessions or coverage across machines and platforms.

4. Start a local Standalone Grid

The Selenium quick start describes Java 11 or higher, a browser, browser drivers (or Selenium Manager configuration), and the Selenium Server JAR as prerequisites. These can change by release, so check the documentation for the version you deploy.

Download the Selenium Server JAR for the release you intend to use from the official Selenium downloads page.
Ensure Java, a supported browser, and the needed driver setup are available on the machine.
Start the server in Standalone mode:

java -jar selenium-server-<version>.jar standalone

The default RemoteWebDriver endpoint in the documented quick start is http://localhost:4444. Keep the server process running while the test executes. The following Java example uses Selenium’s RemoteWebDriver API and opens a page:

import java.net.URL;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.remote.RemoteWebDriver;

public class GridSmokeTest {
  public static void main(String[] args) throws Exception {
    ChromeOptions options = new ChromeOptions();
    WebDriver driver = new RemoteWebDriver(
        new URL("http://localhost:4444"), options);
    try {
      driver.get("https://example.com");
      System.out.println(driver.getTitle());
    } finally {
      driver.quit();
    }
  }
}

Add the Selenium Java client library to the project using the build tool and version you use for the Selenium Server. The exact dependency coordinates and browser setup depend on your project and deployed release; consult Selenium’s current getting-started guide rather than copying stale version numbers.

5. Connect with cURL, Python, and Node.js

Grid speaks the WebDriver protocol over HTTP. These examples show the basic W3C WebDriver session lifecycle against the local Standalone endpoint: create a session, navigate, retrieve the title, then delete the session. They assume the Grid has a compatible browser slot and that the browser and driver setup is valid. The session response can contain either W3C or legacy-shaped fields depending on server/client compatibility; modern Selenium Grid uses W3C WebDriver.

cURL

curl -sS -X POST http://localhost:4444/session \
  -H 'Content-Type: application/json' \
  -d '{"capabilities":{"alwaysMatch":{"browserName":"chrome"}}}'

Copy the returned value.sessionId, then use it in the session URL:

SESSION_ID='paste-session-id-here'
curl -sS -X POST "http://localhost:4444/session/$SESSION_ID/url" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com"}'
curl -sS "http://localhost:4444/session/$SESSION_ID/title"
curl -sS -X DELETE "http://localhost:4444/session/$SESSION_ID"

Python

For ordinary test suites, use Selenium’s Python binding so it manages WebDriver protocol details:

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

options = Options()
driver = webdriver.Remote(
    command_executor="http://localhost:4444",
    options=options,
)
try:
    driver.get("https://example.com")
    print(driver.title)
finally:
    driver.quit()

Install the Selenium Python package in the environment that runs the test. The browser itself must be available on the Node, not necessarily on the client machine.

Node.js

Using the Selenium WebDriver package:

const { Builder, Browser } = require('selenium-webdriver');

(async () => {
  const driver = await new Builder()
    .usingServer('http://localhost:4444')
    .forBrowser(Browser.CHROME)
    .build();
  try {
    await driver.get('https://example.com');
    console.log(await driver.getTitle());
  } finally {
    await driver.quit();
  }
})().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Install the selenium-webdriver package in the test project. In all three clients, use the reachable Grid URL from the client’s network perspective; localhost only works when client and Grid endpoint share the same host or network namespace.

6. Add Nodes and choose capabilities

In Hub-and-Node or distributed deployments, Nodes register browser capacity with the Hub/Distributor. Nodes can live on different machines and operating systems. The Grid matches each new session request to an available slot based on requested capabilities such as browser name and any configured browser version or platform details.

Keep the requested capabilities aligned with what Nodes actually advertise. If tests request a specific browser version, OS, or custom capability, verify that a matching slot is registered. A session request cannot create missing browser capacity by itself.

Exact command-line flags, configuration keys, ports, and component startup procedures are release-sensitive. Inspect the configuration help for the Selenium Server version in use, and use the running implementation’s info commands where available. The current implementation can be more accurate than documentation that has not yet caught up with a release.

7. Size the Grid for concurrency

Estimate capacity from the browser and OS combinations you must support, how many sessions need to run at once, the number of machines, and each machine’s CPU and RAM. Selenium’s getting-started guidance says a Node’s default concurrent-session limit is based on available CPUs (with Safari as an exception) and gives around 1 GB RAM per browser session as an operational expectation. Treat that number as planning guidance, not a guarantee or benchmark: browser type, page complexity, test behavior, and environment change actual usage.

Start with fewer concurrent sessions per Node than the theoretical CPU maximum if tests are memory-heavy or browser stability matters.
Use smaller Nodes when process isolation or a smaller failure boundary is valuable.
Measure your own suite’s queue time, session startup time, CPU, and memory under representative load before increasing parallelism.
Include session startup and cleanup time in capacity planning; a browser slot remains occupied until its session ends.

8. Operations, security, and reliability

The Router is the Grid’s external entry point. Selenium strongly cautions operators against exposing it to the wider web. Put access controls and network boundaries appropriate to your environment in front of Grid, and allow only the configured component and Node communication paths. Verify ports and secure communication settings for the exact Selenium release and deployment; defaults can change.

Reliability depends on the whole path: clients must reach the Router, internal components must communicate, Nodes must remain registered, and matching slots must be available. Use queue timeouts that fit your suite, ensure tests always call quit() even on failure, and monitor whether sessions are waiting, starting, or occupying slots. A Grid that has Nodes online can still be unable to serve a request when the requested capabilities do not match available capacity.

9. Troubleshooting

Symptom	Likely cause	What to check or fix
Connection refused at `localhost:4444`	Grid is not running, listens on another address/port, or the client is in a container or remote host where localhost means something else.	Start the server, confirm its configured endpoint, and use the hostname reachable from the test process.
New session waits, then times out	No free slot matches requested capabilities, a Node is offline, or capacity is exhausted.	Check registered Nodes and slots, relax unnecessarily strict capabilities, add matching capacity, or tune the queue timeout for the workload.
Browser or driver cannot be found	The browser/driver is missing or incompatible on the Node, or Selenium Manager/setup is not configured as expected.	Install or configure browser support on the machine that hosts the Node; check the Selenium release’s prerequisites.
Session created but navigation or commands fail	Node-to-browser problems, a network issue, or the target page is unavailable from the Node environment.	Check Node logs and connectivity from the Node, and distinguish page access failures from Grid routing failures.
Node does not register	Hub/Distributor address, component communication, firewall rules, or configuration is wrong.	Confirm the Node can reach the configured Grid components and that configured HTTP/Event Bus paths and ports are allowed.
Commands reach the wrong or missing session	The session ended, the client has a stale session ID, or the request is sent to a different Grid endpoint.	Use the session ID returned for that run, keep a consistent endpoint, and do not reuse IDs after `quit()`.
Grid behavior differs from an example	Configuration flags or defaults changed between Selenium releases.	Run the deployed server’s `--help config` and relevant `info` commands; verify guidance against that release.
Sessions become unstable at higher parallelism	CPU or memory pressure, oversized Nodes, or workload-specific resource use.	Reduce per-Node concurrency, add machines, or split capacity into smaller Nodes; size from representative workload observations.

10. Performance and cost considerations

Grid improves suite throughput when the time saved by parallel execution exceeds session startup, coordination, and infrastructure overhead. Adding slots does not guarantee a linear speedup: tests can contend for CPU, memory, network, test data, or shared services. Browser sessions also consume resources while idle if tests do not clean them up.

Self-hosted Grid has infrastructure and maintenance costs: machines, browser setup, upgrades, network configuration, monitoring, and time spent keeping Nodes healthy. The right comparison is your actual parallel run time and operating effort against the cost of the capacity required. The Selenium documentation gives planning guidance, not a universal cost or throughput figure.

11. ScreenshotNeo as an alternative for screenshot capture

If your task is to produce website screenshots rather than execute interactive WebDriver tests, ScreenshotNeo is a purpose-built screenshot API and MCP server from Yorker Media. It does not replace Grid for running Selenium test suites. Its one-call endpoint returns a PNG, JPEG, WebP, or PDF and avoids setting up browser infrastructure for screenshot-only jobs.

Or skip the browser setup

For a screenshot, make one GET request. See the ScreenshotNeo API documentation for parameters and formats.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://example.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots, and every feature is on every plan.

12. FAQ

Does Selenium Grid run tests in parallel automatically?

Grid can serve multiple sessions concurrently when matching slots are available. Your test runner still needs to schedule tests in parallel, and the Grid must have enough capacity.

Can Grid run browsers on different operating systems?

Yes. Nodes can be on different machines and platforms, allowing a single Grid endpoint to route sessions across that capacity.

Is a Hub required?

No. Standalone groups all components in one process. Hub-and-Node and fully distributed layouts are options for adding machines or separating component operations.

What should I use for a screenshot-only workflow?

A screenshot API can avoid provisioning and operating WebDriver browser Nodes when you only need rendered images or PDFs. Selenium Grid remains useful when the workflow needs WebDriver interaction and test execution.