Selenium RemoteWebDriver: How to Run Tests Remotely

Direct answer: Run your test code on the client and connect it to Selenium Grid with RemoteWebDriver. Give the remote driver a Grid URL the client can reach and an options object for the browser you want Grid to start. Grid routes WebDriver commands to a browser running on the Grid machine or one of its Nodes.

For a one-machine setup, start Selenium Server in Standalone mode and connect to http://localhost:4444. For CI or a separate browser machine, use that Grid’s reachable address. Selenium’s Remote WebDriver guide documents the client pattern; Selenium Grid provides the remote browser infrastructure.

1. Choose a Grid deployment

Choose based on how many machines and browser environments you need, the parallel capacity you want, and how much infrastructure you want to operate. Grid sizing depends on the environment; measure your own workload rather than treating example defaults as universal requirements.

Mode	Use it when	What it provides
Standalone	Local debugging or a small setup on one machine	One process and one machine; the default endpoint is `http://localhost:4444`.
Hub and Node	You need browser capacity on multiple machines or different browser versions	A Hub is the single entry point; Nodes contribute browser capacity.
Distributed	You need to deploy Grid components separately or customize a larger deployment	Grid components run independently and can be arranged for the deployment.

See the official Grid getting-started guide for topologies and startup examples. Keep your installed server version in view: flags, configuration and supported browsers evolve.

2. Start Selenium Server

Install a Selenium Server release appropriate for your environment and start it in Standalone mode. A typical local command is:

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

Use the server version you downloaded in place of <version>. The local Grid endpoint is normally http://localhost:4444. For the exact flags supported by your server, consult the Grid CLI options and run the installed server’s help output.

On another machine, bind and route the service so the test client can reach it, then use that machine’s Grid address in the client code. For repeatable deployments, Grid also supports TOML configuration files; Selenium recommends them for readability and source control. Check the TOML options guide for the release you deploy.

3. Connect with Java RemoteWebDriver

In Selenium 4, create the browser’s Options object and pass it along with the Grid URL. The following is a complete minimal test using Java, Selenium’s Java client, and JUnit 5:

import java.net.URL;
import org.junit.jupiter.api.Test;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.remote.RemoteWebDriver;

class RemoteSmokeTest {
    @Test
    void opensPageOnGrid() 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();
        }
    }
}

Replace the URL with your Grid endpoint and the target with an application your remote browser can access. A remote session requires both a reachable address and browser options. Use the relevant options class for Firefox, Edge or another browser supported by your Grid, such as FirefoxOptions or EdgeOptions. The Grid must have a matching browser available.

Options select the browser and can request capabilities such as browser version or platform when the Grid can match them. See Selenium’s Browser Options documentation. Prefer browser-specific Options classes in Selenium 4; older Desired Capabilities examples are associated with Selenium 3-era setup.

4. Connect with JavaScript

Install the Selenium WebDriver JavaScript package in your project, start Grid, then build the driver with a browser and server URL:

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

async function main() {
  const driver = await new Builder()
    .forBrowser('chrome')
    .usingServer('http://localhost:4444')
    .build();

  try {
    await driver.get('https://example.com');
    console.log(await driver.getTitle());
  } finally {
    await driver.quit();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

The JavaScript API also documents SELENIUM_REMOTE_URL as an alternative way to configure the remote server. Check the JavaScript API for current client details.

5. Run remotely in CI or across machines

Start Grid in a network location reachable by the CI runner or developer machine.
Make sure the requested browser and any requested version or platform are available in the Grid.
Set the remote URL in the test configuration or environment, rather than hard-coding a machine-specific address into shared test logic.
Run a small smoke test that opens a page and always calls quit(), including when an assertion fails.
Add parallel workers only after observing session capacity and resource use in your own environment.

A Grid session is a remote resource. If tests fail before cleanup, sessions can remain active until Grid or session timeouts clear them. Use a finally block (or equivalent teardown hook) so every created driver is quit.

6. Handle uploads and downloads

A path passed to a remote browser may be interpreted on the remote machine. That is a common mismatch when the file exists only on the test client. Selenium has remote upload handling for files that originate on the client; follow the Remote WebDriver file upload guidance rather than assuming the client path is visible remotely.

For downloads that need to be retrieved by the client, Grid must be started with managed downloads enabled, and the client session must opt in through its options. Consult the current Grid CLI configuration and Remote WebDriver documentation for the version-specific setup. A Grid download listing is a snapshot; it does not prove that a file has finished downloading. Wait for the expected file or application state before retrieving it.

7. Secure the Grid endpoint

Keep Grid behind appropriate network controls. Selenium warns that an externally accessible Grid can expose infrastructure, internal applications and files, and can permit third parties to run custom binaries. Do not publish an unauthenticated Grid endpoint to the public internet. Restrict network access to the test clients that need it and follow the official Grid security guidance.

8. Performance, reliability and cost

Measure your own capacity: browser startup, page behavior, machine resources and parallel workload affect throughput. Grid does not have one universal machine size.
Scale deliberately: Standalone is a simple starting point. Add Nodes or use a distributed topology when you need more machines, browser diversity or session capacity.
Release sessions: call quit() even on test failures so sessions do not consume Grid capacity unnecessarily.
Diagnose network paths: the client must reach Grid, and the remote browser must separately reach the application under test. These are different connections.
Budget infrastructure: Selenium Grid is software; infrastructure cost depends on the machines and operational setup you choose. The cited Selenium documentation does not state a universal hosting cost or performance benchmark.

9. Troubleshooting

Symptom	Likely cause	Fix
Connection refused or timeout at driver creation	Grid is stopped, the URL or port is wrong, or the client cannot route to the host.	Confirm the server is running, check the endpoint and port, and test connectivity from the same machine or CI runner as the test.
Session cannot be created	The Grid has no matching browser, version or platform, or the requested capability is unsupported.	Check available Node/browser capacity and simplify options; request only capabilities the Grid can satisfy.
Page load hangs although the session starts	The remote browser cannot reach the target site, or the target waits on network resources.	Check application reachability from the browser machine and tune explicit waits to the application’s behavior.
Upload reports that a file is missing	The path exists on the client but not on the remote browser machine.	Use Selenium’s remote upload handling for client-side files.
Download is absent or incomplete	Managed downloads or session opt-in is missing, or the listing was read before the download completed.	Enable managed downloads in Grid and the session, then wait for completion before retrieving the file.
Grid becomes saturated after failures	Tests leave sessions running because teardown was skipped.	Ensure driver cleanup runs in a finally block or framework teardown hook, and inspect active sessions.
Remote tests can access sensitive internal systems	The Grid is exposed beyond the trusted test network.	Restrict inbound access with network controls and follow Selenium’s Grid security recommendations.

10. Or skip the browser setup

If the task is to capture a website as an image or PDF rather than interact with it through a browser test, ScreenshotNeo provides a screenshot API and MCP server. A single GET request can return a PNG, JPEG, WebP or PDF. 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}`);

ScreenshotNeo removes cookie banners, newsletter popups and chat widgets before capture. Bot checks, blank pages and failed loads are never billed. Its MCP server lets AI agents use take_screenshot, get_page_info and capture_pdf. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. Sign up for 1,000 free screenshots a month, with no card.

11. FAQ

Does RemoteWebDriver run my test code on the Grid?

No. The test client runs the test code and sends WebDriver commands; Grid routes those commands to the remote browser.

Can I use localhost for a remote Grid?

Only when the Grid is on the same machine or localhost is correctly forwarded. From another machine, use an address reachable from the test client.

Can Selenium Grid take screenshots?

WebDriver sessions can support browser automation tasks such as capturing a page during a test. If you only need a website screenshot or PDF without browser test setup, ScreenshotNeo offers a direct capture API.

Where should I look for version-specific settings?

Use the Selenium documentation for the installed release and the help/configuration output of the Selenium Server binary you actually run.