Browser testing is a cornerstone of modern web development, ensuring that your site behaves correctly across different browsers and devices. Selenium, paired with Python, offers a powerful yet approachable way to automate these tests. In this guide, we’ll walk you through everything you need to get started—from installing the tools to running robust test suites—so you can confidently ship bug‑free web applications.
What You’ll Need
- Python 3.8+ installed on your machine
- pip (Python package manager)
- A code editor (VS Code, PyCharm, etc.)
- Google Chrome or Mozilla Firefox installed
- ChromeDriver or GeckoDriver matching your browser version
- Optional: Git and a CI service (GitHub Actions, GitLab CI)
Step 1: Install Python and Verify pip
First, make sure Python is installed. Open a terminal and run:
python --version
If you see a version number (e.g., Python 3.11.2), you’re good to go. Verify that pip is available:
pip --version
If pip isn’t found, reinstall Python from python.org and ensure the “Add Python to PATH” option is checked.
Step 2: Set Up a Virtual Environment
Working inside a virtual environment isolates your project’s dependencies from the global Python install. Create a folder for your project and run:
mkdir selenium‑automation && cd selenium‑automation
python -m venv venv
# Activate the environment
# Windows
venvScriptsactivate
# macOS/Linux
source venv/bin/activate
Your prompt should now show (venv), indicating the environment is active.
Step 3: Install Selenium and the Browser Driver
With the virtual environment active, install Selenium via pip:
pip install selenium
Next, download the driver that matches your browser:
- Chrome: ChromeDriver
- Firefox: GeckoDriver
Extract the executable and place it in a directory that’s on your system PATH, or keep it in your project folder and reference its path in your scripts.
Step 4: Write Your First Test Script
Create a file named test_google.py and add the following code:
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.chrome.service import Service as ChromeService
from webdriver_manager.chrome import ChromeDriverManager
# Optional: use webdriver‑manager to auto‑install the driver
driver = webdriver.Chrome(service=ChromeService(ChromeDriverManager().install()))
driver.get('https://www.google.com')
search_box = driver.find_element(By.NAME, 'q')
search_box.send_keys('Selenium Python tutorial')
search_box.submit()
# Verify results page loaded
assert 'Selenium Python tutorial' in driver.title
driver.quit()
This script launches Chrome, navigates to Google, performs a search, and checks that the page title contains the query. Save the file.
Step 5: Run the Test and Handle Waits
Run the script with:
python test_google.py
If the test fails because elements aren’t ready, introduce explicit waits:
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
wait = WebDriverWait(driver, 10) # 10‑second timeout
search_box = wait.until(EC.presence_of_element_located((By.NAME, 'q')))
Using waits makes your tests resilient to network latency and dynamic page loads.
Step 6: Organize Tests with pytest
pytest is a popular testing framework that integrates nicely with Selenium. Install it:
pip install pytest
Rename your file to test_google.py (pytest discovers files that start with test_) and wrap the logic in a function:
import pytest
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.chrome.service import Service as ChromeService
from webdriver_manager.chrome import ChromeDriverManager
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
@pytest.fixture(scope='function')
def driver():
driver = webdriver.Chrome(service=ChromeService(ChromeDriverManager().install()))
yield driver
driver.quit()
def test_google_search(driver):
driver.get('https://www.google.com')
wait = WebDriverWait(driver, 10)
search_box = wait.until(EC.presence_of_element_located((By.NAME, 'q')))
search_box.send_keys('Selenium Python tutorial')
search_box.submit()
assert 'Selenium Python tutorial' in driver.title
Run all tests with:
pytest -v
pytest will report each test as passed or failed, and you can add more test functions to the same file or create a test suite.
Step 7: Generate HTML Test Reports
Readable reports help stakeholders understand test outcomes. Install pytest‑html:
pip install pytest-html
Run pytest with the --html flag:
pytest --html=report.html
The command produces report.html in your project root, containing a summary, timestamps, and screenshots (if you add them). To capture screenshots on failure, extend your fixture:
import os
import datetime
@pytest.fixture(scope='function')
def driver(request):
driver = webdriver.Chrome(service=ChromeService(ChromeDriverManager().install()))
yield driver
if request.node.rep_call.failed:
ts = datetime.datetime.now().strftime('%Y-%m-%d_%H-%M-%S')
screenshot_path = os.path.join('screenshots', f'failure_{ts}.png')
os.makedirs('screenshots', exist_ok=True)
driver.save_screenshot(screenshot_path)
driver.quit()
Step 8: Run Tests in Continuous Integration
Automating test execution on every push guarantees that new code never breaks existing functionality. Below is a minimal GitHub Actions workflow (.github/workflows/selenium.yml) that sets up Python, installs dependencies, and runs your pytest suite:
name: Selenium Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install dependencies
run: |
python -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install selenium pytest pytest-html webdriver-manager
- name: Run tests
run: |
source venv/bin/activate
pytest --html=report.html
- name: Upload report
uses: actions/upload-artifact@v3
with:
name: test-report
path: report.html
When the workflow finishes, you can download the HTML report from the “Artifacts” section of the GitHub Actions run.
Common Mistakes to Avoid
1. Mismatched driver version: Using a ChromeDriver that doesn’t match your Chrome version throws session not created errors. Keep drivers in sync or rely on webdriver-manager to handle it automatically.
2. Hard‑coding sleep statements: time.sleep(5) may work locally but leads to flaky tests on slower CI runners. Prefer explicit waits (WebDriverWait) or expected conditions.
3. Not quitting the driver: Forgetting driver.quit() leaves orphaned browser processes, consuming memory and eventually causing “cannot start new session” failures.
4. Locating elements too early: Attempting find_element before the DOM is ready raises NoSuchElementException. Use waits or check for element visibility.
5. Hard‑coding absolute XPaths: They break when the page layout changes. Prefer relative locators, CSS selectors, or data‑attributes designed for testing.
Tips and Tricks
Use Page Object Model (POM): Encapsulate page interactions in classes to keep tests readable and maintainable.
Leverage headless mode: For faster CI runs, launch browsers without UI:
options = webdriver.ChromeOptions()
options.add_argument('--headless')
driver = webdriver.Chrome(options=options)
Parallelize tests: pytest‑xdist can run multiple test files concurrently:
pip install pytest-xdist
pytest -n auto
Capture network traffic: Tools like browsermob‑proxy let you assert on HTTP requests, useful for API‑driven front‑ends.
Frequently Asked Questions
Do I need to install the browser driver manually?
No. While you can download ChromeDriver or GeckoDriver yourself, the webdriver-manager package automatically fetches the correct version at runtime, simplifying setup.
Can Selenium work with browsers other than Chrome and Firefox?
Absolutely. Selenium supports Edge, Safari, and even headless browsers like HtmlUnit. The setup is similar—install the appropriate driver (e.g., msedgedriver for Edge) and adjust the WebDriver class.
How do I handle authentication pop‑ups or CAPTCHA challenges?
For basic HTTP auth, embed credentials in the URL (e.g., https://user:[email protected]). CAPTCHA is intentionally designed to block automation; you’ll need a test environment where CAPTCHA is disabled or use a service that provides test keys.
Conclusion
Automating browser testing with Selenium and Python empowers you to catch regressions early, improve code quality, and deliver smoother user experiences. By following the steps above—setting up a clean environment, writing robust tests with explicit waits, integrating pytest for reporting, and wiring everything into a CI pipeline—you’ll have a scalable test suite that grows with your application. Remember to stay vigilant about driver versions, avoid hard‑coded sleeps, and adopt maintainable patterns like the Page Object Model. Happy testing!
Photo by Portraits of Modern Dairy on Unsplash





