How to Build a Selenium Python framework from scratch (2026)

TL;DR

Use Selenium WebDriver with pytest, focused domain objects, deterministic test data, and explicit lifecycle management. Prove one scenario and its failure evidence locally and in CI, then scale without introducing shared mutable state.

Key Takeaways

• Start Selenium WebDriver with one complete vertical slice before adding framework layers.
• Keep pytest lifecycle, automation code, domain abstractions, and assertions clearly separated.
• Design test data and cleanup for isolated parallel execution from the beginning.
• Prefer observable conditions and meaningful contracts over sleeps and broad retries.
• Publish focused failure evidence from CI while redacting secrets and sensitive data.
• Add abstractions only when they improve domain readability or remove proven duplication.

Build a Selenium Python framework from scratch means creating a small, reliable test system whose responsibilities are obvious to every contributor. This guide gives you a production-minded path using Selenium WebDriver, Python, and pytest, with runnable examples and decisions that remain sound as the suite grows.

The goal is not the largest framework. The goal is fast feedback, trustworthy failures, safe parallel execution, and code that a new SDET can change without decoding hidden behavior. You will build the foundation, organize automation by intent, add diagnostics, and prepare the suite for continuous integration.

TL;DR

Start with one end-to-end vertical slice. Keep lifecycle in pytest, automation in Selenium WebDriver, behavior in focused domain objects, and expectations in tests. Run pytest -q locally and make the same command the center of CI.

1. Build a Selenium Python framework from scratch: Draw Simple Framework Boundaries

Selenium owns browser automation, pytest owns collection, fixtures, markers, and outcomes, and page objects own interface behavior. Python makes abstractions cheap to create, which is exactly why each abstraction should earn its place. A small explicit framework is easier to debug than a clever metaprogrammed one.

Build one complete smoke test first. It should create a browser, navigate, interact through a page object, assert a business outcome, save evidence on failure, and quit under every outcome.

The review question for this stage is simple: can another engineer explain where this responsibility lives and why? If the answer depends on tribal knowledge, add a small naming improvement or a focused README note. Do not compensate with a large framework manual that becomes stale. Executable examples and conventional locations are better documentation.

2. Create a Reproducible Python Project

Use a virtual environment and declare dependencies in pyproject.toml or the organization standard. Bound major versions so a clean install remains predictable. Commit the dependency lock file if the chosen packaging tool creates one.

Run tests through python -m pytest when interpreter ambiguity is possible. Keep credentials in environment variables, never in pytest.ini. A configuration loader should report missing variables clearly.

Keep the feedback loop short. Run the narrowest relevant test while developing, then the complete suite before merging. A framework is successful when failures point directly to an application rule, environment dependency, or automation defect. It is not successful merely because it has many layers.

Installation

python -m venv .venv
source .venv/bin/activate
python -m pip install selenium pytest pytest-xdist
pytest -q

3. Choose a Pythonic Folder Structure

Keep framework code importable and tests easy to discover. conftest.py contains fixtures used within its directory tree, not arbitrary application logic. Pages and reusable components belong in a package, while tests stay focused on behavior.

Avoid placing every helper in conftest.py. Its implicit discovery is powerful, but excessive hidden behavior makes fixtures hard to trace. Prefer ordinary imported functions for logic that does not need pytest lifecycle or dependency injection.

Treat configuration as input with a schema. Identify required values, defaults, allowed choices, and sensitive fields. Print safe effective configuration at run start, but redact secrets. This turns many CI mysteries into immediate, actionable messages.

Recommended project tree

pyproject.toml
pytest.ini
tests/
  conftest.py
  test_login.py
framework/
  config.py
  pages/
    login_page.py
  components/
    header.py
  support/
    artifacts.py

4. Manage Browsers With Yield Fixtures

A yield fixture creates the driver before yield and quits it afterward, even when the test fails. Use function scope by default for isolation. Wider scopes save startup time but share cookies, windows, storage, and failure state.

Parametrize browsers explicitly or expose a validated command-line option. Selenium Manager handles driver discovery for common local setups. Remote execution only needs the fixture to construct Remote with the intended options.

Design for parallel execution even if the first suite is serial. Avoid global mutable state, fixed record names, shared downloads, and order dependence. Isolation is cheaper to establish with ten tests than to retrofit after one thousand.

Core configuration

[project]
name = "ui-tests"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
  "selenium>=4.44,<5",
  "pytest>=8.4,<9",
  "pytest-xdist>=3.8,<4"
]

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-ra --strict-markers"
markers = ["smoke: critical user journeys"]

5. Write Page Objects That Stay Small

Represent locators as tuples and unpack them into find_element. Methods should model intent, return useful page objects, and avoid swallowing exceptions. A component object can receive the driver and a root element or root locator for scoped interactions.

Do not create a BasePage with dozens of thin wrappers around every Selenium method. A small base with navigation or a shared wait can be acceptable, but ordinary Selenium calls preserve familiar stack traces and documentation.

Use failure evidence to guide abstraction. Repeated business setup may deserve a builder or client. Repeated low-level calls do not automatically deserve a wrapper, especially when wrapping removes useful library diagnostics or blocks new APIs.

Runnable design example

from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

class LoginPage:
    EMAIL = (By.ID, "email")
    PASSWORD = (By.ID, "password")
    SUBMIT = (By.CSS_SELECTOR, "button[type='submit']")

    def __init__(self, driver, base_url: str):
        self.driver = driver
        self.base_url = base_url
        self.wait = WebDriverWait(driver, 10)

    def open(self):
        self.driver.get(f"{self.base_url}/login")
        return self

    def login_as(self, email: str, password: str):
        self.wait.until(EC.visibility_of_element_located(self.EMAIL)).send_keys(email)
        self.driver.find_element(*self.PASSWORD).send_keys(password)
        self.wait.until(EC.element_to_be_clickable(self.SUBMIT)).click()

6. Wait for Meaningful UI States

WebDriverWait polls a callable until it returns a truthy value or times out. Selenium expected_conditions cover common element, frame, alert, title, and URL states. Custom conditions are appropriate when the application exposes a domain-specific state.

Do not mix a large implicit wait with explicit waits. Never repair timing with time.sleep. A specific wait both documents the dependency and finishes immediately when the state is ready.

Code review should check readability at the test call site, deterministic cleanup, assertion quality, and the failure message. These qualities matter more than maximizing reuse. A few repeated lines can be safer than one configurable helper with many boolean switches.

Lifecycle or transformation example

import pytest
from selenium import webdriver

@pytest.fixture
def driver(request):
    browser = request.config.getoption("--browser")
    instance = webdriver.Firefox() if browser == "firefox" else webdriver.Chrome()
    yield instance
    instance.quit()

def pytest_addoption(parser):
    parser.addoption("--browser", default="chrome", choices=("chrome", "firefox"))

@pytest.fixture
def base_url():
    return "https://example.test"

7. Use Parametrization and Stable Data

pytest.mark.parametrize is ideal for a small equivalence table, not for generating hundreds of opaque test cases. Give cases readable ids. Use factories for valid domain data, then override the one field relevant to a negative scenario.

Tests must not rely on collection order. Generate unique usernames or resource IDs, and clean up created data. Under xdist, workers run in separate processes and expose shared-environment collisions quickly.

Maintain a small smoke subset that proves the deployment is testable, then separate broader regression by capability. Tags and markers describe purpose or constraints, not ownership politics. Delete quarantined tests that no longer protect a meaningful risk.

8. Add Hooks, Artifacts, and CI

A pytest hook can attach a screenshot and page source when the call phase fails. Keep the fixture teardown responsible for quitting, and make artifact code defensive so diagnostics never replace the original failure.

Publish JUnit XML and artifacts from CI. Start with one worker, then enable xdist after isolation is proven. Headless mode changes rendering conditions, so set a predictable window size and keep at least one visible-browser debugging path for local reproduction.

Record decisions that affect every contributor, such as naming, lifecycle scope, supported environments, and artifact retention. Leave local implementation details close to code. This balance keeps onboarding practical without creating a second source of truth.

9. How to build a Selenium Python framework from scratch

A practical implementation sequence keeps risk visible. First, commit the smallest dependency and configuration set. Second, automate one representative happy path through the intended public abstractions. Third, force that test to fail and confirm the report tells you why. Fourth, add one negative or boundary case and prove that data cleanup works. Fifth, run two tests concurrently and look for shared state. Finally, place the exact local command in CI.

Do not postpone diagnostics until the suite is large. A framework without useful failure evidence makes every product defect expensive to investigate. Likewise, do not enable maximum parallelism before isolation is measured. A serial test that accidentally depends on another test may appear healthy for months. The first parallel run will expose the dependency, but fixing the design early is much cheaper.

Use pull request review as part of framework governance. A reviewer should be able to identify the scenario, setup, action, expectation, and cleanup without jumping through many files. Shared abstractions should have one reason to change and should not accept unrelated flags. When a contributor needs a special case, decide whether it represents a real domain concept or a one-off test detail.

This is also the stage to connect related skills. Review Selenium locator best practices, Python automation interview questions, Selenium exception troubleshooting for deeper treatment of selectors, contracts, execution, and troubleshooting that complement this build.

10. Verify the Framework Before Expanding It

Verification should cover more than a green test. Run from a clean checkout, use a fresh dependency cache when feasible, and confirm the documented command works. Deliberately break a locator, endpoint, assertion, or table value. The resulting message should identify the failed operation and preserve enough context to reproduce it. Then interrupt setup or throw from the test and confirm teardown still releases resources.

Run the suite twice to detect leaked state. Reverse test order or use a random order plugin only as a diagnostic, because tests should not need a particular order. Execute with at least two workers if the runner supports it. Check that filenames, ports, accounts, and generated identifiers remain independent. If a test targets a shared environment, make ownership and cleanup rules explicit.

Finally, inspect the published CI experience as a maintainer would. The job name should show the relevant environment and test slice. A failed job should retain its report. Secrets should not appear in console output or artifacts. The suite should return a nonzero exit code for real failures and should not silently convert skipped setup into success. These checks turn a code sample into an operational framework.

11. Production Readiness Checklist

Use this checklist as a release gate for the framework itself. A checked item means the behavior was demonstrated, not merely configured. Save the command and evidence in the pull request so another engineer can repeat the check.

Installation and configuration

• A clean checkout installs with the declared pip workflow and does not depend on packages, plugins, browser drivers, or environment files that exist only on the author's machine. Dependency versions are constrained, the relevant manifest is committed, and the supported runtime version is documented.
• The framework validates its effective environment before test execution. Required URLs, browser choices, tokens, and paths produce direct messages when absent or invalid. Safe defaults are limited to local non-sensitive settings. No secret is committed, printed, placed in a screenshot, or copied into a report.

Lifecycle and isolation

• Every test can run by itself, first, last, or beside another test. Setup creates the state the scenario needs, while teardown releases sessions and owned records even after an assertion or setup-adjacent operation fails. Rerunning the suite does not encounter leftovers from the prior run.
• Lifecycle scope matches mutability. A dependency shared across tests is either immutable or deliberately synchronized. Browser sessions, scenario state, request-specific headers, and mutable domain records are not stored in process-wide global variables. Generated files and identifiers include enough uniqueness to avoid worker collisions.

Test design and review

• Test names describe a rule and expected outcome, not a sequence of clicks or calls. The arrange, act, and assert phases are visible even when helper methods are used. Assertions prove the business result and include values that explain a mismatch. A test does not pass merely because Selenium WebDriver raised no exception.
• Abstractions expose domain intent and have cohesive responsibilities. There is no catch-all utility class, hidden retry loop, or base class that every test must inherit only to access unrelated helpers. A contributor can still use the underlying library documentation because wrappers preserve standard concepts.

Reliability and diagnostics

• Synchronization waits for an observable condition and has a bounded timeout. Fixed sleeps are absent from normal test paths. Negative cases distinguish an expected rejection from an infrastructure failure. Any retry policy is visible in runner configuration and accompanied by evidence that allows the first failure to be studied.
• A deliberately broken test produces actionable evidence. The report identifies the scenario and failed expectation. Relevant artifacts survive a failed CI command and use collision-free names. Sensitive headers, cookies, credentials, personal data, and confidential payload fields are redacted before artifacts leave the runner.

Continuous integration and ownership

• The main CI command is the same one documented for local use: pytest -q --junitxml=test-results/junit.xml. CI installs declared dependencies, supplies only approved secrets, returns the correct exit code, and publishes machine-readable results plus focused diagnostics. Pull requests run a fast risk-based subset, while broader coverage has a clear scheduled or release trigger.
• Every recurring failure has an owner and classification. The team distinguishes product defects, automation defects, environment incidents, test-data conflicts, and intentional changes. Quarantine is time-bound and visible. Historical pass rate does not excuse a test that no longer protects a meaningful requirement.

Change safety

Before declaring the foundation ready, make one small framework change, such as adding an environment, browser, endpoint version, or new table shape. Observe how many files must change and whether existing tests remain untouched. Cross-cutting edits are sometimes legitimate, but routine extension should follow an obvious path. If adding one scenario requires editing a central switch statement and several base classes, revisit the boundaries now.

Also perform a dependency-update rehearsal. Read release notes for Selenium WebDriver and pytest, update on a branch, run the clean-install path, and inspect warnings as well as failures. The framework should make upgrades boring: direct APIs, small adapters at genuine boundaries, and no reliance on undocumented internals. Record only compatibility decisions that future contributors need.

Production readiness does not mean feature completeness. It means the framework has a trustworthy path for installing, executing, failing, diagnosing, cleaning up, and changing. New capabilities can then be added in response to product risk without weakening those properties.

Interview Questions and Answers

Q: What layers belong in a Selenium WebDriver framework?

I keep the runner responsible for lifecycle and results, Selenium WebDriver responsible for automation, domain clients or page objects responsible for business operations, and tests responsible for expectations. Configuration and data builders are focused supporting layers. I add a layer only when it creates a clear boundary.

Q: How do you prevent flaky tests?

I isolate data and state, wait for observable conditions, use stable selectors or contracts, and collect evidence on failure. I do not use arbitrary sleeps or automatic reruns as the primary fix. Retries can help diagnose nondeterminism, but the flaky test remains a defect.

Q: What belongs in a page object or API client?

It should expose cohesive business operations and hide local interaction mechanics. Tests should still own scenario-specific assertions. I avoid generic wrappers that merely rename library methods because they reduce diagnostic value without adding domain meaning.

Q: How do you support parallel execution?

Every test receives independent lifecycle state and unique data. I remove static mutable objects, fixed filenames, shared accounts, and order assumptions. Then I increase workers gradually while monitoring environment limits and artifact collisions.

Q: How should secrets and environment settings be handled?

I inject them through environment variables or an approved secret store and validate them at startup. Defaults are safe only for non-sensitive local values. Logs and reports redact tokens, passwords, cookies, and sensitive payload fields.

Q: What evidence should CI retain?

I retain the runner report, machine-readable results, and focused failure diagnostics. UI suites need screenshots and browser-level evidence, while API suites need sanitized request and response details. Artifact collection must run even when the test command fails.

Q: When is framework abstraction excessive?

It is excessive when engineers must trace several wrappers to understand one action, or when options and boolean flags replace clear use cases. I prefer composition, small domain APIs, and direct library calls where they remain readable.

Q: How do you introduce a new framework to a team?

I deliver one vertical slice, document the few global decisions, and pair on the first contributions. Pull request checks enforce formatting and test execution. I expand capabilities in response to real suite needs instead of predicting every future requirement.

A strong interview answer explains the decision, the tradeoff, and a concrete failure mode it prevents. Adapt these models to projects you have actually worked on rather than reciting terminology.

Common Mistakes

• Building wrappers around every Selenium WebDriver call before repeated needs exist. This hides familiar APIs and produces longer stack traces.
• Sharing mutable lifecycle objects or test data across cases. The suite becomes order-dependent and unsafe under parallel execution.
• Putting scenario-specific assertions inside generic pages, clients, fixtures, or step definitions. This makes negative testing and reuse difficult.
• Using sleeps, broad retries, or catch-all exception handling to make failures disappear. These techniques delay feedback and conceal the actual synchronization or contract problem.
• Logging secrets or personal data in reports. Diagnostic value never removes the need for redaction and controlled artifact retention.
• Treating a successful local run as complete verification. A clean CI environment often reveals undeclared dependencies, path assumptions, missing binaries, and timezone differences.
• Growing one utility class into a second framework. Split by cohesive responsibility and keep public APIs small.
• Keeping obsolete tests because they once found a bug. Every test should protect a current risk and have an owner when it fails.

Conclusion

To build a Selenium Python framework from scratch, begin with clear boundaries and one trustworthy vertical slice. Use pytest for execution, Selenium WebDriver for automation, focused domain objects for readable operations, and deterministic data plus cleanup for isolation. Add evidence and CI before adding scale.

Your next step is concrete: create the project, implement the first representative scenario, make it fail on purpose, and inspect the evidence. Once that experience is fast and clear, expand capability by capability while protecting the same design rules.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• How to Build a Selenium Java framework from scratch (2026)
• How to Build a Cypress framework from scratch (2026)
• How to Build a Playwright TypeScript framework from scratch (2026)
• How to Build a REST Assured API framework from scratch (2026)
• How to Add CI to a test framework (2026)
• How to Add logging to a test framework (2026)