How to Set Up Selenium Grid for Parallel Browser Testing

Selenium Grid lets a WebDriver test client send commands to remote browser instances, so tests can run in parallel and cover different browsers, browser versions, and operating systems. For a local machine or a small CI job, start Selenium Server in Standalone mode and point a RemoteWebDriver at http://localhost:4444. Use Hub/Node when browser instances need to run on multiple machines behind one client endpoint. Choose distributed mode when you need to operate Grid components separately.

This guide uses Java for the primary WebDriver example. It also shows how to check Grid status with cURL and how to connect Python and Node.js WebDriver clients.

1. Choose a Grid deployment

Mode	Use it when	Client endpoint	Trade-off
Standalone	You want the shortest setup on one machine, such as for local development or a small CI job.	`http://localhost:4444`	All Grid components and browser sessions run in one process on one machine.
Hub/Node	You need browser sessions on multiple machines, or a mix of browser and operating-system environments.	The Hub, typically `http://<hub-host>:4444`	The Hub coordinates requests; Nodes provide browser slots and run sessions.
Fully distributed	You need separate deployment or operations for the Grid components.	The Router, typically on port `4444`	More components, network addresses, ports, and operational coordination.

Start with Standalone if it meets your needs. Selenium describes it as the easiest mode to spin up. The Selenium documentation gives rough size categories for choosing a mode, but these are estimates rather than hard limits: measure your own workload before treating a particular number of Nodes as a capacity boundary. See Selenium’s Grid getting-started guide and Grid documentation.

2. Check prerequisites

Install Java 11 or higher.
Install the target browsers on the machines that will run sessions.
Download the Selenium Server JAR for the release you intend to use. Pin a version appropriate for your project instead of relying on an unpinned download.
Make browser drivers available. Selenium Manager can configure drivers when enabled with --selenium-manager true; otherwise, install the drivers and put them on PATH.
For remote Nodes, confirm that the Hub and Nodes can reach each other on the required network ports.

Check the options supported by your installed release with java -jar selenium-server-<version>.jar --help. Configuration flags can vary by release.

3. Start a local Standalone Grid

Run this command in a terminal, replacing the placeholder with the JAR filename you downloaded:

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

The server listens on http://localhost:4444 by default. Open that address for the Grid UI. Keep the server running while the test client connects.

Java: connect with RemoteWebDriver

With Selenium Java client libraries on your project’s classpath, this runnable example connects to the local Grid and opens a page. It uses Chrome capabilities; the matching browser and driver must be available to the Grid session.

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 {
        URL gridUrl = new URL("http://localhost:4444");
        ChromeOptions options = new ChromeOptions();

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

Use the Hub URL instead of localhost when the Grid runs on another machine. Call quit() in a finally block so the session is released even if an assertion or page operation fails.

Python: connect to the Grid

Install the Selenium Python package in the client environment. This example requests a Chrome session and always closes it:

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()

Node.js: connect to the Grid

Install the Selenium WebDriver package in the client project. The remote URL is the Grid endpoint:

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();
  }
})();

4. Check Grid health and session availability

Query the status endpoint to confirm the server is responding and inspect registered Nodes, slots, and sessions:

curl --fail --silent --show-error http://localhost:4444/status

The response is JSON. Look at Node availability and free slots when a client cannot create a session. The Grid UI is also available at http://localhost:4444. Selenium documents the Grid endpoints, including the status endpoint, in its endpoint reference.

5. Add a Hub and Nodes

Use Hub/Node when tests need browser capacity on more than one machine. Start the Hub on the machine that clients will contact:

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

On a Node machine, connect its Selenium Server process to the Hub:

java -jar selenium-server-<version>.jar node --hub http://<hub-ip>:4444

For a Node on the same machine as the Hub, the basic command is:

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

When Hub and Node are on separate machines, make the Hub event bus ports 4442 and 4443 reachable from the Node, along with the Node’s configured port. If you change the Hub’s event bus ports, configure matching publish and subscribe event addresses on the Node. Use reachable hostnames or IP addresses in the Node configuration, and check your installed release’s help output for the relevant flags.

Point clients at the Hub endpoint, for example http://grid-hub.internal:4444. Add or remove Nodes to change available browser capacity. If you run multiple Nodes on one host, give each a distinct port, such as 5555 and 6666, and verify the flags for your release.

6. Configure browsers, capabilities, and Grid options

A client’s requested browser capabilities must match a browser slot available on a Node. For example, a Chrome client needs a Node able to create Chrome sessions. To run different browsers or versions, install or configure those environments on Nodes and request the corresponding capabilities from clients.

Driver setup: Enable Selenium Manager where appropriate, or install browser drivers and ensure the Grid process can find them on PATH.
Configuration files: Selenium supports TOML configuration. The documentation recommends TOML for readable, source-controlled configuration; CLI flags can be combined with TOML settings.
Session capacity: Configure Node session limits based on the host’s tested capacity, not just its CPU count.
Docker sessions: Standalone and Node setups can use Docker-backed sessions with suitable image-to-capability mapping and access to the Docker daemon.
Release-specific settings: Inspect --help and --config-help for the installed server before copying flags from another release.

See Selenium’s CLI options and TOML configuration reference for the options supported by your version.

7. Run tests in parallel safely

Grid can run separate WebDriver sessions concurrently, but the test runner must also schedule tests concurrently. Configure parallel workers in your test framework, and make sure the Grid has enough free slots and machine resources for the requested sessions.

Make each test create its own WebDriver session. Do not share a driver instance across concurrently executing tests.
Close each session in a cleanup block, even when a test fails.
Keep test data and accounts isolated when parallel tests could change the same server-side state.
Start with a small worker count, then increase it while measuring completion time, resource usage, and failure rates.
Use capabilities that match the browsers and versions registered by the Nodes.

Grid’s default Node capacity is a starting point: Selenium documents one concurrent session per CPU for Chromium-based browsers and Firefox, with Safari limited to one. The guide also gives around 1 GB of RAM per browser session as a reference. These are heuristics, not guarantees; the browser, test workload, memory pressure, and machine configuration affect actual throughput. Selenium recommends measuring performance continuously. Smaller Nodes can improve process isolation; Docker is one option for that setup. See the qualifications in the Grid getting-started guide.

8. When to use fully distributed mode

Distributed mode runs Grid roles as separate components. The main roles are:

Event Bus: carries internal messages between components.
Session Queue: holds incoming session requests.
Distributor: matches queued requests with available Node slots.
Session Map: tracks session IDs and the Nodes running them.
Router: accepts client traffic and routes commands.
Nodes: host browser slots and execute sessions.

Selenium’s example defaults include Event Bus ports 4442, 4443, and 5557; Session Queue 5559; Session Map 5556; Distributor 5553; Router 4444; and Node 5555. Treat these as example defaults, not as a deployment prescription. Start each component with addresses reachable by the components that depend on it, check for port conflicts, and use the installed release’s configuration help. Clients connect to the Router endpoint.

9. Secure the Grid network

Keep Grid endpoints accessible only to trusted test infrastructure and administrators. Selenium warns that an exposed Grid could provide access to internal web applications and files, or allow third parties to run custom binaries. Place the Grid behind appropriate network controls, restrict which machines can reach its endpoints and event bus ports, and avoid exposing it directly to untrusted networks. See Selenium’s security guidance.

10. Troubleshooting

Symptom	Likely cause	What to check or fix
Connection refused at `localhost:4444`	The server is stopped, listening elsewhere, or the client is using the wrong endpoint.	Confirm the server process is running; open the Grid UI and request `/status`. Use the Standalone, Hub, or Router URL that matches your deployment.
Session request waits or fails to create a session	No free slots, no registered Node, or requested capabilities do not match a slot.	Inspect `/status` and the Grid UI; check Node registration, slot availability, browser capabilities, and browser installation.
Node does not register with Hub	Incorrect Hub address, blocked event bus ports, or mismatched event bus settings.	Verify DNS/IP reachability and ports `4442` and `4443` between Hub and Node. If Hub ports changed, align the Node publish and subscribe addresses.
Browser or driver cannot be found	The browser is absent, driver is missing, or the Grid process cannot find it.	Install the target browser. Enable Selenium Manager if suitable, or install the driver and put it on the process’s `PATH`.
Tests pass alone but fail in parallel	Tests may share a WebDriver, account, or mutable test data, or the host may be overloaded.	Use one session per test, isolate shared data, always quit sessions, reduce worker count, and measure resource usage.
Grid starts with an unknown or rejected flag	The command came from a different Selenium Server release.	Run the installed JAR’s `--help` or `--config-help` and use the options for that version.
A Node is reachable but sessions cannot start reliably	Network access may allow registration traffic but block another required port, or the machine may be out of resources.	Check all configured component and Node ports, then inspect CPU and memory use while creating sessions.

11. Performance, reliability, and cost considerations

Concurrency is a measured capacity. More sessions can shorten a suite only while machines have enough CPU, memory, and browser capacity. Increase workers in steps and observe the workload.
Plan for session cleanup. A test that leaves sessions open occupies slots. Use guaranteed cleanup and monitor active sessions through Grid status.
Account for network placement. Remote browsers add network paths between clients, Grid components, Nodes, and the applications under test. Keep the required routes reachable and limit them to trusted systems.
Choose isolation deliberately. Smaller Nodes can contain browser process failures; container-based sessions can help isolate environments but require appropriate Docker configuration and connectivity.
Budget for infrastructure. Selenium Grid is software, but parallel sessions consume machine resources. Size machines based on observed workload and the infrastructure cost available to your team; there is no universal session-to-cost conversion.

12. Or skip the browser setup

If your goal is to capture a website screenshot rather than run interactive browser tests, ScreenshotNeo provides a website screenshot API and MCP server. A single GET request returns a PNG, JPEG, WebP, or PDF. Here is a cURL example:

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

See the ScreenshotNeo API documentation for request options. Python:

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)

Node.js:

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 banners, newsletter popups, and chat widgets are removed before capture; each cleanup step can be turned off.
Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are never billed. Responses indicate the page verdict and billing status.
An MCP server lets AI agents, including Claude and Cursor, take screenshots, inspect page information, and capture PDFs.
The free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots.

Frequently asked questions

Does Selenium Grid make my tests parallel automatically?

No. Grid supplies remote browser sessions. Configure your test runner to execute tests concurrently and ensure each concurrent test uses its own session.

Can I use Grid on one machine?

Yes. Standalone runs the Grid components on one machine and is the simplest way to connect a RemoteWebDriver client locally.

Where should the client connect in distributed mode?

Use the Router endpoint. With the default example configuration, it is on port 4444; confirm the address and port in your actual deployment.

How many parallel sessions should I configure?

Start from the available browser slots and machine resources, then measure your suite. Selenium’s CPU and memory figures are reference heuristics, not guaranteed capacity values.