Build a Complete Selenium Framework Structure
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.txtwith 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.

