Build a Complete Selenium Framework Structure

Selenium 18 min min read Updated: Nov 16, 2026 Advanced
Build a Complete Selenium Framework Structure
Advanced Topic 4 of 5

The Layout

text selenium-framework/ config/ config.json pages/ base_page.py login_page.py inventory_page.py cart_page.py components/header.py tests/ conftest.py # optional test-folder fixtures test_login.py test_inventory.py test_checkout.py utils/ config.py driver_factory.py logger.py data.py test_data/ users.json reports/ # generated screenshots/ # generated conftest.py # root fixtures and hooks pytest.ini requirements.txt .env.example .gitignore README.md

Driver Factory

python # utils/driver_factory.py from selenium import webdriver from selenium.webdriver.chrome.options import Options as ChromeOptions from selenium.webdriver.firefox.options import Options as FirefoxOptions from selenium.webdriver.edge.options import Options as EdgeOptions def create_driver(browser="chrome", headless=False, remote_url=None): browser = browser.lower() if browser == "chrome": options = ChromeOptions() if headless: options.add_argument("--headless=new") options.add_argument("--window-size=1920,1080") options.add_argument("--disable-notifications") elif browser == "firefox": options = FirefoxOptions() if headless: options.add_argument("-headless") options.add_argument("--width=1920") options.add_argument("--height=1080") elif browser == "edge": options = EdgeOptions() if headless: options.add_argument("--headless=new") options.add_argument("--window-size=1920,1080") else: raise ValueError(f"Unsupported browser: {browser}") if remote_url: # Selenium Grid or cloud return webdriver.Remote(command_executor=remote_url, options=options) return {"chrome": webdriver.Chrome, "firefox": webdriver.Firefox, "edge": webdriver.Edge}[browser](options=options)

Root conftest.py

python import os, pytest from dotenv import load_dotenv from utils.config import load_config from utils.driver_factory import create_driver load_dotenv() def pytest_addoption(parser): parser.addoption("--browser", default=os.getenv("BROWSER", "chrome")) parser.addoption("--headless", action="store_true") parser.addoption("--remote", default=os.getenv("GRID_URL")) @pytest.fixture(scope="session") def config(): return load_config() @pytest.hookimpl(tryfirst=True, hookwrapper=True) def pytest_runtest_makereport(item, call): outcome = yield rep = outcome.get_result() setattr(item, f"rep_{rep.when}", rep) @pytest.fixture def driver(request): cfg = request.config drv = create_driver(cfg.getoption("--browser"), cfg.getoption("--headless"), cfg.getoption("--remote")) yield drv rep = getattr(request.node, "rep_call", None) if rep is not None and rep.failed: os.makedirs("screenshots", exist_ok=True) drv.save_screenshot(f"screenshots/{request.node.name}.png") drv.quit() @pytest.fixture def login_page(driver, config): from pages.login_page import LoginPage page = LoginPage(driver) page.open(config["base_url"]) return page

A Test Looks Like This

python # tests/test_checkout.py import pytest from pages.inventory_page import InventoryPage from pages.cart_page import CartPage @pytest.mark.smoke def test_add_item_to_cart(login_page): login_page.login("standard_user", "secret_sauce") inventory = InventoryPage(login_page.driver) inventory.add_to_cart("Sauce Labs Backpack") assert inventory.header.cart_count() == 1 inventory.header.open_cart() assert "Sauce Labs Backpack" in CartPage(login_page.driver).item_names()

Best Practices Checklist

  • Tests independent and runnable in any order
  • Locators only in page objects
  • Explicit waits, no sleep
  • Config and secrets outside the code
  • Screenshot, URL and logs on failure
  • Meaningful test names: test_login_with_locked_user_shows_error
  • Markers for smoke and regression
  • requirements.txt with versions and a clear README
  • Runs the same on your laptop, headless and in CI
  • Code review for tests like any other code

README Essentials

markdown # Selenium Framework ## Setup python -m venv .venv && source .venv/bin/activate pip install -r requirements.txt cp .env.example .env ## Run pytest -m smoke --browser=chrome --headless TEST_ENV=staging pytest -n 4 ## Reports reports/report.html and allure serve allure-results
Start small: A first version needs only: driver fixture, 3 page objects, config and 10 good tests. Grow the framework when the suite grows.

Conclusion

A good framework is a clear folder layout, a driver factory, a root conftest.py, page objects, config outside the code and good reports. Keep it simple and let it grow with the tests.

Quick Summary: pages/ + tests/ + utils/ + config/ + conftest.py + reports.

Get Newsletter

Subscibe to our newsletter and we will notify you about the newest updates on Edugators