🧩 Mini Automation Framework (Page/Object Model)

A lightweight, scalable Python test-automation framework demonstrating clean structure for both UI and API testing — built around the Page/Object Model with Playwright, a small API client, environment-driven configuration, a Typer CLI, structured logging, pre-commit hooks, Docker, and CI.

---

✨ Features

• UI testing — Playwright + pytest using the Page/Object Model (src/maf/ui/pages/).
• API testing — a small requests-based client (src/maf/api/) with a health check.
• Environment-driven config — pydantic settings sourced from MAF_* environment variables.
• CLI runner — a Typer app to run UI / API / all suites.
• Structured logging — Loguru.
• Screenshots on failure — UI failures save a PNG to artifacts/ (optionally embedded in an HTML report).
• Code quality — pre-commit hooks (Black + Ruff) and mypy configuration.
• Containerized — a Dockerfile based on the official Playwright Python image.
• CI — GitHub Actions runs API tests (blocking) and UI tests (non-blocking).

---

🛠 Tech Stack

Area	Tools
Language	Python 3.10+
UI testing	Playwright, pytest-playwright
API testing	requests
Config / models	pydantic
CLI	Typer
Logging	Loguru
Quality	Black, Ruff, mypy, pre-commit
CI / Deploy	GitHub Actions, Docker

---

📂 Project Structure

.
├── src/maf/
│   ├── api/
│   │   └── client.py          # ApiClient (health check via requests)
│   ├── core/
│   │   ├── config.py          # pydantic Config from MAF_* env vars
│   │   ├── logger.py          # Loguru logger setup
│   │   └── runner.py          # Typer CLI: ui / api / all
│   └── ui/pages/              # Page Objects (base, login, inventory)
├── tests/
│   ├── api/test_health.py     # API test
│   └── ui/test_login.py       # UI test (Page/Object pattern)
├── conftest.py                # Headless config + screenshot-on-failure
├── Dockerfile                 # Playwright Python image
├── pyproject.toml             # Packaging, deps, tool config (ruff/black/mypy)
├── .pre-commit-config.yaml    # Black + Ruff hooks
└── .github/workflows/tests.yml# CI

---

🚦 Getting Started

Prerequisites

• Python 3.10+

Installation

git clone https://github.com/douglasalfaro/mini-automation-framework.git
cd mini-automation-framework

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

pip install -e ".[dev]"          # install the package + dev tools
python -m playwright install     # download browser binaries (add --with-deps on Linux/CI)

Run the tests

pytest tests/api      # API tests
pytest tests/ui       # UI tests (Playwright)
pytest                # everything

Or use the Typer CLI runner:

python -m maf.core.runner api    # API suite
python -m maf.core.runner ui     # UI suite
python -m maf.core.runner all    # both

---

⚙️ Configuration

The framework reads configuration from environment variables (see .env.example). Export them in your shell or set them in CI:

Variable	Default	Description
MAF_BASE_URL	https://www.saucedemo.com	Base URL for UI tests.
MAF_API_BASE	https://httpbin.org	Base URL for API tests.
MAF_HEALTH_PATH	/status/200	Path the API health check requests.
MAF_HEADLESS	true	Run the browser headless (false to watch it run).

---

🐳 Docker

docker build -t mini-automation-framework .
docker run --rm mini-automation-framework        # runs `pytest -q`

The image is based on mcr.microsoft.com/playwright/python, so browser dependencies are preinstalled.

---

🧹 Code Quality

pre-commit install      # set up the git hooks
pre-commit run --all-files

Black and Ruff run automatically on commit; mypy is configured in pyproject.toml.

---

🔭 Future Improvements

• Expand UI coverage with more Page Objects and end-to-end flows.
• Add pytest-html/Allure reporting and publish reports from CI.
• Add cross-browser runs (Chromium, Firefox, WebKit) via a CI matrix.
• Wire the Typer runner as a console-script entry point.

---

👤 About the Developer

Douglas Alfaro is a full-stack developer with experience building practical business solutions using modern web technologies, automation, APIs, and cloud-based tools. His work focuses on creating useful, scalable applications for real-world business problems.

• GitHub: @douglasalfaro

---

📄 License

Released under the MIT License.