File download handling in Selenium Python - Framework Patterns

Framework Mode - File download handling

Folder Structure

project-root/
├── src/
│   ├── pages/
│   │   └── download_page.py
│   ├── tests/
│   │   └── test_file_download.py
│   ├── utils/
│   │   └── file_helpers.py
│   └── config/
│       └── config.py
├── downloads/  # Folder where files are saved during tests
├── requirements.txt
└── pytest.ini

Test Framework Layers

• Driver Layer: Selenium WebDriver setup with custom options to handle file downloads automatically (e.g., setting download directory, disabling download prompts).
• Page Objects: Classes representing pages with methods to trigger file downloads and verify UI elements.
• Tests: Test cases that use page objects to perform download actions and validate downloaded files.
• Utilities: Helper functions for file system operations like checking if a file exists, waiting for download completion, and cleaning up files.
• Configuration: Settings for download folder path, browser preferences, and environment variables.

Configuration Patterns

• Download Directory: Define a fixed folder (e.g., downloads/) in config.py to store downloaded files during tests.
• Browser Options: Use Selenium browser options to set preferences like download.default_directory and disable download dialogs.
• Environment Variables: Allow overriding download folder path or browser type via environment variables for flexibility.
• Cleanup: Implement setup and teardown hooks to clear the download folder before and after tests to avoid stale files.

Test Reporting and CI/CD Integration

• Use pytest with plugins like pytest-html to generate readable test reports showing pass/fail status of download tests.
• Log file download status and file existence checks clearly in test output for easy debugging.
• Integrate tests into CI pipelines (e.g., GitHub Actions, Jenkins) ensuring the download folder is writable and cleaned before runs.
• Fail tests explicitly if the expected file is not found or download times out, so CI reports failures clearly.

Best Practices

1. Use Explicit Waits: Wait for the file to appear in the download folder instead of fixed sleep times to make tests reliable.
2. Isolate Downloads: Use a dedicated download folder per test run to avoid conflicts and stale files.
3. Clean Up: Always delete downloaded files after tests to keep environment clean.
4. Configure Browser Properly: Set browser preferences to disable download popups and auto-save files to the desired folder.
5. Validate File Content: When possible, check file size or content to confirm correct download, not just file presence.

Self Check

Where in this folder structure would you add a helper function to wait for a file to finish downloading?

Key Result

Organize Selenium Python tests with clear folder structure, browser config for downloads, utilities for file checks, and clean reporting.