Downloading Files using selenium

Introduction

In the world of test automation, downloading files is a common yet tricky task. Whether it’s PDFs, CSVs, images, or Excel reports, testers often need to validate that a file has been successfully downloaded — and Selenium WebDriver makes it possible with the right configurations.

However, Selenium Testing doesn’t directly interact with the operating system’s file download dialog boxes. Instead, it automates browsers by controlling their settings and preferences before initiating a download.

In this article, you’ll learn:

• How to configure browsers (Chrome, Firefox, Edge) for automatic downloads
• How to verify file downloads using Selenium
• Common issues and troubleshooting tips
• Best practices for handling downloads in real-time test environments

Why File Downloads Matter in Automation Testing

File downloads are part of countless web application workflows from exporting invoices and reports to generating analytics or downloading receipts.

Manual verification of these downloads is tedious and error-prone. With Selenium automation, QA professionals can:

• Save time by automating repetitive download validations
• Integrate file download verification in CI/CD pipelines
• Ensure data integrity in export features
• Validate reports and downloadable test outputs automatically

By mastering this, testers become more efficient and increase test coverage significantly.

Setting Up the Environment

Before you begin automating file downloads, ensure that you have:

• Selenium WebDriver installed
• Browser drivers like ChromeDriver or GeckoDriver configured
• Java or Python environment ready
• A test website or application that provides downloadable content

Example Setup in Python

from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from selenium.webdriver.chrome.options import Options
import time
import os

# Define download directory
download_dir = os.path.abspath("downloads")

# Configure Chrome Options
chrome_options = Options()
prefs = {"download.default_directory": download_dir,
         "download.prompt_for_download": False,
         "directory_upgrade": True}
chrome_options.add_experimental_option("prefs", prefs)

# Launch browser
service = Service("path/to/chromedriver")
driver = webdriver.Chrome(service=service, options=chrome_options)

# Navigate to test URL
driver.get("https://file-examples.com/index.php/sample-documents-download/")

# Click download link
driver.find_element("xpath", "//a[contains(text(), 'Download sample DOC file')]").click()

# Wait for download
time.sleep(5)

driver.quit()
print("File downloaded to:", download_dir)

This example shows how to use ChromeOptions to suppress the download popup and specify a default directory where files are automatically stored.

Configuring Browsers for File Downloads

Different browsers require slightly different settings for automatic file downloads.

1. Chrome Browser Configuration

Chrome allows setting preferences through ChromeOptions:

prefs = {
    "download.default_directory": "C:\\Users\\TestUser\\Downloads",
    "download.prompt_for_download": False,
    "safebrowsing.enabled": True
}
chrome_options.add_experimental_option("prefs", prefs)

This ensures that Chrome automatically downloads the file to the specified folder without asking for user confirmation.

2. Firefox Browser Configuration

Here, you define MIME types for files to be downloaded automatically without showing dialogs.

Firefox uses profiles to handle preferences.

from selenium import webdriver
from selenium.webdriver.firefox.service import Service
from selenium.webdriver.firefox.options import Options
import os

download_dir = os.path.abspath("firefox_downloads")
profile = webdriver.FirefoxProfile()

# Configure preferences
profile.set_preference("browser.download.folderList", 2)
profile.set_preference("browser.download.dir", download_dir)
profile.set_preference("browser.helperApps.neverAsk.saveToDisk", "application/pdf,application/octet-stream")
profile.set_preference("pdfjs.disabled", True)

driver = webdriver.Firefox(firefox_profile=profile)
driver.get("https://file-examples.com/index.php/sample-documents-download/")

3. Microsoft Edge Configuration

Edge (Chromium-based) follows Chrome-style preferences:

from selenium import webdriver
from selenium.webdriver.edge.service import Service
from selenium.webdriver.edge.options import Options

edge_options = Options()
prefs = {"download.default_directory": "C:\\Downloads", "download.prompt_for_download": False}
edge_options.add_experimental_option("prefs", prefs)

driver = webdriver.Edge(service=Service("path/to/msedgedriver"), options=edge_options)
driver.get("https://example.com/download-page")

Verifying File Downloads

After triggering a file download, you must ensure that the file has been successfully saved to the target directory.

Python Example: Check if File Exists

import os, time

file_path = os.path.join(download_dir, "sample.doc")

# Wait for file to appear
timeout = 30
while timeout > 0:
    if os.path.exists(file_path):
        print("✅ File downloaded successfully:", file_path)
        break
    else:
        time.sleep(1)
        timeout -= 1

if timeout == 0:
    print("❌ File not downloaded!")

Java Example: File Verification

File file = new File("C:\\Users\\TestUser\\Downloads\\sample.doc");
if(file.exists()) {
    System.out.println("File Downloaded Successfully");
} else {
    System.out.println("Download Failed");
}

This validation step is essential for automated test reporting.

Handling Different File Types

Applications often provide downloads in different formats — each requiring proper handling.

Ensure that the MIME type matches exactly what the web server sends; otherwise, the browser might prompt manually.

Using Headless Mode for File Downloads

Headless browsers are ideal for CI/CD pipelines where no graphical interface exists. However, earlier versions of Chrome didn’t support file downloads in headless mode — this has now been resolved with command-line flags.

Example

chrome_options = Options()
chrome_options.add_argument("--headless=new")
chrome_options.add_argument("--disable-gpu")
chrome_options.add_argument("--window-size=1920,1080")
prefs = {
    "download.default_directory": download_dir,
    "download.prompt_for_download": False,
    "safebrowsing.enabled": True
}
chrome_options.add_experimental_option("prefs", prefs)

With the “new headless” mode in Chrome 109+, file downloads work seamlessly.

Common Issues and Troubleshooting

1. Download Popup Appearing

If a popup still appears, ensure download.prompt_for_download is set to False, and for Firefox, include the proper MIME type in neverAsk.saveToDisk.

2. File Not Downloaded in Headless Mode

Use the latest driver and browser versions — earlier releases didn’t fully support downloads in headless mode.

3. Permission Denied Error

Make sure the download folder exists and the test environment has write permissions.

4. Unknown File Extension

Sometimes servers mislabel file types. Use browser developer tools to inspect the Content-Type header of the file response and adjust MIME types accordingly.

Best Practices for Automating File Downloads

Define Unique Download Directories per Test

Use a fresh folder for every test to avoid conflicts or leftover files:

import tempfile
download_dir = tempfile.mkdtemp()

Clean Up After Tests

Remove downloaded files post-validation to save storage and keep CI environments clean.

Wait for Download Completion

Use loops or WebDriverWait with filesystem checks instead of static sleep() calls to ensure reliability.

Use Relative Paths

Avoid hard-coded absolute paths, which can break across environments.

Combine with Assertions

Integrate file existence checks with test assertions in frameworks like pytest or JUnit to create robust automated suites.

Advanced: Validating File Contents

Sometimes, merely checking the presence of a file isn’t enough. You may need to verify that the content matches expectations.

Example – Verify CSV Content

import csv

with open(file_path, newline='') as csvfile:
    reader = csv.reader(csvfile)
    header = next(reader)
    assert header == ['Name', 'Email', 'Country']
    print("File content validated successfully.")

Example – Validate PDF Download

For PDFs, you can use the PyPDF2 or pdfplumber library to read text and assert content inside the file.

Integrating with CI/CD Pipelines

In modern DevOps and CI/CD environments, automated download validation can be triggered on every build.

• Use headless Chrome or Firefox to execute tests in pipelines like Jenkins or GitHub Actions.
• Store downloaded files temporarily in the workspace for validation.
• Archive results and logs for traceability.

Example Jenkins snippet:

stage('Run Selenium Download Tests') {
    steps {
        sh 'pytest tests/test_download_files.py --headless'
    }
}

This ensures consistent verification of downloadable assets in every deployment.

Real-World Use Cases

1. Financial Applications:
   Validate PDF invoices or transaction reports generated daily.
2. E-Commerce Platforms:
   Automate the download and verification of order receipts.
3. Data Analytics Dashboards:
   Test CSV or Excel data exports for accuracy.
4. Educational Portals:
   Ensure course materials and certificates are downloadable by users.

By using Selenium, testers can replicate actual user behavior and guarantee the integrity of critical downloadable resources.

Sample End-to-End Script

Here’s a complete example combining all steps:

import os, time
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from selenium.webdriver.chrome.options import Options

download_dir = os.path.abspath("test_downloads")

# Configure Chrome
chrome_options = Options()
prefs = {"download.default_directory": download_dir,
         "download.prompt_for_download": False,
         "safebrowsing.enabled": True}
chrome_options.add_experimental_option("prefs", prefs)

driver = webdriver.Chrome(service=Service("path/to/chromedriver"), options=chrome_options)

# Test workflow
driver.get("https://file-examples.com/index.php/sample-documents-download/")
driver.find_element("xpath", "//a[contains(text(), 'Download sample DOC file')]").click()

# Wait and verify
file_name = "file-sample_100kB.doc"
file_path = os.path.join(download_dir, file_name)

for _ in range(30):
    if os.path.exists(file_path):
        print("✅ File successfully downloaded:", file_path)
        break
    time.sleep(1)
else:
    print("❌ File download failed.")

driver.quit()

This code opens a webpage, triggers a download, waits for completion, and verifies success all in one seamless test.

Conclusion

Automating file downloads using Selenium is an essential skill for QA test automation professionals. By configuring browser settings properly and validating downloads programmatically, you can ensure test accuracy, reduce manual effort, and improve overall efficiency.

Whether you’re working with Chrome, Firefox, or Edge, the key principles remain the same control the browser’s preferences, trigger downloads automatically, verify file existence, and optionally validate file content.

Mastering these techniques prepares you for real-world test scenarios where reliability and automation coverage matter most.