Remote File Uploads with LocalFileDetector on Selenium Grid

A Selenium LocalFileDetector upload solves one specific distributed-systems problem: the test runner owns the fixture, but the browser driver runs on another machine. Passing /workspace/fixtures/invoice.pdf directly to a remote session does not move that file. The node interprets the string against its own file system and usually finds nothing.

The reliable contract is explicit. Verify the fixture on the runner, install LocalFileDetector on the Java RemoteWebDriver, send the absolute path to the real file input, and assert the application's server-backed outcome. This keeps path resolution, transport, browser selection, and application processing as separate failure boundaries.

Follow the remote upload path

The official Remote WebDriver upload guidance explains why remote sessions need a local file detector. The detector examines the text sent to the file input. When it resolves a local file, Selenium bundles and transfers that file to the remote end, then supplies a remote path that the browser node can read.

This is not a promise that the runner path becomes valid on the node. It is a transfer followed by path substitution. That distinction explains why printing the original path from the runner says little about the remote browser's state.

The file detector runs in the client binding before the element command reaches the browser driver. Selenium's remote upload support is therefore an extra transport step around normal file-input interaction, not evidence that arbitrary runner files are shared with the node. Preserve that distinction in logs: record the fixture name, byte count, and Grid session ID, but do not expose the temporary remote path or sensitive content.

Configure the Java remote session deliberately

Java remote sessions require the detector to be set. Keep the concrete remote driver in the setup code, configure it before any upload, and expose it as WebDriver afterward if the framework prefers the interface.

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

RemoteWebDriver remote = new RemoteWebDriver(
    URI.create(System.getenv("SELENIUM_GRID_URL")).toURL(),
    new ChromeOptions()
);
remote.setFileDetector(new LocalFileDetector());

WebDriver driver = remote;

Do not hide the cast inside a generic upload helper that may receive a local driver, a decorated driver, or a framework proxy. Configure transport behavior where the session is created. A local browser driver already sees the runner's file system and does not need this bridge.

Validate the fixture before contacting Grid

A missing fixture should fail as a runner setup error, not emerge later as a remote element error. Resolve from a stable project location rather than the shell's accidental working directory, and verify regular-file and readability constraints before sendKeys.

import java.nio.file.Files;
import java.nio.file.Path;

Path fixture = Path.of("src", "test", "resources", "uploads", "invoice.pdf")
    .toAbsolutePath()
    .normalize();

if (!Files.isRegularFile(fixture) || !Files.isReadable(fixture)) {
    throw new IllegalStateException("Unreadable upload fixture: " + fixture);
}

Generate per-test files under the test runner's temporary directory when content is scenario-specific. Give them deterministic content and a safe filename, close every output stream before selection, and delete the runner copy in teardown. Avoid logging file contents or secrets merely to prove the fixture exists.

Send the path to the actual file control

WebDriver file selection targets an HTML input whose type is file. It does not operate the operating system chooser. Modern applications often style a button over a visually hidden input, so inspect the DOM and locate the underlying control rather than clicking the decorative button and waiting for a native dialog.

import org.openqa.selenium.By;
import org.openqa.selenium.WebElement;

WebElement input = driver.findElement(
    By.cssSelector("input[type='file'][name='attachment']")
);
input.sendKeys(fixture.toString());

driver.findElement(By.cssSelector("button[data-testid='upload']")).click();

The input's accept attribute is a browser hint, not sufficient application validation. Keep negative tests for disallowed extension, MIME mismatch, malformed content, empty files, and size policy at the application boundary. If the control supports multiple files, first confirm that its multiple attribute and the binding's multi-path behavior match the intended case; otherwise upload one fixture per test to keep diagnosis clear.

Assert selection separately from processing

File selection and application upload are different transitions. After sendKeys, the browser has associated a file with the control. The application may still need a button click, a change-event handler, a multipart request, virus scanning, object storage, and a status update.

A strong test waits for a domain result:

import java.time.Duration;
import org.openqa.selenium.support.ui.ExpectedConditions;
import org.openqa.selenium.support.ui.WebDriverWait;

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(20));
wait.until(ExpectedConditions.attributeToBe(
    By.cssSelector("[data-testid='attachment-row']"),
    "data-upload-state",
    "complete"
));

String shownName = driver.findElement(
    By.cssSelector("[data-testid='attachment-name']")
).getText();
if (!shownName.equals(fixture.getFileName().toString())) {
    throw new AssertionError("Unexpected uploaded filename: " + shownName);
}

An input value commonly exposes a sanitized filename rather than a usable local or remote path. Do not assert the temporary Grid location. It is an implementation detail with a lifecycle owned by the remote end.

Classify failures by boundary

When selection fails before a network transfer, inspect the runner path, permissions, and whether the detector was installed on the concrete remote session. If Grid reports an upload command error, inspect request size limits, proxy limits, node storage, and remote logs. If sendKeys returns an invalid-file or argument error, confirm the target is truly a file input and the transferred path is accepted by the driver.

When selection succeeds but the submit action fails, move downstream. Capture the form validation message, upload request result, and application status. A server rejection is not repaired by retrying sendKeys. A stale input after a component rerender requires relocating the element, but blindly repeating the whole upload can create duplicate attachments.

Containers add another useful clue. A path visible inside the runner container is still local from Selenium's perspective. It need not be mounted into the browser container when LocalFileDetector is transferring it. Conversely, a shared mount can mask a missing detector locally and then fail on a cloud Grid with a different layout.

Run one controlled diagnostic with a tiny text fixture when the boundary is unclear. If that transfer fails, investigate client configuration, Grid routing, and node storage before application code. If it selects successfully but a production-like document does not, compare filename policy, byte size, proxy limits, and server validation. This split avoids blaming remote transport for a rejection that occurred after the browser submitted the form.

Parallel tests should create uniquely named fixtures and never mutate a shared file. A detector reads the local path when the command is prepared; another worker rewriting that path can send nondeterministic bytes even though both tests report the same filename. Per-test directories make the fixture's lifetime and evidence unambiguous.

Make security and cleanup part of the test design

Treat uploaded fixtures as data crossing machine boundaries. Use synthetic records, strip credentials and personal data, and keep the minimum content required for the assertion. Grid logs, request traces, screenshots, and retained node artifacts can outlive the test run.

The client can remove its own generated file, while remote temporary-file cleanup belongs to the Selenium service or Grid provider. Do not assume a known node path or issue shell cleanup from the test. For very large fixtures, compare the cost of repeated transfer with a controlled fixture service or pre-provisioned read-only volume. That infrastructure tradeoff should remain explicit, because it exchanges portability for setup and lifecycle management.

Retain only sanitized upload evidence in CI artifacts. A fixture filename, declared byte size, content hash designed for the test, session ID, and application attachment ID are normally enough to correlate the stages without publishing the document itself.

Apply a remote upload checklist

• Resolve an absolute fixture path on the runner.
• Verify that the fixture is a readable regular file.
• Configure LocalFileDetector on the Java RemoteWebDriver.
• Locate the real input[type='file'] instead of a native chooser.
• Send the path once and relocate the control after any rerender.
• Assert a completed application state, not only the selected filename.
• Preserve sanitized client, Grid, and server evidence on failure.
• Keep fixture data synthetic and clean runner-generated files.
• Avoid assertions against a remote temporary path.

Close with the right ownership model

Remote upload reliability comes from assigning each stage to its owner. The runner owns fixture creation and readability, Selenium owns local detection and transfer, the node owns its temporary copy, the browser owns file selection, and the application owns validation and storage. Configure that chain once, assert each meaningful transition, and a Grid upload stops being a mysterious path problem.