Playwright Python UI Automation Framework

A web UI automation framework built with Python, Playwright, Pytest, the Page Object Model, and GitHub Actions. It tests The Internet, a web application containing common browser-automation scenarios.

Project overview

This framework automates browser testing through a scalable architecture that separates concerns: Page Objects manage UI interactions, fixtures handle setup and teardown, and parametrisation enables data-driven validation.

The framework includes:

• Positive and negative test scenarios
• 15 test functions and 18 collected cases
• Page Object Model architecture
• Pytest fixtures and parametrisation
• Reusable test data
• Automatic screenshots and Playwright traces after failures
• Self-contained HTML reports
• Chromium, Firefox, and WebKit execution
• A three-browser GitHub Actions matrix
• Manual test cases, requirements traceability, and sample defect reports

Automated coverage

Area	Automated scenario
Authentication	Successful login
Authentication	Incorrect username
Authentication	Incorrect password
Form controls	Checkbox selection
Form controls	Dropdown selection
File handling	File upload
Browser dialogs	Accept JavaScript alert
Browser dialogs	Cancel JavaScript confirm
Synchronisation	Dynamic loading
Dynamic DOM	Add and remove elements
Data validation	Verify a table row
HTTP	Verify 200, 301, 404, and 500 status codes
Browser contexts	Open a new window
Input validation	Reject letters in a number input
Resource validation	Detect broken images

The status-code test is parametrised. Pytest runs its single test function four times, producing separate results for 200, 301, 404, and 500.

Technology stack

• Python 3.13
• Playwright for Python
• pytest-playwright
• Pytest
• pytest-html
• Git and GitHub
• GitHub Actions
• Visual Studio Code

Framework architecture

playwright-python-ui-automation/
├── .github/workflows/       # Continuous integration workflow
├── .vscode/                 # VS Code testing and debugging settings
├── config/                  # Shared URL, paths, and timeout values
├── data/                    # Reusable credentials and expected values
├── docs/                    # Test plan, cases, bugs, and traceability
├── pages/                   # Page Object Model classes
├── services/                # Non-UI helper for status-code requests
├── tests/                   # Pytest test modules
├── upload_files/            # File used by the upload test
├── reports/                 # Generated HTML report (gitignored)
├── test-results/            # Failure screenshots and traces (gitignored)
├── conftest.py              # Shared Pytest fixtures
├── pytest.ini               # Test discovery, markers, reports, artefacts
├── requirements.txt         # Exact Python package versions
└── README.md

Why Page Object Model?

A test describes what the user is trying to prove. A Page Object contains how the browser interacts with that page.

For example, the test says:

login_page.login(VALID_USERNAME, VALID_PASSWORD)

The selectors and browser actions live inside pages/login_page.py. If the website changes the username selector, only the Page Object needs to be updated.

Local setup on Windows and VS Code

1. Clone the repository

git clone https://github.com/Candycran/playwright-python-ui-automation.git
cd playwright-python-ui-automation
code .

2. Create a virtual environment

py -m venv .venv

Activate it:

.\.venv\Scripts\Activate.ps1

If PowerShell blocks activation:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1

3. Install Python packages

python -m pip install --upgrade pip
pip install -r requirements.txt

4. Install Playwright browsers

python -m playwright install

5. Select the VS Code interpreter

1. Press Ctrl + Shift + P.
2. Select Python: Select Interpreter.
3. Choose the interpreter inside .venv.

Running the tests

Run the complete suite in Chromium

pytest

Playwright runs headlessly by default.

Watch the browser

pytest --headed

Run one file

pytest tests/test_authentication.py --headed -v

Run one test

pytest tests/test_authentication.py::test_successful_login --headed -v

Run by marker

pytest -m smoke
pytest -m regression
pytest -m negative

Run in a particular browser

pytest --browser chromium
pytest --browser firefox
pytest --browser webkit

Run in all three browsers locally

pytest --browser chromium --browser firefox --browser webkit

Debug with Playwright Inspector

$env:PWDEBUG="1"
pytest tests/test_authentication.py::test_successful_login -s

Clear the variable afterwards:

Remove-Item Env:PWDEBUG

Reports, screenshots, and traces

Every standard run creates:

reports/report.html

Open it in a browser to review passed and failed tests.

The pytest.ini file also enables:

--screenshot=only-on-failure
--tracing=retain-on-failure
--output=test-results

After a failure, inspect test-results/. A trace can be opened with:

python -m playwright show-trace path\to\trace.zip

Continuous integration

The workflow at .github/workflows/playwright-tests.yml runs after:

• A push to main
• A pull request targeting main
• A manual workflow dispatch

GitHub creates three jobs through a matrix:

• Chromium
• Firefox
• WebKit

Each job installs its browser, runs the complete suite, and uploads the HTML report, screenshots, and traces as an artifact.

CI/CD evidence

Three green browser jobs

Chromium test output

Firefox test output

Webkit test output

Uploaded artifacts

QA documentation

• Test Plan — Scope, approach, entry/exit criteria, and risk management
• Requirements Traceability Matrix — End-to-end mapping of requirements to coverage
• Manual Test Cases — Detailed human-readable test steps and expected results
• Sample Bug Reports — Professional defect documentation examples

Design decisions

No fixed sleeping

The framework does not use time.sleep(). Playwright waits for elements to become actionable, and Playwright assertions retry until their condition passes or the timeout expires.

Stable locator preference

The Page Objects prefer:

1. Accessible roles and names
2. Unique IDs
3. Small, scoped CSS selectors

Independent tests

Each test opens the page it needs. A test does not rely on another test running first.

Broken-image validation

The Broken Images page intentionally contains two missing resources. The automated test passes when it correctly detects those known broken images.

Known limitations

• The suite depends on a public third-party web application.
• A site outage or markup change can cause external failures.
• This is functional automation, not performance or security testing.
• The sample defect reports are educational examples, not claims about current live defects.

Possible future improvements

• Parallel execution with pytest-xdist
• Accessibility checks with axe-core
• Visual-regression testing
• Dockerised execution
• Test retries limited to known transient failures
• Slack or email CI notifications
• Trend reporting across workflow runs

Technical summary

Designed and developed a Python-based web UI automation framework using Playwright, Pytest, and the Page Object Model. Automated positive and negative browser scenarios covering authentication, controls, uploads, dialogs, dynamic content, tables, windows, response codes, input validation, and broken resources. Added cross-browser GitHub Actions execution, parametrised tests, reusable fixtures and data, HTML reporting, screenshots, traces, test documentation, and sample defect reports.

Author

Praise Chinenye Mbakwe
Junior QA Automation Engineer
GitHub: https://github.com/Candycran
LinkedIn: https://www.linkedin.com/in/praise-mbakwe-51126a311

References

• Playwright Python documentation: https://playwright.dev/python/docs/intro
• Playwright Pytest plugin: https://playwright.dev/python/docs/test-runners
• Playwright CI: https://playwright.dev/python/docs/ci
• Pytest documentation: https://docs.pytest.org/
• GitHub Actions Python guide: https://docs.github.com/actions/automating-builds-and-tests/building-and-testing-python
• Target application: https://the-internet.herokuapp.com/