TestForge
Log in
Medium difficulty~80 min read

Selenium WebDriver

The long-standing, W3C-standard browser automation library — huge ecosystem, every language.

What is Selenium and why use it

Selenium WebDriver automates real browsers via the W3C WebDriver protocol. It is the most widely adopted UI automation tool, with official bindings for Java, Python, C#, JavaScript, and Ruby, and it powers Selenium Grid for large-scale parallel/cross-browser runs.

  • Language-agnostic: pick Java, Python, C#, JS, or Ruby — the API is nearly identical.
  • Standards-based: uses the same W3C WebDriver protocol browsers implement natively.
  • Mature ecosystem: Grid, cloud providers (BrowserStack, Sauce Labs), and countless integrations.
  • Trade-off vs newer tools: no built-in auto-waiting or test runner — you add explicit waits and a runner (pytest, JUnit, TestNG) yourself.

This tutorial uses Python + pytest

Python keeps the examples short. The Java/C# APIs mirror these calls almost one-to-one (driver.find_element becomes driver.findElement, etc.). Target TestForge at http://localhost:3100.

Prerequisites

  • Python 3.9+ (python --version). Java users: JDK 17+ and Maven/Gradle instead.
  • Google Chrome (or Firefox/Edge) installed.
  • The TestForge app running at http://localhost:3100.
  • Selenium 4.6+ — it ships Selenium Manager, which downloads the right driver automatically (no manual chromedriver setup).

Installation and setup

bash
mkdir testforge-selenium && cd testforge-selenium
python -m venv .venv
# Windows: .venv\Scripts\activate   |   macOS/Linux: source .venv/bin/activate
pip install selenium pytest

No more manual driver downloads

Since Selenium 4.6, Selenium Manager resolves and downloads the matching browser driver automatically. If you are on an older version, upgrade — it removes the single most common source of setup pain.

Your first test

test_catalog.py
from selenium import webdriver
from selenium.webdriver.common.by import By


def test_catalog_has_heading():
    driver = webdriver.Chrome()
    try:
        driver.get('http://localhost:3100/catalog')
        heading = driver.find_element(By.XPATH, "//h1[normalize-space()='Catalog']")
        assert heading.is_displayed()
    finally:
        driver.quit()
bash
pytest -v test_catalog.py

Always quit the driver

A leaked driver keeps a browser process alive. Use try/finally, or better, a pytest fixture (next section) so teardown always runs.

A reusable driver fixture

Put driver setup/teardown in a pytest fixture so every test gets a fresh, always-closed browser.

conftest.py
import pytest
from selenium import webdriver


@pytest.fixture
def driver():
    options = webdriver.ChromeOptions()
    # options.add_argument('--headless=new')  # enable in CI
    drv = webdriver.Chrome(options=options)
    drv.implicitly_wait(0)  # prefer explicit waits (see below)
    yield drv
    drv.quit()

Locators — the By strategies

Selenium finds elements with find_element(By.<strategy>, value). Prefer stable strategies: ID, name, or a data-testid via CSS, over deep XPath tied to layout.

python
from selenium.webdriver.common.by import By

driver.find_element(By.ID, 'search')
driver.find_element(By.NAME, 'email')
driver.find_element(By.CSS_SELECTOR, "[data-testid='cart-count']")
driver.find_element(By.LINK_TEXT, 'Catalog')
driver.find_element(By.XPATH, "//button[normalize-space()='Add to cart']")
# find_elements (plural) returns a list — empty if none, never throws
cards = driver.find_elements(By.CSS_SELECTOR, '.card')
  • Priority: ID > name > CSS selector > XPath. Avoid absolute XPath like /html/body/div[2].
  • CSS is usually shorter and faster than XPath for the same target.
  • Use XPath when you need text matching or axis navigation (e.g., parent/following-sibling).

Waiting: explicit waits (the critical skill)

Selenium does NOT auto-wait for elements to be interactable. The number-one cause of flaky Selenium tests is acting before the element is ready. The fix is WebDriverWait with expected_conditions — never time.sleep().

python
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.common.by import By

wait = WebDriverWait(driver, 10)
# Wait until clickable, then click
btn = wait.until(EC.element_to_be_clickable((By.XPATH, "//button[normalize-space()='Log in']")))
btn.click()
# Wait for text to appear
wait.until(EC.text_to_be_present_in_element((By.CSS_SELECTOR, "[data-testid='cart-count']"), '1'))

Implicit vs explicit waits — do not mix them

Setting a global implicitly_wait AND using WebDriverWait can compound unpredictably. Pick explicit waits and leave implicit at 0.

Common tasks: login and forms

test_login.py
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC


def test_user_can_log_in(driver):
    driver.get('http://localhost:3100/login')
    wait = WebDriverWait(driver, 10)

    driver.find_element(By.ID, 'email').send_keys('customer@testforge.dev')
    driver.find_element(By.ID, 'password').send_keys('Password123!')
    driver.find_element(By.XPATH, "//button[normalize-space()='Log in']").click()

    # Account email appears in the header once logged in
    wait.until(EC.visibility_of_element_located(
        (By.XPATH, "//*[contains(text(),'customer@testforge.dev')]")))
    assert 'localhost:3100' in driver.current_url

For dropdowns use the Select helper; for keyboard/mouse gestures use ActionChains.

python
from selenium.webdriver.support.ui import Select
from selenium.webdriver.common.action_chains import ActionChains

Select(driver.find_element(By.ID, 'statusFilter')).select_by_visible_text('paid')
ActionChains(driver).move_to_element(menu).click(item).perform()

The Page Object Model

As suites grow, put locators and actions for each page into a class. Tests read as business steps; if the UI changes, you update one place.

pages/login_page.py
from selenium.webdriver.common.by import By


class LoginPage:
    EMAIL = (By.ID, 'email')
    PASSWORD = (By.ID, 'password')
    SUBMIT = (By.XPATH, "//button[normalize-space()='Log in']")

    def __init__(self, driver):
        self.driver = driver

    def load(self):
        self.driver.get('http://localhost:3100/login')
        return self

    def login(self, email, password):
        self.driver.find_element(*self.EMAIL).send_keys(email)
        self.driver.find_element(*self.PASSWORD).send_keys(password)
        self.driver.find_element(*self.SUBMIT).click()

Cross-browser, Grid, and CI

  • Headless in CI: options.add_argument("--headless=new") and "--no-sandbox" on Linux runners.
  • Selenium Grid: run a hub + browser nodes (easiest via the official Docker images) and point a RemoteWebDriver at it to parallelize across machines/browsers.
  • Cloud grids (BrowserStack, Sauce Labs) expose a Remote URL you pass to webdriver.Remote(command_executor=..., options=...).
.github/workflows/selenium.yml
name: selenium
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - run: pip install selenium pytest
      - run: pytest -v

Best practices

  • Explicit waits everywhere; ban time.sleep() in reviews.
  • Stable locators (ID/name/data-testid) over layout-coupled XPath.
  • One assertion focus per test; keep tests independent and self-provisioning.
  • Page Object Model for reuse; keep assertions in the test, not the page object.
  • Always quit the driver via a fixture so teardown is guaranteed.
  • Run headless + parallel in CI; capture a screenshot on failure for triage.

Wait strategies: implicit, explicit, and fluent

Selenium has three wait mechanisms, and choosing the right one — and never combining them carelessly — is the single biggest lever on suite reliability. TestForge at http://localhost:3100 is a client-rendered Next.js app: elements mount, hydrate, and re-render asynchronously, so acting on a raw find_element the instant a page loads is a coin flip.

Implicit wait

An implicit wait is a single global setting that tells the driver to poll the DOM for up to N seconds whenever find_element cannot immediately locate an element. It is convenient but blunt: it only waits for presence in the DOM, not for visibility or clickability, and it applies to every lookup whether you want it to or not.

python
# Set once, applies to every find_element for the driver's lifetime
driver.implicitly_wait(5)  # seconds

# find_element now polls for up to 5s before raising NoSuchElementException.
# But it will NOT wait for the element to be visible or enabled — only present.

Explicit wait (WebDriverWait + expected_conditions)

An explicit wait targets one specific condition at one specific point in the test: wait until this button is clickable, until this toast is visible, until this element goes stale. It is the precise, condition-driven tool you should reach for by default.

python
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.common.by import By

wait = WebDriverWait(driver, 10)

# Wait for the login button to be clickable, not merely present
login = wait.until(EC.element_to_be_clickable(
    (By.XPATH, "//button[normalize-space()='Log in']")))
login.click()

# Wait for the cart badge to actually show a count of 1 after add-to-cart
wait.until(EC.text_to_be_present_in_element(
    (By.CSS_SELECTOR, "[data-testid='cart-count']"), '1'))

Fluent wait

A fluent wait is an explicit wait with an explicitly configured polling interval and a set of exceptions to ignore while polling. In Python, WebDriverWait takes poll_frequency and ignored_exceptions arguments, so it is itself the fluent-wait API; in Java it is the dedicated FluentWait class. Use it when the default 500ms poll is wrong for the case, or when you must swallow a transient exception (like StaleElementReferenceException) while a component re-renders.

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

# Poll every 250ms for up to 15s, ignoring stale-element churn during hydration
fluent = WebDriverWait(
    driver,
    timeout=15,
    poll_frequency=0.25,
    ignored_exceptions=[StaleElementReferenceException],
)
total = fluent.until(EC.visibility_of_element_located(
    (By.CSS_SELECTOR, "[data-testid='order-total']")))

Never mix implicit and explicit waits

When an implicit wait is set and a WebDriverWait condition polls, the two timeouts compound in ways that are driver- and version-dependent: a 10s explicit wait can silently take 10s per poll, blowing your real timeout out to minutes. The safe rule is: set implicitly_wait(0) and drive every wait explicitly. Pick one model and stick to it.

Ban Thread.sleep / time.sleep

A fixed sleep is either too short (still flaky) or too long (slow suite) — it can never be both right. It hardcodes an assumption about timing that breaks the moment the environment changes. Replace every sleep with an explicit wait on the actual condition you are waiting for.

Structuring suites with the Page Object Model

The Page Object Model (POM) encapsulates the locators and interactions for a page or component behind a class with intent-revealing methods. Tests then read as business steps — login, add_to_cart, checkout — while every selector lives in exactly one place. When TestForge changes its login markup, you edit LoginPage once instead of chasing the same XPath through fifty tests.

  • One class per page or major component; locators are class-level constants, actions are methods.
  • Methods return a page object — the same one for an in-place action, or the next page for a navigation — so tests can chain fluently.
  • Keep assertions OUT of page objects. A page object exposes state (getters, is_displayed); the test asserts on it. This keeps pages reusable across tests with different expectations.
  • No WebDriverWait sprinkled through tests — waits belong inside the page methods, next to the action that needs them.
pages/login_page.py
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC


class LoginPage:
    URL = 'http://localhost:3100/login'
    EMAIL = (By.ID, 'email')
    PASSWORD = (By.ID, 'password')
    SUBMIT = (By.XPATH, "//button[normalize-space()='Log in']")
    ERROR = (By.CSS_SELECTOR, "[data-testid='login-error']")

    def __init__(self, driver):
        self.driver = driver
        self.wait = WebDriverWait(driver, 10)

    def load(self) -> 'LoginPage':
        self.driver.get(self.URL)
        self.wait.until(EC.visibility_of_element_located(self.EMAIL))
        return self

    def login(self, email: str, password: str) -> None:
        self.driver.find_element(*self.EMAIL).send_keys(email)
        self.driver.find_element(*self.PASSWORD).send_keys(password)
        self.wait.until(EC.element_to_be_clickable(self.SUBMIT)).click()

    def error_message(self) -> str:
        return self.wait.until(
            EC.visibility_of_element_located(self.ERROR)).text
test_login_pom.py
from pages.login_page import LoginPage


def test_valid_login(driver):
    page = LoginPage(driver).load()
    page.login('customer@testforge.dev', 'Password123!')
    assert 'localhost:3100' in driver.current_url


def test_invalid_login_shows_error(driver):
    page = LoginPage(driver).load()
    page.login('customer@testforge.dev', 'wrong-password')
    assert 'Invalid' in page.error_message()

PageFactory is a Java pattern — not in Python

In Java, PageFactory + the @FindBy annotation lazily inject WebElements: you declare @FindBy(id = "email") private WebElement email; and call PageFactory.initElements(driver, this) in the constructor. Python has no PageFactory; the idiomatic equivalent is the class-level locator tuples above, resolved with find_element(*self.EMAIL) at call time. The lazy-lookup behavior is the same; only the syntax differs.

Selenium Grid and parallel execution

Selenium Grid lets you run tests on browsers hosted elsewhere — on other machines, in Docker, or in the cloud — through a single endpoint. Your test talks to a RemoteWebDriver instead of a local driver; the Grid routes each session to a node that can satisfy the requested browser and version. This is how you run Chrome, Firefox, and Edge in parallel to cut a 40-minute serial run down to a few minutes.

Grid 4 architecture

  • Grid 4 can run as a single all-in-one process (standalone) or split into Router, Distributor, Session Map, Session Queue, and Nodes for scale.
  • The classic hub-and-node model still works: one hub receives session requests, many nodes register and expose browser slots.
  • Your test connects to the Grid URL (default http://localhost:4444) with webdriver.Remote and options that name the target browser — the Grid picks a matching node.
docker-compose.grid.yml
services:
  selenium-hub:
    image: selenium/hub:4
    ports:
      - '4442:4442'
      - '4443:4443'
      - '4444:4444'
  chrome:
    image: selenium/node-chrome:4
    depends_on: [selenium-hub]
    environment:
      - SE_EVENT_BUS_HOST=selenium-hub
      - SE_EVENT_BUS_PUBLISH_PORT=4442
      - SE_EVENT_BUS_SUBSCRIBE_PORT=4443
      - SE_NODE_MAX_SESSIONS=4
  firefox:
    image: selenium/node-firefox:4
    depends_on: [selenium-hub]
    environment:
      - SE_EVENT_BUS_HOST=selenium-hub
      - SE_EVENT_BUS_PUBLISH_PORT=4442
      - SE_EVENT_BUS_SUBSCRIBE_PORT=4443
      - SE_NODE_MAX_SESSIONS=4

Note that on Linux Grid nodes you reach the TestForge app on the host, not on localhost inside the container. Point the browser at http://host.docker.internal:3100 (or the host IP) so the node can actually load the app under test.

conftest.py
import pytest
from selenium import webdriver

GRID_URL = 'http://localhost:4444'


@pytest.fixture(params=['chrome', 'firefox'])
def driver(request):
    if request.param == 'chrome':
        options = webdriver.ChromeOptions()
    else:
        options = webdriver.FirefoxOptions()
    drv = webdriver.Remote(command_executor=GRID_URL, options=options)
    yield drv
    drv.quit()

Parametrizing the fixture over browsers runs every test on each browser. Combine that with pytest-xdist to execute across the Grid in parallel — the Grid load-balances sessions across nodes up to SE_NODE_MAX_SESSIONS.

bash
pip install pytest-xdist
# -n 4 spins up 4 workers; the Grid distributes their sessions across nodes
pytest -n 4 -v

Same test, local or remote

Because RemoteWebDriver implements the same API as a local driver, your test code and page objects are identical whether you run against a local Chrome or a 50-node Grid. Only the fixture that constructs the driver changes — which is exactly why keeping driver creation in conftest pays off.

Interview questions & answers

Walk me through the difference between implicit, explicit, and fluent waits — and when would you use each?

An implicit wait is a single global timeout that makes every find_element poll the DOM for presence before failing; it is convenient but blunt and only checks presence, not visibility or clickability. An explicit wait (WebDriverWait + expected_conditions) targets one specific condition at one point in the test, like element_to_be_clickable, and is what I reach for by default. A fluent wait is an explicit wait with a configurable poll interval and a set of exceptions to ignore while polling — I use it when the default 500ms cadence is wrong or when I need to swallow transient StaleElementReferenceExceptions during a re-render.

What causes a StaleElementReferenceException, and how do you fix it properly?

It happens when you hold a WebElement reference but the DOM node it pointed to has been detached or replaced — typically after a re-render, navigation, or an AJAX update swaps the element out. The reference is now stale even though a visually identical element exists. The correct fix is to re-locate the element right before you use it rather than caching it across an action that mutates the DOM; a fluent wait that ignores StaleElementReferenceException while re-finding is the robust pattern. Blindly retrying without understanding why the DOM changed just hides a race condition.

Explain the W3C WebDriver protocol and how Selenium talks to a browser.

Selenium 4 speaks the W3C WebDriver protocol, a standardized HTTP/JSON contract that browsers implement natively through their drivers (chromedriver, geckodriver, etc.). Your language binding sends commands as HTTP requests to the driver, which translates them into browser-native operations and returns JSON responses. Standardizing on W3C replaced the older JSON Wire Protocol and removed the encoding mismatches that used to cause subtle cross-browser differences, so the same script behaves consistently across Chrome, Firefox, and Edge.

What is Selenium Grid and what problem does it solve?

Selenium Grid lets you run tests on browsers hosted on other machines, in Docker, or in the cloud through a single endpoint, so you can execute cross-browser and in parallel instead of serially on one box. Your test connects to a RemoteWebDriver pointed at the Grid, which routes each session to a node capable of the requested browser and version. Grid 4 can run standalone or split into Router, Distributor, Session Queue, and Nodes for scale. It is the standard way to cut a long serial suite down to minutes and to cover browsers your CI runner does not have installed locally.

How do you structure a maintainable UI suite, and what is PageFactory?

I use the Page Object Model: one class per page or major component that owns its locators and exposes intent-revealing action methods, so tests read as business steps and every selector lives in one place. Assertions stay in the tests, not the page objects, which keeps pages reusable. PageFactory is a Java-specific helper that lazily injects WebElements declared with @FindBy annotations via PageFactory.initElements; Python has no PageFactory, so the idiomatic equivalent is class-level locator tuples resolved with find_element at call time — same lazy-lookup behavior, different syntax.

What is the difference in behavior between findElement and findElements?

findElement returns the first matching element and throws a NoSuchElementException if none is found, so it is an assertion of existence in itself. findElements returns a list of all matches and returns an empty list — never throwing — when nothing matches. That difference makes findElements the right tool for presence checks: if you want to assert an element is absent, or branch on whether zero or many exist, use findElements and check the list length rather than catching an exception.

How do you handle JavaScript alerts, iframes, and multiple browser windows?

Native browser alerts are not in the DOM, so you switch to them with driver.switch_to.alert and call accept, dismiss, or send_keys. For an iframe you must switch_to.frame before you can find elements inside it, and switch_to.default_content to get back out — elements in a frame are invisible to the driver until you do. For multiple windows or tabs you capture window_handles, switch_to.window(handle) to move focus, act, and switch back. Forgetting to switch context is a classic cause of NoSuchElement errors that look mysterious because the element is clearly on screen.

When would you reach for the Actions class instead of a plain click or send_keys?

The Actions class (ActionChains in Python) builds a sequence of low-level input events for interactions that a simple click or send_keys cannot express: hover to reveal a menu, drag-and-drop, right-click context menus, click-and-hold, double-click, or key combinations like Ctrl+click. You chain the steps and call perform() to dispatch them as one gesture. It is the tool for anything that depends on precise pointer movement or modifier keys, which the element-level convenience methods do not cover.

How does headless execution work, and what caveats come with it?

Headless mode runs the real browser engine without rendering a visible window, which is faster and required on CI runners that have no display. You enable it with a browser option — for Chrome, options.add_argument("--headless=new") — and on Linux you usually also add "--no-sandbox" and a fixed "--window-size" because the default viewport differs from a desktop. The main caveat is that headless can expose or hide layout and timing bugs that only appear at a specific viewport, so I set an explicit window size and, when a test fails only headless, reproduce it headed to see what actually rendered.

A test intermittently throws NoSuchElementException. Is adding a wait always the fix?

Not always — the exception means the element was not in the DOM at lookup time, and a wait only helps if the real cause is timing, where the element simply had not appeared yet. If instead the locator is wrong, the element is inside an iframe you have not switched into, it is on a different window handle, or a prior step failed so the page never reached the expected state, no amount of waiting will find it. So I first confirm the element truly does appear given enough time; if it does, an explicit wait is correct, and if it does not, I fix the locator, the context switch, or the upstream step rather than masking the real bug with a longer timeout.

Where to go next

  • Official docs: selenium.dev/documentation
  • Learn WebDriverWait + expected_conditions deeply — it is 80% of Selenium stability.
  • Explore Selenium Grid with Docker for parallel cross-browser runs.
  • Practice: build LoginPage, CatalogPage, and CartPage objects and automate add-to-cart end to end against TestForge.