Selenium Grid 4: Setup and Parallel Browser Testing

Selenium Grid 4 lets WebDriver clients run tests against remote browser instances, including in parallel across machines. For a first setup, start Selenium Server in Standalone mode and point your client at http://localhost:4444. Use Hub/Node when browser capacity needs to span machines or different operating systems. A session starts only when its requested capabilities match an available Grid slot.

This guide covers a local setup, a multi-machine setup, runnable Java, Python, JavaScript, and cURL examples, capacity planning, operations, and common failure causes. The examples follow Selenium’s official setup documentation; they are not claims of independent execution.

1. Choose a Grid deployment mode

Mode	Use it when	What to know
Standalone	You want a simple Grid on one machine.	One server process provides the Grid endpoint and browser slots.
Hub/Node	You need browser capacity on multiple machines, or different OS/browser combinations.	The Hub is the entry point; Nodes register with it and run sessions.
Distributed components	You need to operate Grid components separately.	This gives more deployment flexibility and adds operational complexity.

Start with Standalone if one machine has the browsers and capacity you need. Move to Hub/Node when you need more machines or a broader browser and platform matrix. The right choice depends on your test matrix, desired parallel sessions, and measured CPU and memory capacity.

2. Prerequisites and local Standalone setup

Selenium’s quick start lists Java 11 or higher, installed browsers, browser drivers, and the Selenium Server JAR as prerequisites. Selenium Manager can configure drivers when enabled with --selenium-manager true. Check the official Grid getting started guide for the requirements of the version you plan to run.

Install Java 11 or higher and the browser or browsers your tests need.
Download the Selenium Server JAR for your selected version.
Start Standalone mode:

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

Replace <version> with the version in the downloaded JAR’s filename. If you want Selenium Manager to configure drivers, use the documented flag:

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

By default, configure the WebDriver client to connect to http://localhost:4444. The Grid UI is available at that endpoint. Keep the process running while clients create and use sessions.

3. Connect WebDriver clients to Grid

The client sends a new-session request to the Grid URL along with browser capabilities. Use capabilities that correspond to browsers and platforms actually available in the Grid. These examples demonstrate a remote Chrome session; the Chrome browser must be installed or registered in the environment serving that slot.

Java

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

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

Compile with the Selenium Java client dependency available on your classpath, then run the class. The Grid URL is the server endpoint; change it to the reachable Hub or Standalone address for your deployment.

Python

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 client environment before running the script. The browser itself runs on a Grid Node, not necessarily where the Python process runs.

Node.js

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

(async function gridSmokeTest() {
  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();
  }
})();

Install the Selenium JavaScript package in your project before running this script. As with other clients, the requested browser must be available in Grid capacity.

cURL: inspect the Grid status endpoint

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

The status endpoint is useful for checking whether the server responds. It does not prove that a requested browser capability has a free matching slot; verify that through the Grid UI and the session request result.

4. Add machines with Hub and Nodes

In a Hub/Node deployment, start the Hub on the machine that will provide the client-facing Grid endpoint, then start Nodes on machines that provide browser execution capacity. Register each Node with the Hub, and direct clients to the Hub. Use the CLI syntax for the exact Selenium Server release you deploy; the official getting started guide describes the Hub/Node setup path.

Conceptually, the commands follow this shape:

# On the Hub machine
java -jar selenium-server-<version>.jar hub

# On each Node machine; replace HUB_HOST with a network-reachable Hub host
java -jar selenium-server-<version>.jar node --hub http://HUB_HOST:4444

Check the current CLI reference for supported options and registration details: Selenium notes that CLI options can change before documentation is updated. Nodes need network reachability to the Hub and need the browsers and drivers required for their advertised capabilities.

For more distributed deployments, Selenium Grid components can run separately. Choose that arrangement only when the additional control is useful for your deployment and your team can operate the extra components.

5. How Grid routes and assigns parallel sessions

A client sends a new-session request to the Router. Grid places it in the New Session Queue. The Distributor tracks available slots and assigns the request to a slot whose stereotype matches the requested capabilities. A Node runs the session. The Session Map records the session ID and its Node so later WebDriver commands reach the right place.

The client requests a browser and any needed platform or browser-specific capabilities.
The request waits in the queue if no matching slot is immediately available.
The Distributor assigns it when a matching slot can accept a session.
The Node runs commands for the session until the client closes it.

Parallelism means multiple independent sessions can run at once, subject to available matching slots and machine resources. A request for a capability no Node advertises will not become satisfiable just because other browser slots are idle. Match your test capabilities to the registered browser and platform inventory.

6. Plan parallel capacity and resources

Selenium’s setup guide offers planning guidance, not performance guarantees. It says a Node’s default maximum concurrent sessions is based on CPU count, Safari is limited to one concurrent session per Node, and teams should expect around 1 GB of RAM per browser session. Treat those values as starting points from the Selenium Project, not as a benchmark for your workload. Selenium recommends measuring continuously because defaults may not fit every environment.

Estimate the number of simultaneous sessions your suite needs, then measure actual browser CPU and memory use.
Include the browser and operating-system combinations in the estimate; a free slot must match the requested capabilities.
Observe queue time, session creation failures, test duration, CPU, and memory while increasing concurrency gradually.
Use small Nodes to isolate failures; Selenium identifies Docker as a useful way to run smaller Nodes.
Set concurrency based on workload measurements and stability, rather than assuming every CPU can safely run one more browser.

The Distributor’s ability to create sessions concurrently also relies on its processors. If many tests start together, session creation itself can be a bottleneck even when browser Nodes have capacity. Staggering test starts or increasing measured Distributor capacity may help, depending on the workload.

7. Containers and Kubernetes

Selenium’s official getting started guide recommends Docker as one way to run smaller Nodes and isolate failures. Its CLI reference documents Docker and Kubernetes mappings from image names to browser stereotypes. Confirm the supported options for your server version in the CLI reference, which warns that its options may be outdated if the implementation changes before the docs.

A Selenium release article for Grid 4.41.0, dated February 22, 2026, describes Dynamic Grid support in Kubernetes: ephemeral browser Pods can be created for session requests and removed when sessions close. Treat this as release-specific information and verify the exact support and configuration for the version you deploy in the 4.41.0 release article and current documentation.

8. Security and operations

Selenium warns that Grid must be protected from external access. An exposed Grid may let third parties reach internal web applications and files or run custom binaries. Restrict network access with controls appropriate to your environment before making the endpoint reachable beyond intended clients. Avoid exposing an unauthenticated Grid directly to the public internet.

For operations, use Selenium’s Grid observability documentation to understand and debug Grid internals. A specific failure’s cause depends on the components deployed, their logs, and the workload. Record enough context to correlate client errors with queueing, session creation, Node availability, and browser execution.

9. Troubleshooting

Symptom	Likely cause	What to check or change
Client cannot connect to Grid	Server is stopped, URL or port is wrong, or network path is blocked.	Check the process, request `/status` from the client host, confirm the configured endpoint, and verify network rules.
New session waits or fails	No free slot matches the requested capabilities, or Nodes are unavailable.	Inspect the Grid UI, confirm registered Node stereotypes, and request a browser/platform that exists in the Grid.
Node does not appear in the Grid	Hub address is not reachable, registration settings are wrong, or the Node process failed.	Check the Node’s startup output and network reachability to the Hub; verify options against the deployed version’s CLI docs.
Browser session fails to launch	Browser or driver is missing, incompatible, or unavailable to the Node.	Install the required browser and driver on the Node, or use Selenium Manager when enabled and suitable for the deployment.
Tests become slower as parallelism increases	CPU, memory, or session-creation capacity is saturated.	Measure resource use and queueing, reduce concurrent sessions, or add capacity based on observed bottlenecks.
Safari concurrency does not increase	Selenium documents a one-session-per-Node Safari limit.	Plan Safari capacity around that limit and add Nodes if more concurrent Safari sessions are required.
Grid endpoint is reachable by unintended users	Network access is too broad.	Restrict access using environment-appropriate network controls and keep the endpoint private to authorized clients.
Documented CLI flag is rejected	Options can change across releases and the CLI reference can lag.	Check the documentation and help output for the exact Selenium Server JAR version in use.

10. Performance, reliability, and cost

Performance: Parallel execution can reduce elapsed suite time when tests are independent and the Grid has enough matching slots. More sessions also consume more CPU and memory, and can increase queueing or destabilize Nodes. Start with modest concurrency, then measure under representative test traffic. Selenium’s around-1-GB-per-session figure is planning guidance, not a sizing guarantee.

Reliability: Small Nodes can limit the impact of an individual Node failure. Monitor session creation, queueing, and Node health, and make sure tests close sessions in cleanup paths. A Hub/Node or distributed setup introduces network and component dependencies, so diagnose failures using the logs and observability information for the components you operate.

Cost: Selenium Grid is software; the infrastructure cost depends on the machines, containers, or Kubernetes capacity you choose and keep available. Size from measured browser mix and concurrency. Dynamic or ephemeral capacity can change how resources are provisioned, but the release feature description alone does not establish a cost saving.

11. Screenshot capture with an API

Selenium Grid is for running WebDriver scripts against remote browsers. If the task is simply to capture a webpage screenshot or PDF, a screenshot API can avoid maintaining browser infrastructure for that capture workflow. ScreenshotNeo is a website screenshot API and MCP server. Its API takes a URL and returns an image or PDF, while its MCP tools let AI agents request screenshots, page information, and PDFs.

Or skip the browser setup

For a one-off webpage capture, call ScreenshotNeo’s API instead of starting a Grid. See the ScreenshotNeo API documentation for request options.

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 banners are accepted and removed before the shot; known newsletter popups and chat widgets are removed too.
Bot checks, blank pages, failed loads, timeouts, and cache hits are never billed; responses identify the page verdict and billing status in headers.
An MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs.
1,000 screenshots per month are free with no card; paid plans start at $5 for 3,000 screenshots.

12. FAQ

Does Grid make tests parallel automatically?

Grid can assign concurrent sessions to available matching slots. Your test runner must also schedule independent tests concurrently, and the Grid must have enough capacity.

Can a local WebDriver test use a remote browser?

Yes. Use a Remote WebDriver client configured with the Grid URL and request capabilities the Grid can satisfy.

Should I use Standalone or Hub/Node?

Use Standalone to begin on one machine. Use Hub/Node when the browser matrix or required capacity needs multiple machines.

Is the 1 GB per session figure a requirement?

No. It is Selenium’s rough planning guidance. Measure your browser and workload because actual resource needs vary.