Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 35 ยท Projects

Project: A Small Test Framework

Combine a config loader, driver factory, base page, reporting and screenshots on failure into one tidy Selenium test layout, with runnable stand-ins.

Single tests are easy. The hard part comes at test number 200: where does the browser get created, who knows the base URL, how do failures leave evidence, and why does every test file start with the same twelve lines? A test framework answers these questions once. It is not a product you install; it is a small, boring layout of a few files that every test shares.

In this project you assemble the pieces from the whole course into one project: configuration, a driver factory, a base page, page objects, and a runner that takes a screenshot when something fails and prints a report. You should be comfortable with the Page Object Model, explicit waits and test data and configuration.

Selenium needs a browser and a driver, so the real framework code below is read-only. The runnable examples are stand-ins written in JavaScript: a fake driver that behaves like a tiny browser, and the same config, factory, base page and runner structure as the real thing. The structure is real; the "browser" is not.

Five layers, one direction

Config URL, browser, timeout, headless.
Driver factory Builds the right driver from config.
Base page Waits and helpers every page shares.
Page objects Locators plus user actions.

Each layer only knows about the layers above it in this list.

1 / 2

The project layout

A layout that scales well past a hundred tests looks like this:

TEXT
selenium-project/
  pytest.ini
  requirements.txt
  config.py               # reads settings and environment variables
  conftest.py             # fixtures: config, driver, failure screenshots
  framework/
    driver_factory.py     # builds Chrome, Firefox or Edge from config
    base_page.py          # waits and common actions
  pages/
    login_page.py         # one class per page or component
    dashboard_page.py
  tests/
    test_login.py
  artifacts/              # screenshots and reports (ignored by git)

The golden rule: tests talk to pages, pages talk to the base page, the base page talks to the driver. A test should never contain a locator, and a page object should never create a browser.

Layer 1: configuration

Configuration is everything that changes between your laptop, CI and staging: base URL, browser, headless or not, timeout. Defaults live in code; the environment overrides them; and the result is validated once, early, with a clear message. Credentials never belong in the repository (see Test Data and Configuration).

Python
# config.py
import os
from dataclasses import dataclass

@dataclass(frozen=True)
class Config:
    browser: str = "chrome"
    headless: bool = True
    base_url: str = "http://localhost:3000"
    timeout: int = 10

def load_config() -> Config:
    config = Config(
        browser=os.getenv("BROWSER", "chrome").lower(),
        headless=os.getenv("HEADLESS", "1") != "0",
        base_url=os.getenv("BASE_URL", "http://localhost:3000").rstrip("/"),
        timeout=int(os.getenv("TIMEOUT", "10")),
    )
    if config.browser not in {"chrome", "firefox", "edge"}:
        raise ValueError(f"Unsupported browser: {config.browser}")
    return config

Making the dataclass frozen means no test can quietly change a setting that other tests depend on.

Layer 2: the driver factory

The factory is the only code that knows how to build a browser. When a new option is needed, such as a window size or a download folder, exactly one file changes.

Python
# framework/driver_factory.py
from selenium import webdriver

def create_driver(config):
    if config.browser == "chrome":
        options = webdriver.ChromeOptions()
        if config.headless:
            options.add_argument("--headless=new")
        options.add_argument("--window-size=1280,900")
        return webdriver.Chrome(options=options)
    if config.browser == "firefox":
        options = webdriver.FirefoxOptions()
        if config.headless:
            options.add_argument("-headless")
        driver = webdriver.Firefox(options=options)
        driver.set_window_size(1280, 900)
        return driver
    options = webdriver.EdgeOptions()
    if config.headless:
        options.add_argument("--headless=new")
    options.add_argument("--window-size=1280,900")
    return webdriver.Edge(options=options)

Selenium Manager finds or downloads the matching driver binary automatically, so the factory does not need any paths. This is the same idea you will meet again in Headless Mode and Browser Options.

Here is a runnable stand-in for layers 1 and 2. The "driver" only reports what it was built with, but the loading, validation and branching are exactly the logic above:

JS Stand-in: config loader and driver factory

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that bad settings fail immediately with a readable message, before any browser starts. That is far cheaper than discovering a typo in BROWSER after a ten-minute run.

Layer 3: the base page

Every page object needs the same few things: the driver, a way to wait for an element, and thin wrappers for clicking and typing. Putting them in BasePage keeps page classes short and puts waits in one place, which is the best defence against flaky tests (see Why Tests Need Waits).

Python
# framework/base_page.py
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

class BasePage:
    def __init__(self, driver, config):
        self.driver = driver
        self.config = config
        self.wait = WebDriverWait(driver, config.timeout)

    def visible(self, locator):
        return self.wait.until(EC.visibility_of_element_located(locator))

    def click(self, locator):
        self.wait.until(EC.element_to_be_clickable(locator)).click()

    def type(self, locator, text):
        field = self.visible(locator)
        field.clear()
        field.send_keys(text)

A page object then reads like a description of a screen:

Python
# pages/login_page.py
from selenium.webdriver.common.by import By
from framework.base_page import BasePage

class LoginPage(BasePage):
    USERNAME = (By.ID, "username")
    PASSWORD = (By.ID, "password")
    SUBMIT = (By.CSS_SELECTOR, "[data-testid='login']")
    WELCOME = (By.CSS_SELECTOR, "[data-testid='welcome']")
    ERROR = (By.CSS_SELECTOR, "[data-testid='error']")

    def open(self):
        self.driver.get(self.config.base_url + "/login")
        return self

    def login_as(self, user, password):
        self.type(self.USERNAME, user)
        self.type(self.PASSWORD, password)
        self.click(self.SUBMIT)

    def welcome_text(self):
        return self.visible(self.WELCOME).text

    def error_text(self):
        return self.visible(self.ERROR).text

Layer 4: fixtures and screenshots on failure

With pytest, conftest.py is the glue. One fixture creates the driver for each test and quits it afterwards, even when the test fails. A small hook remembers whether the test passed, so the fixture can save a screenshot while the browser is still open:

Python
# conftest.py
import pathlib
import pytest
from config import load_config
from framework.driver_factory import create_driver

@pytest.fixture(scope="session")
def config():
    return load_config()

@pytest.hookimpl(tryfirst=True, hookwrapper=True)
def pytest_runtest_makereport(item, call):
    outcome = yield
    report = outcome.get_result()
    setattr(item, f"rep_{report.when}", report)

@pytest.fixture
def driver(config, request):
    driver = create_driver(config)
    yield driver
    report = getattr(request.node, "rep_call", None)
    if report is not None and report.failed:
        folder = pathlib.Path("artifacts")
        folder.mkdir(exist_ok=True)
        driver.save_screenshot(str(folder / f"{request.node.name}.png"))
        (folder / f"{request.node.name}.html").write_text(driver.page_source, encoding="utf-8")
    driver.quit()

Saving page_source next to the PNG is cheap and very useful: when a CI run fails at night you can read the DOM as it was. The code after yield is the teardown, which pytest runs whether the test passed or failed. Selenium with pytest explains this mechanism in detail.

A test now contains no setup noise at all:

Python
# tests/test_login.py
from pages.login_page import LoginPage

def test_valid_login(driver, config):
    page = LoginPage(driver, config).open()
    page.login_as("ana", "s3cret")
    assert page.welcome_text() == "Welcome, ana"

The whole thing, running

Because the real stack cannot run here, the next stand-in puts all layers into one script. The FakeDriver is a tiny page model with a delayed "server" response, BasePage.waitFor polls with a timeout like WebDriverWait, and runSuite plays the part of pytest: a fresh driver per test, a screenshot when something goes wrong, and a final report. Two tests are broken on purpose, so you can see the two different kinds of failure: an assertion failure (the page was fine, the expectation was wrong) and an error (the page never reached the expected state).

JS Stand-in: a complete mini framework

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Look at the screenshot lines. The failed assertion shows an error element on the page, so the evidence says "the page is right, the test expectation is wrong". The timeout shows only welcome, so you can see at a glance that the login worked and the test waited for something else. That is why evidence on failure is worth the few lines it costs.

Making it your own

Once the skeleton works, grow it in small steps:

  • Reporting. Add pytest-html or Allure and attach the artifacts folder in CI (see Reporting and Logging).
  • Markers. Mark tests as smoke or slow and run subsets with pytest -m smoke.
  • Parallel runs. Because each test builds its own driver and shares no state, pytest-xdist works without changes (see Running in CI).
  • Retries. Add them last and sparingly, since they can hide real bugs (see Flaky Tests and Debugging).
  • Java. The same layers map to Maven or Gradle, a DriverFactory class, a BasePage class and JUnit or TestNG listeners for screenshots (see Selenium with JUnit and TestNG).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which rule keeps a framework layout easy to change?

    Each layer has one job. When the browser setup or a locator changes, exactly one file needs editing.
  2. 2. Why does the driver fixture save the screenshot before calling driver.quit()?

    A screenshot captures the live browser window. Once the session is closed, nothing is left to capture.
  3. 3. In the stand-in report, what is the difference between a failed test and an errored test?

    An assertion failure says the observed value differed from the expected one. A timeout or missing element says the page never got there, which points to a different kind of problem.
  4. 4. Why validate configuration when it is loaded?

    Early validation turns a confusing mid-run failure into a one-line message before any browser opens.

Summary

  • A framework is a small layout, not a library: config, driver factory, base page, page objects, fixtures and tests.
  • Tests never contain locators or browser setup; page objects never create browsers.
  • Configuration comes from defaults plus environment variables, is validated once and is read-only afterwards.
  • One fixture builds the driver per test, saves a screenshot and the page source on failure, and always quits.
  • Separate "failed" (wrong value) from "error" (the page never got there): the evidence tells different stories.
  • Add reporting, markers, parallelism and retries only after the basics are stable.

Finally, test yourself with Practice Exercises with Solutions.