skip to content

Your Selenium test downloads a CSV while the browser runs on a Grid node; how do you get that file to the client?

level: seniorimportance: should knowfreq 44%

answer

  1. The file is on the wrong machine
  2. Grid can hold it for the session
  3. One capability switches the feature on
  4. Three commands: list, fetch, clear
  5. Augment the driver before the cast

basics

~10 s

Request the se:downloadsEnabled capability so Selenium 4's Grid manages the session's download folder, then call getDownloadableFiles to list what arrived, downloadFile to copy one to a client path, and deleteDownloadableFiles to clear it.

solid answer

~40 s

A download preference points at a folder on the node, so the client can never read it. Selenium 4's Grid solves this with managed downloads: request the `se:downloadsEnabled` capability on the options, and the Grid takes over the download directory for that session. The client then uses the `HasDownloads` commands — `getDownloadableFiles()` returns the names present, `downloadFile(name, targetPath)` copies one onto the client's filesystem, and `deleteDownloadableFiles()` empties the area between steps. Two operational details decide whether this works. The driver must be augmented, because the interface is mixed in only when the session actually reports the capability, and the retrieval must happen **before** `quit()`, since the per-session directory dies with the session.

code

java · 22 lines
java
void exportManifestFromGrid(URL gridUrl) throws Exception {
    ChromeOptions options = new ChromeOptions();
    options.setCapability("se:downloadsEnabled", true);

    WebDriver driver = new Augmenter().augment(new RemoteWebDriver(gridUrl, options));
    try {
        driver.get("https://freight.internal/shipments");
        driver.findElement(By.id("export-manifest-csv")).click();

        HasDownloads downloads = (HasDownloads) driver;
        new WebDriverWait(driver, Duration.ofSeconds(30))
            .until(d -> downloads.getDownloadableFiles().contains("manifest.csv"));

        Path clientDir = Files.createTempDirectory("freight-manifests");
        downloads.downloadFile("manifest.csv", clientDir);
        downloads.deleteDownloadableFiles();

        System.out.println(Files.readString(clientDir.resolve("manifest.csv")));
    } finally {
        driver.quit();
    }
}

go deeper

for a junior

Understand the core fact first: the browser writes the file where the browser runs. If that is a remote machine, no amount of preference tuning puts the file on your own disk.

for a middle

Be able to name the capability that enables managed downloads and the three commands that list, fetch and clear the session's files, and to say which side of the wire each path refers to.

for a senior

Show that you can diagnose the real failures: teardown ordering that quits before retrieval, a missing augmentation surfacing as a cast error, and a session that never had the capability at all.

for a principal

Own the decision of whether download artefacts should be pulled back per test at all, versus verifying the export at its service interface and keeping the browser suite focused on the user path.

## The problem this exists to solve Point Chrome at `download.default_directory` and the value is read by the **browser process**. Run that browser on a Grid node and the folder is on the node. A test asserting on an exported **freight manifest** from its own machine sees an empty directory, and the usual reaction — mounting volumes, shelling into hosts, copying artefacts out of band — turns a test concern into an infrastructure one. Selenium 4's Grid answers this with **managed downloads**. When a session asks for them, the Grid itself owns the download directory for that session and exposes commands that let the client list, fetch and clear what landed there. Standing up and configuring the node that serves this is the Grid's own concern; what follows is the client half. ## Turning it on The switch is a capability in the `se:` namespace — the namespace itself belongs to the Grid's client wiring — requested on the options object that starts the session: - `se:downloadsEnabled` set to `true` on the options passed to `RemoteWebDriver`. - The node must be running with managed downloads available; if it is not, sessions still start and the download commands fail. - These commands are served by the Grid, not by the browser driver, so a locally launched `ChromeDriver` cannot answer them. Locally you keep pointing the browser at a directory yourself. If the session did not request the capability, the client raises a `WebDriverException` saying downloads were not enabled, rather than returning an empty list — a useful distinction when diagnosing. ## The three commands | Command | Returns | Purpose | |---|---|---| | `getDownloadableFiles()` | `List<String>` | Names of the files currently in the session's download area | | `downloadFile(String, Path)` | nothing | Copies one named file to a directory on the client | | `deleteDownloadableFiles()` | nothing | Empties the area for this session | They live on the `HasDownloads` interface. The name you pass to `downloadFile` is one of the names `getDownloadableFiles()` gave you, and the `Path` is the **client-side** directory the file is written into. ## Why the driver has to be augmented `RemoteWebDriver` is one class facing every browser and every configuration, so capability-dependent behaviour is not declared on it statically. `Augmenter` inspects the session's actual capabilities and returns a proxy implementing the extra interfaces that session supports: ```java WebDriver driver = new RemoteWebDriver(gridUrl, options); driver = new Augmenter().augment(driver); HasDownloads downloads = (HasDownloads) driver; ``` Skip the augmentation and the cast throws `ClassCastException`, which reads like a broken import rather than a missing step. Augment a session that never requested `se:downloadsEnabled` and the interface is simply not mixed in, so the same cast fails for a different reason. ## Ordering, and the window you have The download area is scoped to the session. That makes the sequence rigid: 1. Start the session with the capability requested. 2. Drive the dashboard and click the export control. 3. Poll `getDownloadableFiles()` until the expected name appears — the click returns before the transfer finishes, and a file still being written can show up under a partial name. 4. Call `downloadFile` for that name, into a directory on the client. 5. Optionally call `deleteDownloadableFiles()` so a later step in the same session starts clean. 6. Only then `quit()`. Reverse steps four and six and the file is gone: ending the session discards its download area along with the profile. This is the single most common way the feature "does not work" — teardown in a fixture that runs before the assertion helper does. ## When it does not do what you expected - **The list is empty.** The click did not start a transfer, or it is still in flight; poll instead of reading once. - **A `WebDriverException` about downloads not being enabled.** The capability was not on the options that started this session, and adding it afterwards does nothing. - **A `ClassCastException`.** The driver was never augmented, or the session did not report the capability. - **The file is on the node, outside the managed area.** Something set a download directory preference for the session and overrode the folder the Grid manages; let the Grid own it when managed downloads are on. - **Nothing arrives for a rendered type.** A PDF the browser displays instead of saving never becomes a download at all, whichever machine it runs on. Retrieving artefacts from a **hosted** browser service is a different subject with its own mechanisms; managed downloads are the answer for a Grid you run yourself.

  • Your teardown hook quits the driver, then a helper retrieves the file. What happens and why?
    The retrieval fails, because the managed download area is scoped to the session and is discarded when the session ends. Move the `downloadFile` call into the test body, or into a hook that runs before the one owning `quit()`, so the fetch happens while the session is still alive.
  • The same code works against the Grid but throws locally. Why?
    Managed downloads are served by the Grid, not by the browser driver, so a locally launched session has nothing answering those commands. Locally you configure a download directory through browser preferences and read the file directly, since the browser is already on your machine.
  • Why call deleteDownloadableFiles when the area is discarded at the end of the session anyway?
    Because a session that exports several times accumulates names, and a later step can match a file left by an earlier one. Clearing between exports keeps `getDownloadableFiles()` unambiguous, which matters most when one long session covers more than one download.

It is the parcel desk in a building lobby: the browser leaves the export with a desk the Grid controls, and your test asks the desk to hand it over, instead of reaching into a filing cabinet in a building it cannot enter.

saying these in an interview costs you the question

  • Quits the session before retrieving the downloaded file
  • Casts RemoteWebDriver to HasDownloads without augmenting it first
  • Expects a local ChromeDriver session to serve the download commands
  • Thinks the browser preference alone reaches a remote node's file
  • Calls downloadFile once without polling for the file to appear