Selenium · Browser automation foundations

How do you test file downloads reliably?

Harddownloadschrome optionsfilesystemUpdated Oct 2026

Short answer

Configure a download directory in browser options, disable the download prompt, trigger the download, then poll the filesystem for a completed file. Verify content and size, and isolate the directory per test.

A download is asynchronous and happens outside the DOM. The browser may create a temporary file with a .crdownload suffix before renaming it. The test needs both browser configuration and filesystem synchronisation; a WebDriver wait alone cannot observe a file.

java

Path downloads = Files.createTempDirectory("downloads");

ChromeOptions options = new ChromeOptions();
Map<String, Object> prefs = new HashMap<>();
prefs.put("download.default_directory", downloads.toString());
prefs.put("download.prompt_for_download", false);
prefs.put("safebrowsing.enabled", true);
options.setExperimentalOption("prefs", prefs);

WebDriver driver = new ChromeDriver(options);
driver.findElement(By.linkText("Download invoice")).click();

Path completed = waitForDownload(downloads, "invoice.pdf", Duration.ofSeconds(20));
Assert.assertTrue(Files.size(completed) > 0);

The helper polls for the final file and ignores temporary download files.

Set download.default_directory explicitly; the default is hard to find and shared
download.prompt_for_download false avoids a native dialog the driver cannot see
Poll for the final filename and a stable size rather than assuming the file is complete
Use a unique temporary directory per test to avoid collisions in parallel runs
Remote Grid nodes write to their own filesystem, so the test may need a shared volume or an API check
Headless Chrome can download, but some older configurations need extra flags

If the download is served with Content-Disposition attachment, the browser starts it automatically. If the application instead opens a PDF viewer, configure the browser to download PDFs or assert through the network layer. On a Grid, the file is not on the client machine; either mount a shared directory or verify the download through the application's API.

A test that only clicks the link and checks for no error is not testing the download. Assert the file exists, has plausible content and, where relevant, matches a checksum or parsed value.

Follow-ups you should expect

Interviewers use these to check whether the first answer was understanding or memorisation.

1Why is a WebDriver wait not enough for downloads?
2How do you handle downloads on a remote Grid?
3How do you detect that a download has finished?
4What should you assert about the downloaded file?

Say it in the interview

I configure an explicit per-test download directory and suppress the native prompt, then click the download link. Since downloads are outside the DOM, I poll the filesystem for the final filename and a stable size, ignoring temporary files. On a Grid the node writes to its own disk, so I use a shared volume or verify through the API. I assert the file exists and has plausible content, not just that the click did not error.

Use this as a model, not a script. Saying it in your own words is what makes it survive follow-up pressure.

Now say it out loud.

Understanding an answer and delivering it under pressure are different skills. Rehearse this topic in a live Selenium mock interview and get scored feedback on depth, clarity and confidence.

Start a free Selenium interview Browse all questions

Follow-ups you should expect

Related questions

Now say it out loud.