Selenium Automation That Doesn’t Flake: A Practical Pattern for Reliable UI Tests

Pictalingo

·

Selenium Automation That Doesn’t Flake: A Practical Pattern for Reliable UI Tests

Selenium is still one of the most useful tools for end-to-end (E2E) browser automation: verifying critical user flows like login, checkout, or admin actions in the same way a real user would. The catch: Selenium tests can become slow and flaky if you rely on sleeps, brittle selectors, or tests that leak state.

This article shows a hands-on, junior/mid-friendly pattern for writing Selenium tests that are stable and maintainable: clear waits, resilient locators, page objects, and a simple test layout you can scale.

What You’ll Build

  • A clean Selenium test setup in Python
  • Reliable WebDriverWait utilities (no time.sleep())
  • A “Page Object” structure for readable tests
  • Examples: login flow + form submission
  • Debug tips (screenshots, logs, headless mode)

Project Setup

Create a virtual environment and install dependencies:

python -m venv .venv # macOS/Linux source .venv/bin/activate # Windows # .venv\Scripts\activate pip install selenium pytest

Selenium needs a browser driver. The easiest modern approach is Selenium Manager (bundled with Selenium 4.6+), which can auto-manage drivers for Chrome/Edge/Firefox in many environments. You can usually just create webdriver.Chrome() and it will “just work”. If not, install the relevant driver or use your OS package manager.

A Solid Folder Structure

This structure keeps things readable as the suite grows:

tests/ conftest.py test_login.py pages/ base_page.py login_page.py dashboard_page.py utils/ waits.py

1) Create a Browser Fixture (Pytest)

Put this in tests/conftest.py. It launches the browser once per test and cleans up properly.

import os import pytest from selenium import webdriver from selenium.webdriver.chrome.options import Options @pytest.fixture def driver(): options = Options() # Run headless in CI by default if os.getenv("HEADLESS", "1") == "1": options.add_argument("--headless=new") # Useful stability flags (especially in CI containers) options.add_argument("--window-size=1365,900") options.add_argument("--disable-gpu") options.add_argument("--no-sandbox") options.add_argument("--disable-dev-shm-usage") driver = webdriver.Chrome(options=options) driver.implicitly_wait(0) # prefer explicit waits; keep implicit at 0 yield driver driver.quit()

Why not implicit waits? Mixing implicit and explicit waits can produce weird timing behavior. A simple rule: keep implicit at 0 and use explicit waits everywhere you touch the UI.

2) Replace Sleeps with Explicit Wait Utilities

Create utils/waits.py for reusable explicit waits:

from selenium.webdriver.support.ui import WebDriverWait from selenium.webdriver.support import expected_conditions as EC DEFAULT_TIMEOUT = 10 def wait_visible(driver, locator, timeout=DEFAULT_TIMEOUT): return WebDriverWait(driver, timeout).until( EC.visibility_of_element_located(locator) ) def wait_clickable(driver, locator, timeout=DEFAULT_TIMEOUT): return WebDriverWait(driver, timeout).until( EC.element_to_be_clickable(locator) ) def wait_url_contains(driver, fragment, timeout=DEFAULT_TIMEOUT): WebDriverWait(driver, timeout).until(EC.url_contains(fragment)) def wait_invisible(driver, locator, timeout=DEFAULT_TIMEOUT): WebDriverWait(driver, timeout).until( EC.invisibility_of_element_located(locator) )

This is the single biggest “anti-flake” improvement: stop guessing timing and wait for real conditions.

3) Use Page Objects to Keep Tests Clean

Page Objects are simple classes that wrap common actions on a page (fill login form, click submit, read toast messages). This keeps tests readable and reduces duplication.

Create pages/base_page.py:

from selenium.webdriver.common.by import By from utils.waits import wait_visible, wait_clickable class BasePage: def __init__(self, driver, base_url): self.driver = driver self.base_url = base_url.rstrip("/") def open(self, path): url = f"{self.base_url}/{path.lstrip('/')}" self.driver.get(url) def type(self, locator, text): el = wait_visible(self.driver, locator) el.clear() el.send_keys(text) def click(self, locator): el = wait_clickable(self.driver, locator) el.click() def text_of(self, locator): el = wait_visible(self.driver, locator) return el.text.strip()

4) Example: Login Page Object

Create pages/login_page.py. Use stable locators: data-testid is ideal (ask your team to add these attributes if possible).

from selenium.webdriver.common.by import By from pages.base_page import BasePage from utils.waits import wait_url_contains class LoginPage(BasePage): # Prefer data-testid if available EMAIL = (By.CSS_SELECTOR, "[data-testid='email']") PASSWORD = (By.CSS_SELECTOR, "[data-testid='password']") SUBMIT = (By.CSS_SELECTOR, "[data-testid='login-submit']") ERROR = (By.CSS_SELECTOR, "[data-testid='login-error']") def go(self): self.open("/login") def login(self, email, password): self.type(self.EMAIL, email) self.type(self.PASSWORD, password) self.click(self.SUBMIT) def assert_logged_in(self): # adjust to your app (dashboard URL, user avatar, etc.) wait_url_contains(self.driver, "/dashboard") def get_error(self): return self.text_of(self.ERROR)

If your app doesn’t have data-testid, choose selectors that are least likely to change: IDs are decent, semantic attributes are better than brittle CSS chains, and avoid targeting layout classes that designers might rename.

5) Write the Test: Happy Path + Invalid Credentials

Create tests/test_login.py:

import os from pages.login_page import LoginPage BASE_URL = os.getenv("BASE_URL", "http://localhost:3000") def test_login_success(driver): page = LoginPage(driver, BASE_URL) page.go() page.login("[email protected]", "correct-horse-battery-staple") page.assert_logged_in() def test_login_invalid_password(driver): page = LoginPage(driver, BASE_URL) page.go() page.login("[email protected]", "wrong-password") # Example: app shows a visible error message assert "Invalid" in page.get_error()

Run it:

pytest -q

6) Example: Fill and Submit a Form (Avoid Click Interception)

Forms are a great place for flakiness: buttons are disabled until validation, spinners overlay clicks, and auto-complete can shift focus. The cure is the same: wait for the right state.

Create pages/dashboard_page.py as a simple example:

from selenium.webdriver.common.by import By from pages.base_page import BasePage from utils.waits import wait_visible, wait_invisible class DashboardPage(BasePage): NEW_POST = (By.CSS_SELECTOR, "[data-testid='new-post']") TITLE = (By.CSS_SELECTOR, "[data-testid='post-title']") BODY = (By.CSS_SELECTOR, "[data-testid='post-body']") SAVE = (By.CSS_SELECTOR, "[data-testid='post-save']") SPINNER = (By.CSS_SELECTOR, "[data-testid='loading']") TOAST = (By.CSS_SELECTOR, "[data-testid='toast']") def create_post(self, title, body): self.click(self.NEW_POST) self.type(self.TITLE, title) self.type(self.BODY, body) self.click(self.SAVE) # If your app shows a loading overlay/spinner, wait for it to go away wait_invisible(self.driver, self.SPINNER, timeout=15) def toast_message(self): return self.text_of(self.TOAST)

Now a test that logs in, then creates a post:

import os from pages.login_page import LoginPage from pages.dashboard_page import DashboardPage BASE_URL = os.getenv("BASE_URL", "http://localhost:3000") def test_create_post(driver): login = LoginPage(driver, BASE_URL) login.go() login.login("[email protected]", "correct-horse-battery-staple") login.assert_logged_in() dash = DashboardPage(driver, BASE_URL) dash.create_post("Hello Selenium", "This is an automated post.") assert "Saved" in dash.toast_message()

Debugging Like a Pro: Screenshots + Page Source on Failure

When a test fails in CI, you want evidence. You can add a pytest hook to capture screenshots and HTML automatically.

Add this to tests/conftest.py (below the fixture):

import pathlib import datetime import pytest ARTIFACTS_DIR = pathlib.Path("artifacts") @pytest.hookimpl(tryfirst=True, hookwrapper=True) def pytest_runtest_makereport(item, call): outcome = yield report = outcome.get_result() if report.when == "call" and report.failed: driver = item.funcargs.get("driver") if driver: ARTIFACTS_DIR.mkdir(exist_ok=True) ts = datetime.datetime.now().strftime("%Y%m%d_%H%M%S") name = f"{item.name}_{ts}" screenshot_path = ARTIFACTS_DIR / f"{name}.png" html_path = ARTIFACTS_DIR / f"{name}.html" driver.save_screenshot(str(screenshot_path)) html_path.write_text(driver.page_source, encoding="utf-8")

Now failed tests produce artifacts/*.png and artifacts/*.html, which is gold for troubleshooting.

Practical Anti-Flake Checklist

  • Never use time.sleep() unless you’re diagnosing something temporary. Use explicit waits.
  • Prefer stable selectors: data-testid, IDs, or accessible labels. Avoid deep CSS chains.
  • Wait for state, not time: element visible/clickable, URL changed, spinner gone, toast visible.
  • Keep tests independent: don’t rely on previous tests having run; create/cleanup data where possible.
  • Limit scope: UI tests should cover critical flows, not every edge case (that’s better in unit/integration tests).

Run Locally vs CI

Locally, it’s helpful to see the browser. In CI, you usually want headless. With the fixture above, you can control this via environment variables:

# visible browser (local debugging) HEADLESS=0 pytest -q # target a deployed environment BASE_URL="https://staging.example.com" HEADLESS=1 pytest -q

Wrap-Up

If you take only one thing: replace timing guesses with explicit waits and structure your suite with Page Objects. That combination makes Selenium tests readable, scalable, and far less flaky—exactly what junior/mid developers need to ship confidence without fighting the test runner.

Leave a Reply

Your email address will not be published. Required fields are marked *