Selenium - Browser Automation That Actually Works Everywhere

Selenium is some browser automation toolkit from 2004. Jason Huggins built it at ThoughtWorks because clicking through web forms manually was driving everyone insane. Now it's everywhere because it was first to market and migrating existing test suites would cost more than anyone wants to think about.

The Selenium Suite: Four Components (Sort Of)

OK, so Selenium isn't actually one tool - it's like four different things that are supposed to work together:

WebDriver - The One Everyone Actually Uses

WebDriver is the main thing you'll actually interact with. It's supposed to talk to browsers through their native APIs, which works fine until Chrome decides to update and your entire test suite starts throwing weird errors.

The W3C WebDriver standard supposedly fixed browser compatibility issues, though in practice you'll still hit browser-specific quirks regularly. You can write tests in Java, Python, C#, Ruby, or JavaScript - pick whichever one your team hates least this month.

What works:

• Clicks buttons, fills forms, finds elements
• Works in headless mode for CI/CD
• Supports modern web shit like shadow DOM and relative locators
• Integrates with Chrome DevTools Protocol for debugging

What doesn't work (and will ruin your day):

• StaleElementReferenceException will haunt your dreams - elements disappear the moment you try to click them
• Tests run slower than your patience can handle, especially compared to modern tools like Playwright
• Element not found errors that make zero sense even when you can clearly see the fucking element right there
• File upload dialogs still require OS-level workarounds that break half the time
• Timing issues everywhere - too fast and elements aren't ready, too slow and tests take forever

Grid - For When One Slow Test Suite Isn't Enough

Selenium Grid is supposed to let you run tests on multiple machines simultaneously. In theory, this speeds things up. In practice, you'll spend way more time debugging Grid node connectivity problems and version mismatches than you save on parallel execution.

Grid 4 has some web UI that shows you all your failing tests in real-time, which is either helpful for debugging or just depressing when you realize how broken everything is. Docker support means you can at least containerize your suffering and make it reproducible.

The setup is still a pain - half the time nodes don't register properly, and the other half they lose connection for no apparent reason. There's extensive troubleshooting docs which should tell you something about how often this breaks.

IDE - Record and Playback Tool

Selenium IDE is a browser extension that records your clicks and generates test code. It's useful for prototyping and demos. The generated code requires significant refactoring for production use.

Manager - Automatic Driver Management

Selenium Manager automatically downloads and manages browser drivers. This solved the biggest pain point - manually updating ChromeDriver every time Chrome updated.

Current Version: 4.35.0 (as of August 2025)

The latest Selenium version is 4.35.0 as of August 2025. They release updates every few weeks, so check the downloads page for whatever's newest. The release notes mention better BiDi support and Grid stability fixes, though "stability" is relative with Grid.

What's new:

• BiDi APIs for two-way browser communication
• Improved relative locators
• Modern Grid interface
• Better Chrome DevTools integration

Why Companies Keep Using Selenium

Investment Protection: We have 847 Selenium tests that took 3 years to write. Migrating to Playwright means rewriting everything and convincing management it's worth the cost. Nobody wants to be the guy who suggests throwing away 3 years of work.

Universal Browser Support: Selenium works everywhere - Chrome, Firefox, Safari, even Internet Explorer that some enterprise client refuses to upgrade. Yes, IE testing is still a thing in 2025.

Language Flexibility: Write tests in Java, Python, C#, Ruby, or JavaScript. Teams can use their existing language skills rather than learning JavaScript-only tools.

Mature Community: Stack Overflow has 180k+ Selenium questions because everyone runs into the same problems. That's either reassuring or terrifying, depending on your perspective.

Open Source: Apache 2.0 license means it's free as in beer. The hidden costs come from developer time debugging flaky tests and CI compute time waiting for slow test suites.

Setting up Selenium used to be an absolute nightmare of manual driver downloads and PATH management bullshit. Selenium 4 supposedly fixed most of this with Selenium Manager, but you'll still run into weird issues that make no sense.

Installation: Usually Works, Sometimes Doesn't (Mostly Doesn't on First Try)

Python (easiest path):

pip install selenium

If this fails with permission errors on macOS (it probably will), try:

pip3 install --user selenium

Or if you're using some corporate laptop with locked-down permissions, you might need virtual environments or to beg IT to install it for you.

Java (enterprise choice):
Add this to your pom.xml:

<dependency>
    <groupId>org.seleniumhq.selenium</groupId>
    <artifactId>selenium-java</artifactId>
    <version>4.35.0</version>
</dependency>

JavaScript:

npm install selenium-webdriver

Driver Management: Finally Less Hell (But Still Some Hell)

Selenium Manager is supposed to automatically download ChromeDriver, GeckoDriver, EdgeDriver. This was the biggest fucking pain point for years - every Chrome update would break everyone's tests because the driver versions were mismatched.

It mostly works now, except when it doesn't:

• Corporate proxies block driver downloads (workaround here)
• ARM64 Macs sometimes get x86 drivers and everything falls apart
• Linux containers need specific Chrome/Firefox versions that don't always match what gets downloaded
• Windows with spaces in username paths still breaks things (seriously, Microsoft?)
• Sometimes it just decides to download the wrong driver version for no reason
• Network timeouts during driver download leave you stuck

Your First Test

Here's a basic example that handles common issues:

from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
from selenium.common.exceptions import TimeoutException, StaleElementReferenceException

options = webdriver.ChromeOptions()
options.add_argument("--headless")  # Because you'll run this in Docker
options.add_argument("--no-sandbox")  # Docker needs this
options.add_argument("--disable-dev-shm-usage")  # Prevents crashes

driver = webdriver.Chrome(options=options)

try:
    driver.get("https://example.com")
    
    # Wait for elements to load
    wait = WebDriverWait(driver, 10)
    search_box = wait.until(
        EC.element_to_be_clickable((By.NAME, "q"))
    )
    
    search_box.send_keys("selenium is slow")
    search_box.submit()
    
    # This will randomly fail sometimes
    results = wait.until(
        EC.presence_of_element_located((By.ID, "results"))
    )
    
    print(f"Found {len(results.find_elements(By.CSS_SELECTOR, '.result'))} results")
    
except TimeoutException:
    print("Page took too long to load, probably broken")
    driver.save_screenshot("failed_test.png")
except StaleElementReferenceException:
    print("Element disappeared, welcome to modern web development")
finally:
    driver.quit()  # Always quit to prevent resource leaks

Common Issues You'll Encounter

Chrome Updates Break Everything:
Chrome auto-updates to 118.0.5993.70 and your tests immediately start failing with "session not created" errors. ChromeDriver needs to match Chrome version exactly. Selenium Manager usually handles this, except when your corporate IT blocks the driver download and you're stuck debugging for 3 hours before realizing that's the issue.

Headless vs Headed Differences:
Tests pass in headed mode, fail headless because some CSS hover state isn't triggered or fonts render 2 pixels different. Took down our staging deployment for 2 hours last month because nobody tested the CSS changes in headless. Add --window-size=1920,1080 to your options and pray.

Docker Pain:
M1 Macs are a special kind of hell - you need --platform linux/amd64 or Chrome downloads the wrong architecture and fails with "Exec format error". Learned that after 4 hours of debugging.

## You'll need these in your Dockerfile
RUN apt-get update && apt-get install -y \
    wget gnupg2 ca-certificates \
    && wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | apt-key add - \
    && echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" > /etc/apt/sources.list.d/google-chrome.list \
    && apt-get update && apt-get install -y google-chrome-stable

## Don't forget this or Chrome crashes randomly
ENV DISPLAY=:99

Grid Setup Hell:

Selenium Grid with Docker:

docker run -d -p 4444:4444 --shm-size=2g selenium/standalone-chrome:latest

Until it doesn't because of shared memory limits, container networking, or hub/node version mismatches. Pro tip: --shm-size=2g or Chrome runs out of memory and you get cryptic "unknown error" messages. Found that out at 2am during a prod deployment.

Production Pain Points You'll Hit Later

Page Object Models start simple but become a maintenance nightmare:

class LoginPage:
    def __init__(self, driver):
        self.driver = driver
        self.username = (By.ID, "username")
        self.password = (By.ID, "password")
        
    def login(self, user, pwd):
        self.driver.find_element(*self.username).send_keys(user)
        self.driver.find_element(*self.password).send_keys(pwd)
        self.driver.find_element(By.XPATH, "//button[@type='submit']").click()

Wait Strategy Options:

• Implicit waits apply globally, can conflict with explicit waits (don't use both)
• Explicit waits are generally preferred but verbose as hell
• Fluent waits provide more control but add complexity nobody has time for
• Custom waits for SPAs that load content dynamically (welcome to modern web development)

Error handling patterns:

from selenium.common.exceptions import *

## Common exceptions you'll encounter
try:
    element.click()
excep ElementClickInterceptedException:
    # Something is covering your element
    driver.execute_script("arguments[0].click();", element)
excep StaleElementReferenceException:
    # Element was there, now it's not
    element = driver.find_element(By.ID, "same-id")  # Find it again
    element.click()
excep TimeoutException:
    # Page is slow or broken
    driver.save_screenshot(f"timeout_{int(time.time())}.png")
    raise

CI/CD Differences:

Tests pass locally but fail in CI because:

• Different screen resolution (elements positioned differently)
• Missing fonts make layout shift
• Timing differences (CI is slower, race conditions appear)
• Browser version differences between your Mac and the Ubuntu container
• Environment variables like $HOME have spaces and Windows breaks

The learning curve isn't the API - it's debugging all the shit that breaks randomly in production.