How to Set Up Selenium Grid for Cross-Browser Testing

Selenium Grid runs WebDriver tests on remote browser instances. Start with a Standalone server on one machine, connect a test through RemoteWebDriver at http://localhost:4444, then move to Hub and Node or Distributed mode if you need more operating systems, browser versions, or parallel capacity.

This guide uses the Selenium Server version shown by the official downloads page at publication research time, 4.49.0 (September 9, 2026). Check the Selenium downloads page before installing: releases and defaults change.

1. Choose a Grid topology

Topology	What it runs	Use it when
Standalone	All Grid components and browser sessions in one server process on one machine.	You are learning, debugging, or running a small CI job with browsers available on that machine.
Hub and Node	A Hub provides the Grid entry point and scheduling components; one or more Nodes provide browser slots.	You need a shared endpoint backed by machines with different operating systems, browser versions, or capacity.
Distributed	Event Bus, Session Queue, Session Map, Distributor, Router, and Nodes run as separately operated components.	You need to operate or scale Grid components independently and can manage the extra network and configuration work.

Grid routes client WebDriver commands to remote browser instances, enabling parallel runs and cross-platform coverage. For a first working setup, Standalone has the fewest moving parts. The official Selenium guide describes these deployment choices in its Grid getting-started guide; its When to Use Grid page discusses when a remote Grid is useful.

2. Start Standalone Grid

Prerequisites

Java 11 or newer.
The browser or browsers you intend to run.
The Selenium Server JAR.
Browser drivers available on PATH, or Selenium Manager configured to resolve them.

Download the current Selenium Server JAR from the official downloads page. Replace 4.49.0 below if a newer stable version is listed.

java -jar selenium-server-4.49.0.jar standalone

The server listens at http://localhost:4444 by default. Open that address for the Grid UI, or request http://localhost:4444/status to inspect status. Keep the terminal running while tests execute.

Selenium Manager can manage drivers for supported environments. Selenium’s quick-start documents --selenium-manager true; for reproducible CI, verify that the Java binding and server behavior in your environment use the expected driver. An installed driver on PATH is a predictable fallback. See Selenium’s driver location troubleshooting page.

3. Connect a Java test with RemoteWebDriver

Add Selenium’s Java binding to your project using its existing dependency management, then compile this class with that dependency on the classpath. It requests Chrome and sends a session label that operators can recognize in the Grid UI. The requested browser and platform must match an available Node slot.

import java.net.URL;
import org.openqa.selenium.Platform;
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();
    options.setCapability("browserVersion", "stable");
    options.setCapability("platformName", Platform.LINUX);
    options.setCapability("se:name", "grid-smoke-test");

    WebDriver driver = new RemoteWebDriver(
        new URL("http://localhost:4444"), options);
    try {
      driver.get("https://example.com");
      System.out.println(driver.getTitle());
    } finally {
      driver.quit();
    }
  }
}

For a simple local run, omit browserVersion and platformName if you do not need to constrain matching. Capability names and supported values depend on the browser and Grid. Use the browser-specific options class, such as FirefoxOptions, when requesting Firefox. Always call quit() so the remote session and its slot are released, including when an assertion or navigation fails.

4. Request browser and platform coverage

The client sends browser options as session capabilities. Common matching fields include:

Capability	Purpose	Practical guidance
`browserName`	Browser family, such as `chrome` or `firefox`.	Browser options classes commonly set this for you.
`browserVersion`	Requested browser version.	Request a version your Nodes actually advertise. Avoid pinning a version unless the coverage requirement needs it.
`platformName`	Operating system/platform constraint.	Use values supported by the available Nodes; a mismatch leaves the request waiting or causes it to fail.
`se:name`	Human-readable session metadata.	Label suites or jobs so they are easier to identify in Grid status and the UI.

A Node advertises slots for its available browser environments. The Distributor matches a new session request to a compatible free slot. If you request a browser, version, or platform no Node offers, no capability adjustment on the client can create that missing environment: add a suitable Node or relax the constraint.

5. Expand to Hub and Nodes

Use Hub and Node when browser execution needs multiple machines or operating systems. The Hub is the entry point. Its Router accepts WebDriver traffic; the New Session Queue holds requests; the Distributor assigns them to matching Node slots; the Session Map tracks session IDs and Nodes; and the Event Bus coordinates component communication. A Node runs the browser sessions supported by its machine.

On the Hub machine, start the Hub:

java -jar selenium-server-4.49.0.jar hub

On each Node machine, register a Node with the Hub. The following command assumes the Hub is reachable at hub.example.internal; replace that host with the actual address:

java -jar selenium-server-4.49.0.jar node --hub http://hub.example.internal:4444

For machines on separate hosts, network paths must work in both directions where required: Nodes need to reach the Hub’s Event Bus, and the Hub must be able to reach each Node’s HTTP port. Selenium’s documented default Event Bus ports are 4442 and 4443; the Node also listens on its configured HTTP port (default 5555). Permit only the needed component traffic through host and network firewalls. If the Hub uses non-default ports or addresses, configure the publish and subscribe Event Bus addresses explicitly according to the official setup guide.

Start Nodes with the browser and driver combinations you want to test. Nodes can use different operating systems from the Hub and from each other. Repeat the RemoteWebDriver example against the Hub URL instead of localhost; the client does not need to know which Node receives a session.

6. Run Distributed mode

Distributed mode separates the Grid services. Use it when the operational benefit of independently placing or scaling components outweighs the extra configuration. Start the Event Bus first, then the Session Queue, Session Map, Distributor, Router, and Nodes, configuring each component to reach the others. Commands copied from the documentation often use local addresses; for a real multi-host layout, set addresses to the actual reachable interfaces and secure every path.

Selenium documents these default ports as a starting reference:

Component	Documented default port(s)
Event Bus	`4442`, `4443`, `5557`
Session Map	`5556`
Distributor	`5553`
New Session Queue	`5559`
Router	`4444`
Node	`5555`

These are documented defaults, not required universal values. Avoid pasting a localhost-only example into a multi-host deployment without replacing the addresses. Follow the command syntax and options in the current Grid getting-started documentation and CLI options reference.

7. Plan concurrency and capacity

Capacity depends on the test workload, browser, machine, and page under test. Selenium offers approximately 1 GB RAM per browser session as a planning reference, not a universal measured requirement. Its guidance generally limits Node sessions by available CPUs; the component guidance describes one default slot per CPU for Chromium browsers and Firefox, and one Safari slot by default. These defaults may not fit a particular workload.

Start with a small number of sessions per Node.
Run representative pages and test flows, not only an empty smoke test.
Track CPU, memory, session startup time, queue time, and failure rate.
Increase slots or add Nodes only while the measurements remain acceptable.
Use smaller Nodes when isolation matters more than reducing infrastructure overhead.

More slots than the machine can sustain can increase contention, slow browser startup, and make timeouts or flakes harder to diagnose. Conversely, too few slots create queue time. Re-measure when browser versions, page complexity, or test parallelism changes.

8. Verify Grid health and sessions

Open the Grid UI at the Router/Standalone address, commonly http://localhost:4444.
Request /status at that address to check status information.
Inspect registered Nodes and available slots before debugging a client capability mismatch.
Use Grid’s GraphQL interface when you need to query state and session metadata programmatically.
Ensure the test calls quit(); a leaked session keeps its slot occupied until Grid cleanup.

9. Secure the Grid endpoint

Do not expose an unauthenticated Grid openly to the internet. Selenium warns that an exposed Grid can let third parties access the Grid infrastructure and internal applications or files, and may allow custom binaries to run. Restrict client access to trusted networks and use firewall rules that allow only the client-to-Router and component-to-component traffic your chosen topology requires. There is no single production security layout that fits every network, so design the boundaries for your deployment rather than treating the default ports as a security policy.

10. Troubleshoot common setup failures

Symptom	Likely cause	Fix
Server will not start or reports unsupported class version	Java is missing or older than the server requires.	Install Java 11 or newer and check `java -version`.
Address already in use	Another process owns the configured port.	Stop the other server or configure a free port consistently for the server and clients.
`SessionNotCreatedException` or no matching capabilities	No free slot matches the requested browser, version, or platform.	Check Node registration and advertised slots; loosen unnecessary capability constraints or add the required Node.
Driver executable cannot be found	No compatible driver is available through PATH or automatic management is unavailable in that environment.	Use Selenium Manager as supported by the binding/environment, or install the matching driver and put it on PATH. See the official driver location guide.
Hub shows no Nodes	Node cannot reach the Hub/Event Bus, the Hub cannot reach the Node port, or addresses/ports do not match.	Check routing, DNS, firewall rules, advertised address, and Event Bus configuration from both machines.
Remote connection refused or times out	Server is stopped, the wrong endpoint/port is used, or network policy blocks it.	Check the server process, `/status`, URL, listening interface, and firewall path.
Sessions remain occupied after a test	Test did not close the remote session.	Put `driver.quit()` in a `finally` block, including for failed assertions.
Tests become slow or flaky at higher parallelism	CPU or memory contention, overloaded Nodes, or slow session startup.	Reduce simultaneous slots, measure resource use, and add smaller Nodes if capacity is needed.
Test runs locally but not on Grid	The remote browser has a different OS, browser version, file system, or network context.	Make test data and paths portable; verify the requested environment and that remote browsers can reach the target application.

11. Consider other execution options

Self-managed Grid gives control over machines and browser environments, with the cost of operating the server, Nodes, networking, and updates. Selenium also documents Docker-backed browser sessions and configuration for relaying commands to external WebDriver services, including cloud providers or Appium, for platforms or versions unavailable locally. Those are integration categories; coverage, pricing, and terms depend on the provider. See Selenium’s TOML configuration options for the documented configuration paths.

For a visual snapshot of a page rather than interactive browser automation, ScreenshotNeo is a separate website screenshot API and MCP server. It does not replace Selenium’s remote WebDriver test session: it returns a PNG, JPEG, WebP, or PDF from one GET request.

Or skip the browser setup

If the task is to capture a page image or PDF rather than drive a full cross-browser test, ScreenshotNeo can return the capture from one request. See the ScreenshotNeo API documentation.

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

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

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

Cookie and consent banners are accepted or removed before capture; known consent platforms, newsletter popups, and chat widgets can be removed.
Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers report the page verdict and billing status.
An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents.
The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000.

Performance, reliability, and cost notes

Performance: Browser startup and page rendering dominate many test runs. Parallel slots help only while CPU, RAM, and the target application can sustain them. Measure queue and startup time alongside test duration.
Reliability: Keep server, browser, driver, and client versions compatible; make cleanup unconditional; and confirm target pages are reachable from the browser machine, not just the test runner.
Operations: Standalone is simplest to operate. Hub/Node adds machine registration and network dependencies. Distributed adds component placement, ports, and more failure points.
Cost: A self-managed Grid consumes machine capacity and maintenance time. Selenium’s RAM-per-session guidance is a planning aid, not a pricing estimate. Compare that operational cost with any hosted service only after confirming its browser, OS, and version coverage.

Frequently asked questions

When would you use a Selenium Grid?

Use Grid when tests need remote browser execution, parallel sessions, or browser and operating-system combinations beyond the machine running the test client.

Can the Hub and Node use different operating systems?

Yes. Nodes can run on operating systems different from the Hub and from one another; capability requests are matched to Node slots.

Does the test client connect directly to each Node?

With Hub/Node or Distributed routing, the client sends its WebDriver request to the Grid Router/Hub entry point. The Grid assigns it to a suitable Node.

Do I need Docker?

No. Selenium Server can run directly with Java and browser drivers. Selenium also documents Docker-backed sessions as an option when containerized browser environments suit the deployment.