Implementation:SeleniumHQ Selenium Python Conftest

Knowledge Sources	SeleniumHQ_Selenium
Domains	WebDriver, Python_Bindings, Testing
Last Updated	2026-02-12 00:00 GMT

Overview

The Python conftest.py provides pytest configuration, command-line options, fixtures, and driver lifecycle management for the Selenium Python binding test suite.

Description

This file is the central pytest configuration module for Selenium's Python test suite. It provides:

Command-Line Options: Registers custom pytest options via pytest_addoption:

• --driver: Select which browser drivers to test against (chrome, edge, firefox, ie, safari, webkitgtk, wpewebkit).
• --browser-binary: Custom browser executable path.
• --driver-binary: Custom driver service executable path.
• --browser-args: Additional browser arguments.
• --headless: Run tests in headless mode.
• --use-lan-ip: Use LAN IP instead of localhost for the test server.
• --bidi: Enable WebDriver BiDi support.
• --remote: Run tests against a remote Selenium Grid server.

Driver Management: The Driver class encapsulates driver creation and configuration. It maps driver names to WebDriver classes and options classes using SupportedDrivers, SupportedOptions, and SupportedBidiDrivers dataclasses. It handles browser-specific configuration like headless flags, dev-shm usage, Wayland workarounds for Firefox on Linux, and BiDi WebSocket URL enablement.

Fixtures:

• driver: Session-scoped driver instance with lazy initialization, platform validation, xfail marker support, BiDi window validation, and automatic cleanup.
• pages: Helper for constructing and loading test page URLs from the web server.
• server: Session-scoped Selenium Grid server (only when --remote is used).
• webserver: Session-scoped simple HTTP web server for test fixtures.
• clean_driver, clean_service, clean_options: Fixtures providing fresh, unconfigured driver/service/options instances.
• firefox_options, chromium_options: Browser-specific options fixtures.
• proxy_server: Creates temporary HTTP proxy servers for proxy-related tests.

Test Collection: pytest_ignore_collect filters test directories based on the selected driver, and pytest_generate_tests parametrizes tests when multiple drivers are specified.

Rich Tracebacks: The pytest_runtest_makereport hook uses the rich library to render filtered, color-formatted tracebacks on test failure, excluding pytest internals.

Usage

This file is automatically loaded by pytest when running tests from the py/ directory. It requires no explicit import. Tests rely on the fixtures it defines (especially driver, pages, and webserver).

Code Reference

Source Location

• Repository: SeleniumHQ_Selenium
• File: py/conftest.py

Signature

# Pytest hooks
def pytest_addoption(parser)
def pytest_ignore_collect(collection_path, config)
def pytest_generate_tests(metafunc)
def pytest_runtest_makereport(item, call)
def pytest_exception_interact(node, call, report)

# Driver management class
class Driver:
    def __init__(self, driver_class, request)
    @classmethod
    def clean_options(cls, driver_class, request)
    @property
    def driver(self)
    def stop_driver(self)
    def _initialize_driver(self)

# Dataclass registries
@dataclass
class SupportedDrivers(ContainerProtocol)

@dataclass
class SupportedOptions(ContainerProtocol)

@dataclass
class SupportedBidiDrivers(ContainerProtocol)

# Key fixtures
@pytest.fixture
def driver(request, server)

@pytest.fixture
def pages(driver, webserver)

@pytest.fixture(autouse=True, scope="session")
def server(request)

@pytest.fixture(autouse=True, scope="session")
def webserver(request)

@pytest.fixture
def clean_driver(request)

@pytest.fixture
def clean_options(request)

@pytest.fixture
def proxy_server()

Import

# conftest.py is auto-discovered by pytest; no explicit import needed.
# Fixtures are available by name in test function signatures:
def test_example(driver, pages, webserver):
    pass

I/O Contract

Pytest Command-Line Options

Option	Type	Default	Description
--driver	Choice (repeatable)	All drivers	Browser driver(s) to test against
--browser-binary	String	None	Path to browser binary
--driver-binary	String	None	Path to driver service executable
--browser-args	String	None	Space-separated browser arguments
--headless	Flag	False	Enable headless mode
--use-lan-ip	Flag	False	Bind test server to LAN IP
--bidi	Flag	False	Enable BiDi protocol support
--remote	Flag	False	Test against a remote Grid server

Key Fixtures

Fixture	Scope	Yields	Description
driver	function	WebDriver instance	Lazily-initialized browser driver with platform/marker logic
pages	function	Pages helper	URL builder and page loader tied to webserver
server	session	Server or None	Remote Grid server (only with --remote)
webserver	session	SimpleWebServer	Local HTTP server serving test fixture HTML pages
clean_driver	function	WebDriver class	Fresh driver class reference for custom instantiation
proxy_server	function	factory function	Creates temporary HTTP proxy servers

Usage Examples

# Run Python Selenium tests for Chrome in headless mode:
bazel test //py:test-chrome --test_arg=--driver=chrome --test_arg=--headless

# Run tests against a remote Grid:
pytest py/test/ --driver=chrome --remote

# Run Firefox tests with a custom binary:
pytest py/test/ --driver=firefox --browser-binary=/usr/bin/firefox-nightly

# Example test using conftest fixtures:
def test_navigate_to_page(driver, pages):
    pages.load("simpleTest.html")
    assert "simpleTest" in driver.title

# Example test with xfail marker:
import pytest

@pytest.mark.xfail_firefox(reason="Known Firefox rendering issue")
def test_css_feature(driver, pages):
    pages.load("cssPage.html")
    element = driver.find_element("id", "target")
    assert element.is_displayed()

Related Pages

• SeleniumHQ_Selenium_Python_Pyproject - Python package and test tool configuration
• SeleniumHQ_Selenium_WebDriver_Navigation_And_Element_Interaction - WebDriver navigation API
• SeleniumHQ_Selenium_ChromiumOptions_Configuration - Chromium options configuration
• SeleniumHQ_Selenium_Bazel_Test_With_Filters - Bazel test filtering