Skip to main content

File Download

When automating file downloads in web testing, it's essential to handle them consistently across different browsers to ensure reliable test execution.

Here, we provide best practices for file downloads and demonstrate how to configure download directories for Google Chrome, Mozilla Firefox, and Microsoft Edge.

Download Paths

Hardcoding download paths in test scripts can lead to maintenance issues and portability problems. Utilize relative paths for download directories to ensure portability and compatibility across different environments.

// 👎
// Hardcoded download path
const downloadPath = '/path/to/downloads';

// 👍
// Relative download path
const downloadPath = path.join(__dirname, 'downloads');

Wait Strategies

Failing to implement proper wait strategies can lead to race conditions or unreliable tests, especially for download completion. Implement explicit wait strategies to wait for file downloads to complete, ensuring synchronization between test steps.

// 👎
// No explicit wait for download completion
await browser.pause(5000);

// 👍
// Wait for file download completion
await waitUntil(async ()=> await fs.existsSync(downloadPath), 5000);

Configuring Download Directories

To override file download behavior for Google Chrome, Mozilla Firefox, and Microsoft Edge, provide the download directory in the WebDriverIO capabilities:


For an example implementation, refer to the WebdriverIO Test Download Behavior Recipe.

Configuring Chromium Browser Downloads

To change the download path for Chromium-based browsers (such as Chrome, Edge, Brave, etc.) using WebDriverIOs getPuppeteer method for accessing Chrome DevTools.

const page = await browser.getPuppeteer();
// Initiate a CDP Session:
const cdpSession = await;
// Set the Download Path:
await cdpSession.send('Browser.setDownloadBehavior', { behavior: 'allow', downloadPath: downloadPath });

Handling Multiple File Downloads

When dealing with scenarios involving multiple file downloads, it's essential to implement strategies to manage and validate each download effectively. Consider the following approaches:

Sequential Download Handling: Download files one by one and verify each download before initiating the next one to ensure orderly execution and accurate validation.

Parallel Download Handling: Utilize asynchronous programming techniques to initiate multiple file downloads simultaneously, optimizing test execution time. Implement robust validation mechanisms to verify all downloads upon completion.

Cross-Browser Compatibility Considerations

While WebDriverIO provides a unified interface for browser automation, it's essential to account for variations in browser behavior and capabilities. Consider testing your file download functionality across different browsers to ensure compatibility and consistency.

Browser-Specific Configurations: Adjust download path settings and wait strategies to accommodate differences in browser behavior and preferences across Chrome, Firefox, Edge, and other supported browsers.

Browser Version Compatibility: Regularly update your WebDriverIO and browser versions to leverage the latest features and enhancements while ensuring compatibility with your existing test suite.

Welcome! How can I help?

WebdriverIO AI Copilot