Selenium × pytest Practical Guide | fixture · parametrize · conftest.py · mark

This guide covers the four core features of Selenium × pytest——fixture, parametrize, conftest.py, and mark——with production-ready sample code.

Once you master pytest fixtures, parametrize, and marks, you can evolve your Selenium tests from one-off scripts into a maintainable test suite.

Every pattern in this article is taken directly from production projects and ready to copy-paste.

👉 Prerequisites: This article assumes Selenium × Python is already installed. If not, start with the setup guide first.

There’s a gap between “tests that run” and “tests a team can maintain and run in CI.” Closing that gap is exactly what pytest fixtures, parametrize, and marks are for.

Selenium × pytest Project Structure

Folder Layout

Start by understanding the folder structure and the role of each file.

selenium-project/
├── venv/
├── tests/
│   ├── conftest.py          # WebDriver fixture & shared config
│   ├── test_login.py        # Login tests
│   ├── test_search.py       # Search tests
│   └── test_register.py     # Registration tests
├── pages/
│   └── login_page.py        # Page Object (covered in a separate article)
├── requirements.txt
└── pytest.ini

Role of Each File

STEP 1: What Is a pytest fixture? Centralizing Selenium WebDriver with conftest.py

Defining the WebDriver fixture in conftest.py makes it available to every test file automatically.

# tests/conftest.py
import pytest
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.webdriver.chrome.service import Service
from webdriver_manager.chrome import ChromeDriverManager

@pytest.fixture(scope="function")
def driver():
    """Fixture that launches and quits Chrome for each test"""
    options = webdriver.ChromeOptions()
    # options.add_argument("--headless")  # Turn ON for CI/CD
    options.add_argument("--no-sandbox")            # For Linux/CI environments
    options.add_argument("--disable-dev-shm-usage") # For Linux/CI environments
    options.add_argument("--window-size=1920,1080")

    service = Service(ChromeDriverManager().install())
    driver = webdriver.Chrome(service=service, options=options)
    driver.implicitly_wait(10)  # Basic wait — use WebDriverWait as the primary approach

    yield driver

    try:
        driver.quit()
    except Exception:
        # Protects teardown even if session was already disconnected
        pass


@pytest.fixture(scope="function")
def logged_in_driver(driver):
    """Fixture for tests that require a logged-in session.
    For tests that don't need login, use the driver fixture directly."""
    # ※ example-app.com is a sample URL — replace with your actual URL
    driver.get("https://example-app.com/login")
    driver.find_element(By.ID, "username").send_keys("test_user")
    driver.find_element(By.ID, "password").send_keys("test_pass")
    driver.find_element(By.ID, "login-btn").click()

    # Wait for login to complete (without this, CI runs become flaky)
    WebDriverWait(driver, 10).until(
        EC.url_contains("/dashboard")
    )

    yield driver
    # driver.quit() is handled by the driver fixture — no teardown needed here

# Use logged_in_driver only when login is required
def test_dashboard_title(logged_in_driver):
    assert "Dashboard" in logged_in_driver.title

# Use driver directly for tests that don't need login
def test_top_page_title(driver):
    driver.get("https://example-app.com")
    assert "Home" in driver.title

STEP 2: Writing Selenium Tests — Happy Path and Error Cases

Accepting base_url as a fixture argument keeps URLs in one place — no hardcoding, easy to swap per environment.

# tests/test_login.py
# ※ The same imports are used throughout the code below
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

# ── Happy path ──────────────────────────────────────
def test_login_success(driver, base_url):
    """Happy path: correct credentials log the user in"""
    driver.get(f"{base_url}/login")
    driver.find_element(By.ID, "username").send_keys("valid_user")
    driver.find_element(By.ID, "password").send_keys("valid_pass")
    driver.find_element(By.ID, "login-btn").click()

    WebDriverWait(driver, 10).until(EC.url_contains("/dashboard"))
    assert "/dashboard" in driver.current_url

# ── Error cases ─────────────────────────────────────
def test_login_failure_wrong_password(driver, base_url):
    """Error case: wrong password shows an error message"""
    driver.get(f"{base_url}/login")
    driver.find_element(By.ID, "username").send_keys("valid_user")
    driver.find_element(By.ID, "password").send_keys("wrong_pass")
    driver.find_element(By.ID, "login-btn").click()

    error_msg = WebDriverWait(driver, 10).until(
        EC.visibility_of_element_located(
            (By.CSS_SELECTOR, "[data-testid='login-error']")  # data-testid preferred
        )
    )
    assert "Invalid password" in error_msg.text

def test_login_failure_empty_fields(driver, base_url):
    """Error case: submitting empty fields shows a validation error"""
    driver.get(f"{base_url}/login")
    driver.find_element(By.ID, "login-btn").click()

    error = WebDriverWait(driver, 10).until(
        EC.visibility_of_element_located((By.CLASS_NAME, "validation-error"))
    )
    assert error.is_displayed()

STEP 3: pytest parametrize — Data-Driven Testing

@pytest.mark.parametrize runs the same test logic against multiple inputs — the go-to tool when you have many error case patterns to cover.

# tests/test_login.py (continued)
import pytest

INVALID_LOGIN_CASES = [
    ("", "valid_pass", "Please enter your username"),
    ("valid_user", "", "Please enter your password"),
    ("wrong_user", "valid_pass", "Authentication failed"),
    ("valid_user", "wrong_pass", "Invalid password"),
    ("a" * 256, "valid_pass", "Input is too long"),
]

@pytest.mark.parametrize("username, password, expected_error", INVALID_LOGIN_CASES)
def test_login_validation(driver, base_url, username, password, expected_error):
    """parametrize: runs all error cases with a single test function"""
    driver.get(f"{base_url}/login")
    driver.find_element(By.ID, "username").send_keys(username)
    driver.find_element(By.ID, "password").send_keys(password)
    driver.find_element(By.ID, "login-btn").click()

    error_msg = WebDriverWait(driver, 10).until(
        EC.visibility_of_element_located((By.CLASS_NAME, "error-message"))
    )
    assert expected_error in error_msg.text

Sample output

pytest tests/test_login.py -v

collected 8 items

test_login.py::test_login_success                                           PASSED
test_login.py::test_login_failure_wrong_password                            PASSED
test_login.py::test_login_failure_empty_fields                              PASSED
test_login.py::test_login_validation[-valid_pass-Please enter your username] PASSED
test_login.py::test_login_validation[valid_user--Please enter your password] PASSED
test_login.py::test_login_validation[wrong_user-valid_pass-Auth failed]     PASSED
test_login.py::test_login_validation[valid_user-wrong_pass-Invalid password] PASSED
test_login.py::test_login_validation[aaaa…-valid_pass-Input is too long]    PASSED

========================== 8 passed in 18.34s ==========================

STEP 4: pytest mark — Classifying and Selecting Tests

@pytest.mark tags tests so you can run only a specific group — essential for CI/CD pipelines.

Register custom marks in pytest.ini

[pytest]
testpaths = tests
addopts = -v
markers =
    smoke: smoke tests (highest priority — run every time)
    regression: regression tests (run before releases)
    slow: tests that take a long time

Tag and run by mark

@pytest.mark.smoke
def test_login_success(driver, base_url): ...

@pytest.mark.regression
def test_login_failure_wrong_password(driver, base_url): ...

@pytest.mark.slow
@pytest.mark.regression
def test_login_session_timeout(driver, base_url): ...

# Run only smoke (post-deploy)
pytest -m smoke

# Skip slow tests
pytest -m "not slow"

# Only tests tagged with BOTH smoke and regression
pytest -m "smoke and regression"

STEP 5: Advanced fixture Patterns (Setup and Teardown)

# tests/conftest.py (additions)
import pytest

@pytest.fixture(scope="function")
def go_to_login(driver):
    driver.get("https://example-app.com/login")
    yield driver
    import os, re, time
    os.makedirs("screenshots", exist_ok=True)
    # ※ In production use pytest_runtest_makereport to save on failure only
    driver.save_screenshot(f"screenshots/{int(time.time())}.png")


@pytest.fixture(scope="session")
def base_url():
    """Base URL as a fixture — replaces BASE_URL constants entirely.
    ※ Sample URL — replace with your actual URL."""
    return "https://example-app.com"

import os, re, pytest

@pytest.hookimpl(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:
            os.makedirs("screenshots", exist_ok=True)
            # Strip Windows-forbidden characters (\ / * ? : " < > |)
            safe_name = re.sub(r'[\\/*?:"<>|]', "_", item.name)
            driver.save_screenshot(f"screenshots/{safe_name}.png")

STEP 6: Complete Example — Registration Form Tests

# tests/test_register.py
import pytest
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

# ※ In real projects, reusing the same email causes duplicate errors
# Use f"test_{int(time.time())}@example.com" for unique emails per run
VALID_USER = {
    "name": "Test User",
    "email": "test@example.com",
    "password": "SecurePass123!",
}

VALIDATION_CASES = [
    ("name", "", "Please enter your name"),
    ("email", "not-an-email", "Please enter a valid email address"),
    ("email", "", "Please enter your email address"),
    ("password", "short", "Password must be at least 8 characters"),
]

@pytest.fixture
def register_page(driver, base_url):
    """Navigate to registration page (URL unified via base_url fixture)"""
    driver.get(f"{base_url}/register")
    yield driver


@pytest.mark.smoke
def test_register_success(register_page):
    d = register_page
    d.find_element(By.ID, "name").send_keys(VALID_USER["name"])
    d.find_element(By.ID, "email").send_keys(VALID_USER["email"])
    d.find_element(By.ID, "password").send_keys(VALID_USER["password"])
    d.find_element(By.ID, "submit-btn").click()

    success = WebDriverWait(d, 10).until(
        EC.visibility_of_element_located((By.CLASS_NAME, "success-message"))
    )
    assert "Registration complete" in success.text


@pytest.mark.regression
@pytest.mark.parametrize("field, value, expected_error", VALIDATION_CASES)
def test_register_validation(register_page, field, value, expected_error):
    d = register_page
    d.find_element(By.ID, "name").send_keys(VALID_USER["name"])
    d.find_element(By.ID, "email").send_keys(VALID_USER["email"])
    d.find_element(By.ID, "password").send_keys(VALID_USER["password"])

    target = d.find_element(By.ID, field)
    target.clear()
    target.send_keys(value)
    d.find_element(By.ID, "submit-btn").click()

    error = WebDriverWait(d, 10).until(
        # By.ID targets the specific field's error — more precise than By.CLASS_NAME
        EC.visibility_of_element_located((By.ID, f"{field}-error"))
    )
    assert expected_error in error.text

⚠️ 7 Common Pitfalls in Selenium × pytest

tests/
├── conftest.py   ← correct (directly inside tests/)
└── test_login.py

[pytest]
markers =
    smoke: smoke tests
    regression: regression tests

# NG
cd tests && pytest

# OK — always run from the project root
cd selenium-project
pytest

FAQ

Work through this article’s structure and you’ll have a test suite where design and implementation are clearly separated and easy to maintain.

📋 Summary

Start by extracting the data from one existing test into a parametrize list. That single change separates “test design” from “test implementation” — and makes the whole test suite easier to read and maintain.