From c585d1c221aaa8758b1518422b81ee8298a87b3e Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 25 Feb 2026 03:42:34 +0000
Subject: [PATCH 1/2] Initial plan


From 1c08aa097c6b6d537951bcce3ef64860f4c040d5 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 25 Feb 2026 03:54:58 +0000
Subject: [PATCH 2/2] feat: complete framework implementation - add missing
 modules, tests, docs

Co-authored-by: ErickFlores13 <112999558+ErickFlores13@users.noreply.github.com>
---
 README.md                                   | 119 +++--
 conftest.py                                 |  27 +
 core/api/services/auth/strategies/oauth2.py |  68 ++-
 docs/API_TESTING.md                         | 543 ++++++++++++++++++++
 docs/DATABASE_TESTING.md                    | 340 ++++++++++++
 docs/UI_TESTING.md                          | 482 +++++++++++++++++
 services/__init__.py                        |   6 +
 services/base_pages/__init__.py             |   3 +
 services/base_pages/login_page.py           |  77 +++
 tests/__init__.py                           |   1 +
 tests/test_api_examples.py                  | 386 ++++++++++++++
 tests/test_crud_example.py                  | 284 ++++++++++
 tests/test_database_examples.py             | 242 +++++++++
 tests/test_ui_examples.py                   | 275 ++++++++++
 utils/config.py                             |  21 -
 15 files changed, 2797 insertions(+), 77 deletions(-)
 create mode 100644 docs/API_TESTING.md
 create mode 100644 docs/DATABASE_TESTING.md
 create mode 100644 docs/UI_TESTING.md
 create mode 100644 services/__init__.py
 create mode 100644 services/base_pages/__init__.py
 create mode 100644 services/base_pages/login_page.py
 create mode 100644 tests/__init__.py
 create mode 100644 tests/test_api_examples.py
 create mode 100644 tests/test_crud_example.py
 create mode 100644 tests/test_database_examples.py
 create mode 100644 tests/test_ui_examples.py

diff --git a/README.md b/README.md
index c16105d..11d94e0 100644
--- a/README.md
+++ b/README.md
@@ -151,47 +151,96 @@ Pre-commit hooks run automatically on `git commit` and ensure consistent code qu
 ## 🏗️ Project Structure
 
 ```
-playwright-python-async-template/
-├── pages/                      # Page Object Model
-│   ├── base_page.py           # Core browser interactions
-│   ├── standard_web_page.py   # Common UI patterns (CRUD, filters, etc.)
-│   ├── login_page.py          # Authentication
-│   └── examples/              # Example page objects
+playwright-python-async-framework/
+├── core/                           # Framework internals
+│   ├── api/                        # API testing layer
+│   │   ├── base_client.py          # BaseAPIClient (HTTP methods + auth)
+│   │   ├── http_client.py          # Low-level HTTP with retries
+│   │   ├── config.py               # HTTPConfig presets
+│   │   ├── models.py               # API exception models
+│   │   ├── services/
+│   │   │   ├── auth/               # Authentication strategies
+│   │   │   │   └── strategies/     # Bearer, APIKey, Basic, OAuth2, etc.
+│   │   │   ├── response/           # APIResponseWrapper
+│   │   │   ├── retry.py            # Retry with exponential backoff
+│   │   │   ├── interceptor.py      # Request/response interceptors
+│   │   │   └── validation.py       # Schema + status code validation
+│   │   ├── README.md               # API usage guide (user-facing)
+│   │   └── DEVELOPER_GUIDE.md      # How to extend the API layer
+│   │
+│   ├── ui/                         # UI testing layer
+│   │   ├── base_page.py            # BasePage with lazy-loaded services
+│   │   ├── ai/                     # AI-powered selector healing
+│   │   │   ├── locator_healer.py   # Main healing orchestrator
+│   │   │   ├── cache_manager.py    # Persistent healing cache
+│   │   │   ├── metrics_tracker.py  # Healing metrics & reports
+│   │   │   └── extraction/         # DOM extraction strategies
+│   │   ├── browser/
+│   │   │   ├── browser_manager.py  # Browser lifecycle management
+│   │   │   └── strategies/         # Local / CI / Debug strategies
+│   │   ├── components/             # Reusable UI components
+│   │   │   ├── button.py, checkbox.py, datepicker.py
+│   │   │   ├── input.py, modal.py, radio.py
+│   │   │   ├── select.py, select2.py, table.py
+│   │   │   └── file.py
+│   │   ├── services/               # Page interaction services
+│   │   │   ├── attribute.py        # DOM attribute manipulation
+│   │   │   ├── screenshot.py       # Evidence capture
+│   │   │   ├── storage.py          # LocalStorage / Cookies
+│   │   │   ├── tab_window.py       # Multi-tab management
+│   │   │   ├── validation.py       # Assertion helpers
+│   │   │   ├── wait.py             # Page-load waiting
+│   │   │   └── form/               # Form-filling strategies
+│   │   ├── wrappers/               # Locator wrappers
+│   │   │   ├── retry_locator.py    # Retry failed operations
+│   │   │   └── smart_locator.py    # AI healing + retry wrapper
+│   │   ├── README.md               # UI usage guide (user-facing)
+│   │   └── DEVELOPER_GUIDE.md      # How to extend the UI layer
+│   │
+│   ├── reporting/
+│   │   └── pytest_hooks.py         # Auto-screenshot on failure + Allure
+│   │
+│   └── utils/
+│       ├── exceptions.py           # Custom exception types
+│       ├── logger_config.py        # Centralized logging setup
+│       └── playwright_utils.py     # Locator resolution helpers
 │
-├── helpers/                    # Helper modules
-│   ├── api_client.py          # API testing client
-│   ├── database.py            # Database client (PostgreSQL, MySQL, etc.)
-│   └── redis_client.py        # Redis client
+├── services/                       # Project-level page objects
+│   └── base_pages/
+│       └── login_page.py           # Generic login page (used by conftest)
 │
-├── utils/                      # Utilities
-│   ├── config.py              # Configuration management
-│   ├── consts.py              # Constants and enums
-│   ├── exceptions.py          # Custom exceptions
-│   └── test_helpers.py        # Test utilities
+├── helpers/                        # Infrastructure clients
+│   ├── database.py                 # DatabaseClient (PostgreSQL, MySQL, …)
+│   └── redis_client.py             # RedisClient
 │
-├── tests/                      # Test suites
-│   ├── test_ui_examples.py    # UI testing examples
-│   ├── test_api_examples.py   # API testing examples
-│   ├── test_database_examples.py  # Database testing examples
-│   └── test_crud_example.py   # Complete CRUD example
+├── utils/                          # Project-level utilities
+│   ├── config.py                   # Centralized configuration (env vars)
+│   ├── consts.py                   # Enumerations (FilterType, etc.)
+│   └── test_helpers.py             # TestDataGenerator + TestHelpers
 │
-├── docs/                       # Documentation
-│   ├── UI_TESTING.md          # UI testing guide
-│   ├── API_TESTING.md         # API testing guide
-│   └── DATABASE_TESTING.md    # Database testing guide
+├── tests/                          # Example test suites
+│   ├── test_ui_examples.py         # UI automation examples
+│   ├── test_api_examples.py        # REST API testing examples
+│   ├── test_database_examples.py   # Database & Redis testing examples
+│   └── test_crud_example.py        # Complete CRUD workflow example
 │
-├── ci/                         # CI/CD configuration
-│   └── Jenkinsfile            # Jenkins pipeline
+├── docs/                           # User-facing documentation
+│   ├── UI_TESTING.md               # UI testing patterns & examples
+│   ├── API_TESTING.md              # API testing patterns & examples
+│   └── DATABASE_TESTING.md         # Database testing patterns & examples
 │
-├── conftest.py                 # Pytest configuration and fixtures
-├── pytest.ini                  # Pytest settings
-├── requirements.txt            # Python dependencies
-├── Dockerfile                  # Docker configuration
-├── docker-compose.yml          # Docker Compose orchestration
-├── .pre-commit-config.yaml     # Pre-commit hooks configuration
-├── pyproject.toml              # Python tooling configuration
-├── .env.example               # Environment template
-└── README.md                   # This file
+├── ci/                             # CI/CD configuration
+│   └── Jenkinsfile                 # Jenkins pipeline
+│
+├── conftest.py                     # Pytest fixtures (browser, page, api_client, …)
+├── pytest.ini                      # Pytest settings (markers, testpaths, …)
+├── requirements.txt                # Python dependencies
+├── Dockerfile                      # Docker image for test runner
+├── docker-compose.yml              # Multi-service Docker Compose (DB + Redis)
+├── .pre-commit-config.yaml         # Pre-commit hooks (black, flake8, mypy, …)
+├── pyproject.toml                  # Tool configuration (black, isort, mypy, …)
+├── .env.example                    # Environment variable template
+└── README.md                       # This file
 ```
 
 ---
diff --git a/conftest.py b/conftest.py
index 0403201..93e91e7 100644
--- a/conftest.py
+++ b/conftest.py
@@ -16,6 +16,8 @@
 from core.utils.logger_config import configure_logging
 from helpers.database import DatabaseClient
 
+from core.api.base_client import BaseAPIClient
+
 # Custom imports
 from helpers.redis_client import RedisClient
 from services.base_pages.login_page import LoginPage
@@ -162,6 +164,31 @@ async def _connect_to_environment(username: str, password: str, url: str):
     return _connect_to_environment
 
 
+# --- API client fixture -------------------------------------------------------
+@pytest_asyncio.fixture(scope="function")
+async def api_client(context: BrowserContext) -> BaseAPIClient:
+    """
+    Provides a ready-to-use BaseAPIClient for API testing.
+
+    The client is pre-configured with the base URL from the
+    ``API_BASE_URL`` environment variable (falls back to ``BASE_URL``).
+    Authentication can be configured per-test via:
+
+    - ``client.set_bearer_token("token")``
+    - ``client.set_api_key("key")``
+    - ``client.set_basic_auth("user", "pass")``
+
+    Example::
+
+        async def test_get_users(api_client):
+            api_client.set_bearer_token(Config.get_api_bearer_token())
+            response = await api_client.get("/users")
+            assert response.is_success
+            assert isinstance(response.data, list)
+    """
+    return BaseAPIClient(context.request, Config.get_api_base_url())
+
+
 # --- Database fixtures --------------------------------------------------------
 @pytest_asyncio.fixture
 async def db_client():
diff --git a/core/api/services/auth/strategies/oauth2.py b/core/api/services/auth/strategies/oauth2.py
index 28c0fbb..2c2be7e 100644
--- a/core/api/services/auth/strategies/oauth2.py
+++ b/core/api/services/auth/strategies/oauth2.py
@@ -70,31 +70,57 @@ def _needs_refresh(self) -> bool:
 
     async def _fetch_token(self) -> None:
         """
-        Fetch access token from token endpoint.
+        Fetch access token from token endpoint using client credentials flow.
 
-        Note: Requires HTTPClient to be injected or uses requests library.
+        Makes a POST request to the token URL with client credentials.
+        Uses the standard OAuth2 client_credentials grant type.
+
+        Raises:
+            RuntimeError: If token request fails or response is invalid
         """
-        # This would use HTTPClient in real implementation
-        # For now, showing the structure
+        import asyncio
+        import json
+        import urllib.error
+        import urllib.parse
+        import urllib.request
+
         logger.info(f"Fetching OAuth2 token from {self.token_url}")
 
-        # In real implementation:
-        # response = await http_client.post(
-        #     self.token_url,
-        #     data={
-        #         'grant_type': 'client_credentials',
-        #         'client_id': self.client_id,
-        #         'client_secret': self.client_secret,
-        #         'scope': self.scope
-        #     }
-        # )
-        # self._access_token = response.data['access_token']
-        # self._expires_at = time.time() + response.data.get('expires_in', 3600)
-
-        raise NotImplementedError(
-            "OAuth2 token fetching requires HTTPClient integration. "
-            "Use BearerTokenAuth with pre-fetched token for now."
-        )
+        post_data: dict = {
+            "grant_type": "client_credentials",
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+        }
+        if self.scope:
+            post_data["scope"] = self.scope
+
+        encoded_data = urllib.parse.urlencode(post_data).encode("utf-8")
+
+        def _sync_fetch() -> dict:
+            req = urllib.request.Request(
+                self.token_url,
+                data=encoded_data,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+                method="POST",
+            )
+            with urllib.request.urlopen(req) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+
+        try:
+            token_response = await asyncio.to_thread(_sync_fetch)
+            self._access_token = token_response["access_token"]
+            expires_in = token_response.get("expires_in", 3600)
+            self._expires_at = time.time() + int(expires_in)
+            logger.info("OAuth2 token fetched successfully")
+        except urllib.error.HTTPError as e:
+            error_body = e.read().decode("utf-8")
+            raise RuntimeError(
+                f"OAuth2 token request failed (HTTP {e.code}): {error_body}"
+            ) from e
+        except (KeyError, ValueError) as e:
+            raise RuntimeError(f"Invalid OAuth2 token response: {e}") from e
+        except Exception as e:
+            raise RuntimeError(f"Failed to fetch OAuth2 token: {e}") from e
 
     @classmethod
     def from_env(
diff --git a/docs/API_TESTING.md b/docs/API_TESTING.md
new file mode 100644
index 0000000..dc947f1
--- /dev/null
+++ b/docs/API_TESTING.md
@@ -0,0 +1,543 @@
+# API Testing Guide
+
+Complete guide for REST API testing using the Playwright Python Async Framework.
+
+> **Quick reference?** See [core/api/README.md](../core/api/README.md)  
+> **Extending the framework?** See [core/api/DEVELOPER_GUIDE.md](../core/api/DEVELOPER_GUIDE.md)
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Quick Start](#quick-start)
+- [Service Client Pattern](#service-client-pattern)
+- [HTTP Methods](#http-methods)
+- [Authentication](#authentication)
+- [Response Validation](#response-validation)
+- [HTTP Configuration Presets](#http-configuration-presets)
+- [conftest Fixtures](#conftest-fixtures)
+- [Complete Examples](#complete-examples)
+
+---
+
+## Overview
+
+The API testing layer wraps Playwright's `APIRequestContext` with a clean,
+strategy-based client. The architecture has three layers:
+
+```
+Service Clients (your code)        e.g. UserServiceClient, OrderClient
+        ↓ extends
+BaseAPIClient (framework)          get(), post(), put(), patch(), delete()
+        ↓ uses
+HTTPClient (infrastructure)        retry logic, interceptors, timeouts
+```
+
+You focus on **business logic**; the framework handles HTTP mechanics.
+
+---
+
+## Quick Start
+
+### 1. Create a Service Client
+
+```python
+from pydantic import BaseModel
+from core.api.base_client import BaseAPIClient
+
+class User(BaseModel):
+    id: int
+    name: str
+    email: str
+
+class UserServiceClient(BaseAPIClient):
+    """Typed client for the User service."""
+
+    async def list_users(self) -> list[User]:
+        response = await self.get('/users')
+        return [User(**u) for u in response.data]
+
+    async def get_user(self, user_id: int) -> User:
+        response = await self.get(f'/users/{user_id}')
+        return self.validation.validate_schema(response.data, User)
+
+    async def create_user(self, name: str, email: str) -> User:
+        response = await self.post('/users', data={'name': name, 'email': email})
+        return self.validation.validate_schema(response.data, User)
+
+    async def delete_user(self, user_id: int) -> None:
+        await self.delete(f'/users/{user_id}')
+```
+
+### 2. Use the `api_client` Fixture
+
+A generic `api_client` fixture is available in every test via `conftest.py`:
+
+```python
+async def test_api_health(api_client):
+    response = await api_client.get('/health')
+    assert response.is_success
+```
+
+### 3. Create a Typed Service Fixture
+
+For domain-specific clients, define a fixture in your test file or a
+shared `conftest.py`:
+
+```python
+import pytest_asyncio
+from core.api.services.auth import BearerTokenAuth
+
+@pytest_asyncio.fixture
+async def user_client(context):
+    auth = BearerTokenAuth(token='my-jwt-token')
+    return UserServiceClient(
+        context.request,
+        base_url='https://api.example.com',
+        auth_strategy=auth,
+    )
+
+async def test_get_user(user_client):
+    user = await user_client.get_user(1)
+    assert user.id == 1
+    assert user.name
+```
+
+---
+
+## Service Client Pattern
+
+Define one `BaseAPIClient` subclass per service/domain:
+
+```python
+class OrderServiceClient(BaseAPIClient):
+    """Client for the Orders microservice."""
+
+    async def create_order(self, items: list[dict]) -> dict:
+        response = await self.post('/orders', data={'items': items}, expected_status=201)
+        return response.data
+
+    async def get_order(self, order_id: str) -> dict:
+        response = await self.get(f'/orders/{order_id}')
+        self.validation.validate_required_fields(response.data, ['id', 'status', 'items'])
+        return response.data
+
+    async def cancel_order(self, order_id: str) -> None:
+        await self.delete(f'/orders/{order_id}', expected_status=[200, 204])
+```
+
+---
+
+## HTTP Methods
+
+All methods return an `APIResponseWrapper`:
+
+```python
+response.data         # Parsed JSON (dict or list), or plain text
+response.status_code  # HTTP status code (int)
+response.headers      # Response headers (dict)
+response.elapsed_ms   # Request duration in milliseconds
+response.is_success   # True for 2xx status codes
+response.url          # Request URL
+response.method       # HTTP method used
+```
+
+### GET
+
+```python
+# Simple fetch
+response = await client.get('/users/1')
+
+# With query parameters
+response = await client.get('/users', params={'page': 1, 'per_page': 20, 'status': 'active'})
+
+# Accept multiple status codes
+response = await client.get('/users/99999', expected_status=[200, 404])
+```
+
+### POST
+
+```python
+response = await client.post('/users', data={
+    'name': 'Alice',
+    'email': 'alice@example.com',
+    'role': 'editor',
+})
+# Default expected_status is 201
+```
+
+### PUT (full update)
+
+```python
+response = await client.put('/users/1', data={
+    'id': 1,
+    'name': 'Alice Updated',
+    'email': 'alice.new@example.com',
+})
+```
+
+### PATCH (partial update)
+
+```python
+response = await client.patch('/users/1', data={'email': 'new@example.com'})
+```
+
+### DELETE
+
+```python
+response = await client.delete('/users/1')
+# Default expected_status is 204
+```
+
+### Custom Headers per Request
+
+```python
+response = await client.get(
+    '/protected',
+    headers={'X-Request-ID': 'trace-abc-123', 'X-Tenant': 'tenant-1'},
+)
+```
+
+---
+
+## Authentication
+
+### Bearer Token
+
+```python
+from core.api.services.auth import BearerTokenAuth
+
+auth = BearerTokenAuth(token='your-jwt-token')
+
+# Or from environment (reads API_BEARER_TOKEN)
+auth = BearerTokenAuth.from_env()
+
+# Or lazy fetch via login endpoint
+auth = BearerTokenAuth(
+    playwright_context=context.request,
+    api_url='https://api.example.com',
+    auth_endpoint='/auth/token',
+    credentials={'username': 'user', 'password': 'pass'},
+    token_field='access_token',
+)
+```
+
+### API Key
+
+```python
+from core.api.services.auth import APIKeyAuth
+
+auth = APIKeyAuth(api_key='sk_test_123456')                    # header: X-API-Key
+auth = APIKeyAuth(api_key='abc123', header_name='Authorization')  # custom header
+
+# From environment (reads API_KEY and API_KEY_HEADER_NAME)
+auth = APIKeyAuth.from_env()
+```
+
+### Basic Auth
+
+```python
+from core.api.services.auth import BasicAuth
+
+auth = BasicAuth(username='admin', password='password123')
+
+# From environment (reads API_USERNAME and API_PASSWORD)
+auth = BasicAuth.from_env()
+```
+
+### OAuth2 Client Credentials
+
+```python
+from core.api.services.auth import OAuth2ClientCredentialsAuth
+
+auth = OAuth2ClientCredentialsAuth(
+    client_id='your-client-id',
+    client_secret='your-secret',
+    token_url='https://auth.example.com/oauth/token',
+    scope='read write',           # optional
+)
+# Token is fetched and cached automatically; refreshed when expired.
+
+# From environment (reads OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, OAUTH_SCOPE)
+auth = OAuth2ClientCredentialsAuth.from_env(
+    token_url='https://auth.example.com/oauth/token'
+)
+```
+
+### Refreshable Token
+
+```python
+from core.api.services.auth import RefreshableTokenAuth
+import time
+
+async def get_fresh_token():
+    # Your refresh logic here
+    return 'new-access-token'
+
+auth = RefreshableTokenAuth(
+    initial_token='current-token',
+    refresh_callback=get_fresh_token,
+    expires_at=time.time() + 3600,
+)
+```
+
+### Custom Headers
+
+```python
+from core.api.services.auth import CustomHeaderAuth
+
+auth = CustomHeaderAuth(headers={
+    'X-API-Key':    'abc123',
+    'X-Tenant-ID':  'tenant-456',
+    'X-API-Version': 'v2',
+})
+```
+
+### Composite (Multiple Strategies)
+
+```python
+from core.api.services.auth import CompositeAuth, BearerTokenAuth, CustomHeaderAuth
+
+auth = CompositeAuth([
+    BearerTokenAuth(token='jwt-token'),
+    CustomHeaderAuth(headers={'X-Tenant-ID': 'tenant-1'}),
+])
+```
+
+### Switching Auth Mid-Test
+
+```python
+from core.api.services.auth import BearerTokenAuth
+
+client.set_bearer_token('admin-token')
+await client.delete('/users/42')
+
+client.set_bearer_token('regular-user-token')
+response = await client.get('/users/me')
+```
+
+---
+
+## Response Validation
+
+### Schema Validation (Pydantic)
+
+```python
+from pydantic import BaseModel
+
+class User(BaseModel):
+    id: int
+    name: str
+    email: str
+    status: str
+
+user = self.validation.validate_schema(response.data, User)
+print(user.name)   # IDE autocomplete works, type-safe access
+assert user.status == 'active'
+```
+
+### Status Code Validation
+
+```python
+self.validation.validate_status_code(response, 200)
+self.validation.validate_status_code(response, [200, 201])  # multiple acceptable
+```
+
+### Required Fields
+
+```python
+self.validation.validate_required_fields(
+    response.data,
+    ['id', 'name', 'email', 'created_at']
+)
+```
+
+### JSON Path Validation
+
+```python
+# Assert a field exists
+self.validation.validate_json_path(response.data, 'user.address.city')
+
+# Assert a specific value
+self.validation.validate_json_path(response.data, 'user.status', expected_value='active')
+
+# Nested array access: items[0].price
+self.validation.validate_json_path(response.data, 'items[0].price', expected_value=9.99)
+```
+
+### Type and Length Validation
+
+```python
+# Type check
+self.validation.validate_response_type(response.data, list)
+self.validation.validate_response_type(response.data, dict)
+
+# List length
+self.validation.validate_list_length(response.data, min_length=1)
+self.validation.validate_list_length(response.data, min_length=1, max_length=100)
+self.validation.validate_list_length(response.data, exact_length=10)
+```
+
+---
+
+## HTTP Configuration Presets
+
+Control retry and timeout behaviour with built-in presets:
+
+| Preset | Use Case | Retries | Timeout |
+|--------|----------|---------|---------|
+| `HTTPConfig.standard()` | Most API testing | 3 | 30 s |
+| `HTTPConfig.external_api()` | Third-party APIs (Stripe, AWS) | 5 | 60 s |
+| `HTTPConfig.local_api()` | Localhost / Docker | 1 | 10 s |
+| `HTTPConfig.testing()` | Fast unit tests | 1 | 5 s |
+
+```python
+from core.api.config import HTTPConfig
+
+client = BaseAPIClient(context.request, 'https://api.example.com',
+                       http_config=HTTPConfig.external_api())
+```
+
+Set the default preset via environment variable (applies to the `api_client` fixture):
+
+```bash
+HTTP_CONFIG_MODE=local_api   # Options: standard | external_api | local_api | testing
+```
+
+### Custom Configuration
+
+```python
+from core.api.config import HTTPConfig, RetryConfig, TimeoutConfig
+
+config = HTTPConfig(
+    retry=RetryConfig(max_attempts=5, initial_delay=2.0, max_delay=30.0),
+    timeout=TimeoutConfig(request_timeout=45.0, connect_timeout=10.0),
+    base_headers={'User-Agent': 'MyTestFramework/1.0'},
+)
+```
+
+---
+
+## conftest Fixtures
+
+### `api_client` (generic)
+
+Available in every test without any setup:
+
+```python
+async def test_create_resource(api_client):
+    api_client.set_bearer_token('my-token')
+    response = await api_client.post('/resources', data={'name': 'test'})
+    assert response.status_code == 201
+```
+
+### `context` (Playwright browser context)
+
+Used to create service-specific clients:
+
+```python
+@pytest_asyncio.fixture
+async def order_client(context):
+    return OrderServiceClient(
+        context.request,
+        base_url='https://orders.example.com',
+        auth_strategy=BearerTokenAuth.from_env(),
+    )
+```
+
+---
+
+## Complete Examples
+
+### Example 1: Full CRUD Test
+
+```python
+import pytest_asyncio
+from pydantic import BaseModel
+from core.api.base_client import BaseAPIClient
+from core.api.services.auth import BearerTokenAuth
+
+class Product(BaseModel):
+    id: int
+    name: str
+    price: float
+    in_stock: bool
+
+class ProductClient(BaseAPIClient):
+    async def create(self, name, price) -> Product:
+        r = await self.post('/products', data={'name': name, 'price': price})
+        return self.validation.validate_schema(r.data, Product)
+
+    async def get(self, pid) -> Product:
+        r = await self.get(f'/products/{pid}')
+        return self.validation.validate_schema(r.data, Product)
+
+    async def update(self, pid, **kw) -> Product:
+        r = await self.patch(f'/products/{pid}', data=kw)
+        return self.validation.validate_schema(r.data, Product)
+
+    async def delete(self, pid) -> None:
+        await self.delete(f'/products/{pid}')
+
+@pytest_asyncio.fixture
+async def products(context):
+    return ProductClient(
+        context.request,
+        base_url='https://api.example.com',
+        auth_strategy=BearerTokenAuth.from_env(),
+    )
+
+async def test_product_crud(products):
+    # CREATE
+    p = await products.create('Laptop', 999.99)
+    assert p.id > 0
+
+    # READ
+    fetched = await products.get(p.id)
+    assert fetched.name == 'Laptop'
+
+    # UPDATE
+    updated = await products.update(p.id, price=899.99)
+    assert updated.price == 899.99
+
+    # DELETE
+    await products.delete(p.id)
+```
+
+### Example 2: Pagination
+
+```python
+async def get_all_users(client: BaseAPIClient) -> list[dict]:
+    """Fetch all pages of users."""
+    all_users = []
+    page = 1
+    while True:
+        response = await client.get('/users', params={'page': page, 'per_page': 50})
+        data = response.data
+        if not data:
+            break
+        all_users.extend(data)
+        if len(data) < 50:
+            break
+        page += 1
+    return all_users
+
+async def test_all_users_are_active(api_client):
+    users = await get_all_users(api_client)
+    assert all(u['status'] == 'active' for u in users)
+```
+
+### Example 3: Performance Gate
+
+```python
+async def test_api_response_time(api_client):
+    response = await api_client.get('/health')
+    assert response.elapsed_ms < 500, (
+        f"Health check took {response.elapsed_ms}ms — SLA is 500ms"
+    )
+```
+
+---
+
+See [core/api/README.md](../core/api/README.md) for the full framework reference.
diff --git a/docs/DATABASE_TESTING.md b/docs/DATABASE_TESTING.md
new file mode 100644
index 0000000..36c82ae
--- /dev/null
+++ b/docs/DATABASE_TESTING.md
@@ -0,0 +1,340 @@
+# Database Testing Guide
+
+Complete guide for database and cache testing using the Playwright Python Async Framework.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Supported Databases](#supported-databases)
+- [Quick Start](#quick-start)
+- [DatabaseClient API](#databaseclient-api)
+- [Redis Testing](#redis-testing)
+- [Docker Setup](#docker-setup)
+- [Configuration Reference](#configuration-reference)
+- [Complete Examples](#complete-examples)
+
+---
+
+## Overview
+
+The framework ships with two helper clients:
+
+| Client | Module | Purpose |
+|--------|--------|---------|
+| `DatabaseClient` | `helpers/database.py` | PostgreSQL, MySQL, SQL Server, Oracle |
+| `RedisClient` | `helpers/redis_client.py` | Redis cache operations |
+
+Both clients are **async-first** and integrate with pytest via fixtures defined
+in `conftest.py`.
+
+---
+
+## Supported Databases
+
+The `DatabaseClient` uses **SQLAlchemy async** drivers:
+
+| Database | `DB_TYPE` value | Driver package |
+|----------|----------------|----------------|
+| PostgreSQL | `postgresql` | `asyncpg` (included) |
+| MySQL | `mysql` | `aiomysql` (included) |
+| SQL Server | `mssql` | `aioodbc` (install separately) |
+| Oracle | `oracle` | `cx_oracle_async` (install separately) |
+
+---
+
+## Quick Start
+
+### 1. Enable Database Testing
+
+Set environment variables in `.env`:
+
+```bash
+DB_TEST=true
+DB_TYPE=postgresql
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=testdb
+DB_USER=postgres
+DB_PASSWORD=password
+```
+
+### 2. Use the `db_client` Fixture
+
+The `db_client` fixture is defined in `conftest.py`. Tests that use it will
+**skip automatically** when `DB_TEST` is not `true`:
+
+```python
+async def test_user_exists(db_client):
+    user = await db_client.fetch_one(
+        "SELECT * FROM users WHERE email = :email",
+        {"email": "qa@example.com"},
+    )
+    assert user is not None
+    assert user["status"] == "active"
+```
+
+### 3. Start Infrastructure (Optional)
+
+Use Docker Compose for a ready-to-go database:
+
+```bash
+docker-compose --profile with-db up --abort-on-container-exit
+```
+
+---
+
+## DatabaseClient API
+
+### `fetch_one(query, params)` → `dict | None`
+
+Fetch a single row as a dictionary. Returns `None` if no rows match.
+
+```python
+user = await db_client.fetch_one(
+    "SELECT id, name, email, status FROM users WHERE id = :id",
+    {"id": 42},
+)
+assert user is not None
+assert user["status"] == "active"
+```
+
+### `fetch_all(query, params)` → `list[dict]`
+
+Fetch all matching rows as a list of dictionaries.
+
+```python
+active_users = await db_client.fetch_all(
+    "SELECT id, name FROM users WHERE status = :status",
+    {"status": "active"},
+)
+assert len(active_users) > 0
+```
+
+### `execute(query, params)` → result
+
+Execute an INSERT, UPDATE, or DELETE statement. Commits automatically.
+
+```python
+await db_client.execute(
+    "UPDATE users SET status = :status WHERE id = :id",
+    {"status": "inactive", "id": 42},
+)
+```
+
+### `session_maker()` — SQLAlchemy session
+
+For advanced ORM queries use the async session context manager directly:
+
+```python
+from sqlalchemy import text, select
+from sqlalchemy.orm import DeclarativeBase, mapped_column, Mapped
+
+class User(DeclarativeBase):
+    __tablename__ = "users"
+    id:     Mapped[int] = mapped_column(primary_key=True)
+    name:   Mapped[str]
+    email:  Mapped[str]
+    status: Mapped[str]
+
+async def test_orm_query(db_client):
+    async with db_client.session_maker() as session:
+        result = await session.execute(
+            select(User).where(User.status == "active").limit(10)
+        )
+        users = result.scalars().all()
+        assert len(users) > 0
+```
+
+---
+
+## Redis Testing
+
+### Configuration
+
+```bash
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_DB=0
+```
+
+### Using `RedisClient` in Tests
+
+```python
+from helpers.redis_client import RedisClient
+from utils.config import Config
+
+@pytest_asyncio.fixture
+async def redis():
+    cfg = Config.get_redis_config()
+    async with RedisClient(port=str(cfg["port"]), db=int(cfg["db"])) as client:
+        yield client
+```
+
+### RedisClient API
+
+```python
+# Basic operations
+await client.set("key", "value")
+raw = await client.get("key")           # Returns bytes or None
+value = raw.decode() if raw else None
+
+await client.delete("key")             # Returns count deleted
+exists = await client.exists("key")    # Returns 1 or 0
+
+# List keys
+keys = await client.list_keys("prefix:*")
+
+# Bulk get
+values = await client.mget(["key1", "key2", "key3"])
+
+# Context manager (auto-close)
+async with RedisClient() as client:
+    await client.set("temp", "value")
+```
+
+---
+
+## Docker Setup
+
+Start all services with Docker Compose:
+
+```bash
+# Start everything (tests + PostgreSQL + Redis)
+docker-compose --profile with-db --profile with-redis up --abort-on-container-exit
+
+# PostgreSQL only
+docker-compose --profile with-db up --abort-on-container-exit
+
+# Redis only
+docker-compose --profile with-redis up --abort-on-container-exit
+
+# Tests without external services
+docker-compose up --abort-on-container-exit
+
+# Cleanup
+docker-compose down -v
+```
+
+---
+
+## Configuration Reference
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DB_TEST` | `false` | Set `true` to enable database tests |
+| `DB_TYPE` | `postgresql` | `postgresql` \| `mysql` \| `mssql` \| `oracle` |
+| `DB_HOST` | `localhost` | Database host |
+| `DB_PORT` | `5432` | Database port |
+| `DB_NAME` | `testdb` | Database name |
+| `DB_USER` | `postgres` | Database username |
+| `DB_PASSWORD` | `password` | Database password |
+| `REDIS_HOST` | `localhost` | Redis host |
+| `REDIS_PORT` | `6379` | Redis port |
+| `REDIS_DB` | `0` | Redis database number (0–15) |
+
+---
+
+## Complete Examples
+
+### Example 1: Data Integrity Validation
+
+```python
+async def test_order_creates_inventory_record(db_client):
+    """After creating an order via UI/API, verify database state."""
+    order_id = "ORD-2024-001"
+
+    # Verify order exists
+    order = await db_client.fetch_one(
+        "SELECT * FROM orders WHERE order_ref = :ref",
+        {"ref": order_id},
+    )
+    assert order is not None
+    assert order["status"] == "pending"
+
+    # Verify inventory was decremented
+    inv = await db_client.fetch_one(
+        "SELECT stock_count FROM inventory WHERE product_id = :pid",
+        {"pid": order["product_id"]},
+    )
+    assert inv["stock_count"] >= 0
+```
+
+### Example 2: Test Data Setup and Teardown
+
+```python
+import pytest
+
+@pytest.fixture
+async def test_user(db_client):
+    """Create a user for the test and remove it afterwards."""
+    await db_client.execute(
+        "INSERT INTO users (name, email, status) VALUES (:name, :email, :status)",
+        {"name": "Test User", "email": "test_fixture@example.com", "status": "active"},
+    )
+    user = await db_client.fetch_one(
+        "SELECT * FROM users WHERE email = :email",
+        {"email": "test_fixture@example.com"},
+    )
+    yield user
+    await db_client.execute(
+        "DELETE FROM users WHERE id = :id",
+        {"id": user["id"]},
+    )
+
+async def test_user_profile(db_client, test_user):
+    """Test using the pre-created test user."""
+    fetched = await db_client.fetch_one(
+        "SELECT * FROM users WHERE id = :id",
+        {"id": test_user["id"]},
+    )
+    assert fetched["name"] == "Test User"
+```
+
+### Example 3: Redis Cache Verification
+
+```python
+async def test_session_stored_in_redis(redis_client, page, login):
+    """After login, verify that the session token is cached in Redis."""
+    from utils.config import Config
+
+    await login(Config.get_test_username(), Config.get_test_password(), Config.get_base_url())
+
+    # Extract token from browser storage
+    token = await page.evaluate("localStorage.getItem('authToken')")
+    assert token
+
+    # Verify Redis has the session
+    session_data = await redis_client.get(f"session:{token}")
+    assert session_data is not None
+    assert json.loads(session_data.decode())["user_id"] > 0
+```
+
+### Example 4: Cross-Layer Validation (UI + DB)
+
+```python
+async def test_registration_persists_to_database(page, db_client):
+    """Register via UI, then confirm the user exists in the database."""
+    from tests.test_ui_examples import RegistrationPage
+    from utils.test_helpers import TestDataGenerator
+
+    email = TestDataGenerator.random_email()
+
+    reg = RegistrationPage(page)
+    await page.goto('https://app.example.com/register')
+    await reg.register(email=email)
+    await reg.validation.assert_visible('#successBanner')
+
+    # Cross-check with database
+    user = await db_client.fetch_one(
+        "SELECT id, email, status FROM users WHERE email = :email",
+        {"email": email},
+    )
+    assert user is not None
+    assert user["status"] == "active"
+```
+
+---
+
+See the `tests/test_database_examples.py` file for runnable examples.
diff --git a/docs/UI_TESTING.md b/docs/UI_TESTING.md
new file mode 100644
index 0000000..64ce032
--- /dev/null
+++ b/docs/UI_TESTING.md
@@ -0,0 +1,482 @@
+# UI Testing Guide
+
+Complete guide for UI automation using the Playwright Python Async Framework.
+
+> **Quick reference?** See [core/ui/README.md](../core/ui/README.md)  
+> **AI-powered healing?** See [core/ui/ai/README.md](../core/ui/ai/README.md)
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Page Object Model](#page-object-model)
+- [Form Interactions](#form-interactions)
+- [Validation](#validation)
+- [Browser Services](#browser-services)
+- [Components Reference](#components-reference)
+- [Test Markers](#test-markers)
+- [Configuration](#configuration)
+- [Complete Examples](#complete-examples)
+
+---
+
+## Overview
+
+The UI testing layer is built on top of **Playwright** and follows the **Page Object Model (POM)** pattern. Every page object inherits from `BasePage`, which provides lazy-loaded services and convenience shortcuts.
+
+```
+BasePage
+├── fill_data()          ← Auto-detecting form filler
+├── edit_item()          ← Clear + refill
+├── validate_edit_view() ← Assert form field values
+├── validate_details_view() ← Assert read-only view
+│
+├── Services (accessed via self.<service>)
+│   ├── attribute        ← DOM attribute manipulation
+│   ├── element_resolver ← Element resolution & metadata
+│   ├── strategy_factory ← Form-filling strategies
+│   ├── screenshot       ← Evidence capture
+│   ├── storage          ← LocalStorage / SessionStorage / Cookies
+│   ├── tab_window       ← Multi-tab management
+│   ├── validation       ← Element assertions
+│   └── wait             ← Page-load waiting
+```
+
+---
+
+## Page Object Model
+
+### Creating a Page Object
+
+Every page object must inherit from `BasePage` and call `super().__init__(page)`:
+
+```python
+from playwright.async_api import Page
+from core.ui.base_page import BasePage
+
+class ProductPage(BasePage):
+    def __init__(self, page: Page):
+        super().__init__(page)          # Required!
+
+        # Define selectors as instance variables
+        self.search_input   = '#search'
+        self.search_button  = '#searchBtn'
+        self.results_list   = '.results-item'
+        self.add_to_cart    = '[data-testid="add-cart"]'
+
+    async def search(self, query: str) -> None:
+        await self.fill_data({self.search_input: query})
+        await self.page.click(self.search_button)
+        await self.wait.wait_for_page_load()
+
+    async def result_count(self) -> int:
+        return await self.page.locator(self.results_list).count()
+```
+
+### Using in Tests
+
+```python
+async def test_product_search(page):
+    await page.goto('https://shop.example.com/products')
+    product_page = ProductPage(page)
+
+    await product_page.search('laptop')
+
+    count = await product_page.result_count()
+    assert count > 0
+```
+
+---
+
+## Form Interactions
+
+### `fill_data()` — Create / Fill
+
+Automatically detects the field type and uses the correct interaction strategy:
+
+```python
+await self.fill_data({
+    '#name':            'John Doe',           # Text input
+    '#email':           'john@example.com',   # Email input
+    '#age':             '30',                 # Number input
+    '#department':      'Engineering',        # <select> dropdown
+    '#country':         'United States',      # Select2 dropdown
+    '#active':          True,                 # Checkbox (check)
+    '#premium':         False,                # Checkbox (uncheck)
+    '#employment':      'full-time',          # Radio button (by value)
+    '#start_date':      '2024-01-15',         # Date picker (YYYY-MM-DD)
+    '#resume':          '/abs/path/file.pdf', # File upload (absolute path)
+    '#submit':          'click',              # Button click
+    '.benefits':        ['Health', 'Dental'], # Multiple checkboxes
+})
+```
+
+### `edit_item()` — Clear and Refill
+
+Clears existing values before filling. Use this when editing a form:
+
+```python
+await self.edit_item({
+    '#name':       'Jane Smith',
+    '#department': 'Marketing',
+})
+```
+
+### `validate_edit_view()` — Assert Form Field Values
+
+Checks that form fields contain the expected values:
+
+```python
+await self.validate_edit_view({
+    '#name':       'Jane Smith',
+    '#department': 'Marketing',
+    '#active':     True,
+})
+```
+
+### `validate_details_view()` — Assert Read-Only View
+
+Checks that container elements display expected text:
+
+```python
+await self.validate_details_view({
+    '#div_id_name':       'Jane Smith',
+    '#div_id_department': 'Marketing',
+    '#div_id_email':      'jane@example.com',
+})
+```
+
+---
+
+## Validation
+
+The `validation` service provides assertion helpers:
+
+```python
+# Element state
+await self.validation.assert_visible('#successMessage')
+await self.validation.assert_not_visible('#errorMessage')
+
+# Checkbox state
+await self.validation.assert_checked('#agreeTerms')
+await self.validation.assert_not_checked('#newsletter')
+
+# Input value
+await self.validation.assert_value('#username', 'john_doe')
+
+# Message content
+await self.validation.validate_message('#flash', 'Saved successfully', exact=False)
+
+# Details view (shortcut to validate_details_view)
+await self.validation.validate_record_information_in_details_view({
+    '#div_id_name': 'John Doe',
+})
+```
+
+---
+
+## Browser Services
+
+### `wait` — Smart Page Loading
+
+```python
+# Wait for page to finish loading (networkidle with domcontentloaded fallback)
+await self.wait.wait_for_page_load()
+
+# With custom timeout (milliseconds)
+await self.wait.wait_for_page_load(timeout=60_000)
+```
+
+For element-level waits, use Playwright directly:
+
+```python
+await self.page.locator('#result').wait_for(state='visible', timeout=10_000)
+```
+
+### `screenshot` — Evidence Capture
+
+```python
+# Full-page screenshot (auto-timestamped, saved to screenshots/)
+await self.screenshot.take_screenshot('before_submit')
+
+# Element screenshot
+await self.screenshot.take_element_screenshot('#error-banner', 'error_state')
+```
+
+### `storage` — Browser Storage
+
+```python
+# LocalStorage
+await self.storage.set_local_storage('theme', 'dark')
+theme = await self.storage.get_local_storage('theme')
+await self.storage.clear_local_storage()
+
+# SessionStorage
+await self.storage.set_session_storage('temp_id', '42')
+value = await self.storage.get_session_storage('temp_id')
+
+# Cookies
+await self.storage.add_cookie({'name': 'session', 'value': 'abc123', 'url': 'https://app.com'})
+cookies = await self.storage.get_all_cookies()
+await self.storage.clear_cookies()
+```
+
+### `tab_window` — Multi-Tab Management
+
+```python
+# Wait for a new tab to open after an action and switch to it
+new_page = await self.tab_window.wait_for_new_tab_and_switch(
+    lambda: self.page.click('#open-report')
+)
+
+# Close the current tab and switch to the previous one
+await self.tab_window.close_current_tab()
+
+# Refresh the page
+await self.tab_window.refresh_page()
+
+# Navigate browser history
+await self.tab_window.go_back()
+await self.tab_window.go_forward()
+
+# Handle confirm/alert dialogs
+message = await self.tab_window.handle_confirmation_dialog(
+    trigger_action=lambda: self.page.click('#delete-btn'),
+    accept=True,
+    dialog_text='Are you sure?',
+)
+```
+
+### `attribute` — DOM Attribute Manipulation
+
+Useful for bypassing client-side validation to test server-side behaviour:
+
+```python
+# Remove HTML5 required constraint to submit empty value
+await self.attribute.remove_attribute('#email', 'required')
+
+# Remove pattern validation
+await self.attribute.remove_attribute('#phone', 'pattern')
+
+# Set an attribute
+await self.attribute.set_attribute('#input', 'maxlength', '200')
+
+# ARIA attributes
+await self.attribute.remove_attribute('#field', 'aria-required')
+```
+
+---
+
+## Components Reference
+
+Components provide advanced control over specific element types. Access them
+directly when `fill_data()` is insufficient:
+
+```python
+from core.ui.components.file  import FileComponent
+from core.ui.components.table import TableComponent
+from core.ui.components.modal import ModalComponent
+
+class MyPage(BasePage):
+
+    def get_file_upload(self) -> FileComponent:
+        return FileComponent(self.page, '#resume')
+
+    def get_results_table(self) -> TableComponent:
+        return TableComponent(self.page, '#resultsTable')
+
+    async def upload_with_preview(self, path: str) -> None:
+        fc = self.get_file_upload()
+        await fc.upload_files_with_preview_validation(
+            file_paths=[path],
+            preview_element='.file-preview',
+            timeout=10_000,
+        )
+
+    async def row_count(self) -> int:
+        table = self.get_results_table()
+        rows = await table.get_rows()
+        return await rows.count()
+```
+
+---
+
+## Test Markers
+
+Use pytest markers to categorise tests and run targeted subsets:
+
+```python
+import pytest
+
+@pytest.mark.smoke_test
+async def test_login(page):
+    """Critical path — must pass before deeper tests."""
+    ...
+
+@pytest.mark.regression
+async def test_form_validation(page):
+    """Full regression coverage."""
+    ...
+
+@pytest.mark.integration
+async def test_ui_plus_api(page, api_client):
+    """Tests that combine UI and API layers."""
+    ...
+
+@pytest.mark.slow
+@pytest.mark.regression
+async def test_bulk_upload(page):
+    """Slow test — excluded from quick runs."""
+    ...
+```
+
+Running subsets:
+
+```bash
+pytest -m smoke_test          # Smoke tests only
+pytest -m "regression and not slow"   # Fast regression
+pytest -m integration         # Integration tests only
+```
+
+---
+
+## Configuration
+
+All browser settings are controlled via environment variables (`.env`):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BASE_URL` | `http://localhost:8000` | Application URL |
+| `BROWSER` | `chromium` | `chromium` \| `firefox` \| `webkit` |
+| `HEADLESS` | `true` | Run without a visible window |
+| `VIEWPORT_WIDTH` | `1920` | Browser width in pixels |
+| `VIEWPORT_HEIGHT` | `1080` | Browser height in pixels |
+| `TIMEOUT` | `30000` | Default element timeout (ms) |
+| `SCREENSHOT_ON_FAILURE` | `true` | Auto-capture screenshot on failure |
+| `SCREENSHOTS_DIR` | `screenshots` | Directory to save screenshots |
+| `TEST_MODE` | `local` | `local` \| `debug` (slow motion) |
+| `CI` | `false` | Set `true` in CI/CD pipelines |
+| `PYTEST_WORKERS` | `auto` | Parallel worker count |
+
+---
+
+## Complete Examples
+
+### Example 1: Registration Form
+
+```python
+from core.ui.base_page import BasePage
+from utils.test_helpers import TestDataGenerator
+
+class RegistrationPage(BasePage):
+    def __init__(self, page):
+        super().__init__(page)
+        self.first_name    = '#firstName'
+        self.last_name     = '#lastName'
+        self.email         = '#email'
+        self.password      = '#password'
+        self.agree_terms   = '#agreeTerms'
+        self.submit        = '#submitBtn'
+
+    def generate_user_data(self, **overrides):
+        return {
+            self.first_name:  overrides.get('first_name', TestDataGenerator.random_name('first')),
+            self.last_name:   overrides.get('last_name',  TestDataGenerator.random_name('last')),
+            self.email:       overrides.get('email',      TestDataGenerator.random_email()),
+            self.password:    overrides.get('password',   TestDataGenerator.random_password()),
+            self.agree_terms: True,
+        }
+
+    async def register(self, **overrides):
+        data = self.generate_user_data(**overrides)
+        await self.fill_data(data)
+        await self.page.click(self.submit)
+        return data
+
+async def test_user_registration(page):
+    reg = RegistrationPage(page)
+    await page.goto('https://app.example.com/register')
+
+    user_data = await reg.register(email='qa+test@example.com')
+
+    await reg.validation.assert_visible('#successBanner')
+```
+
+### Example 2: Full CRUD Workflow
+
+```python
+from core.ui.base_page import BasePage
+from utils.test_helpers import TestDataGenerator
+
+class EmployeePage(BasePage):
+    def __init__(self, page):
+        super().__init__(page)
+        # Form selectors
+        self.name     = '#name'
+        self.email    = '#email'
+        self.dept     = '#department'
+        # Details view selectors
+        self.name_d   = '#div_id_name'
+        self.email_d  = '#div_id_email'
+        self.dept_d   = '#div_id_department'
+        # Stored data
+        self.form_data    = {}
+        self.details_data = {}
+
+    def generate_data(self, **kw):
+        name  = kw.get('name',  TestDataGenerator.random_name())
+        email = kw.get('email', TestDataGenerator.random_email())
+        dept  = kw.get('dept',  'Engineering')
+        self.form_data    = {self.name: name, self.email: email, self.dept: dept}
+        self.details_data = {self.name_d: name, self.email_d: email, self.dept_d: dept}
+        return self.form_data, self.details_data
+
+    async def create(self, **kw):
+        form_data, _ = self.generate_data(**kw)
+        await self.fill_data(form_data)
+        await self.page.click('#submit')
+
+    async def edit(self, **kw):
+        form_data, _ = self.generate_data(**kw)
+        await self.edit_item(form_data)
+        await self.page.click('#submit')
+
+    async def assert_edit_view(self):
+        await self.validate_edit_view(self.form_data)
+
+    async def assert_details_view(self):
+        await self.validate_details_view(self.details_data)
+
+async def test_employee_crud(page):
+    emp = EmployeePage(page)
+    await page.goto('https://app.example.com/employees')
+
+    # CREATE
+    await page.click('#addEmployee')
+    await emp.create(name='Alice Johnson')
+
+    # READ — details view
+    await page.click('a:has-text("Alice Johnson")')
+    await emp.assert_details_view()
+
+    # UPDATE
+    await page.click('#editBtn')
+    await emp.edit(dept='Marketing')
+
+    # Validate edit form
+    await page.click('#editBtn')
+    await emp.assert_edit_view()
+
+    # DELETE
+    await page.click('#deleteBtn')
+    await emp.tab_window.handle_confirmation_dialog(
+        trigger_action=lambda: None,
+        accept=True,
+    )
+    await emp.validation.assert_not_visible('tr:has-text("Alice Johnson")')
+```
+
+---
+
+See [core/ui/README.md](../core/ui/README.md) for the full framework reference.
diff --git a/services/__init__.py b/services/__init__.py
new file mode 100644
index 0000000..548df63
--- /dev/null
+++ b/services/__init__.py
@@ -0,0 +1,6 @@
+"""
+Services package.
+
+Contains base page objects and service-layer page objects
+that are shared across test suites.
+"""
diff --git a/services/base_pages/__init__.py b/services/base_pages/__init__.py
new file mode 100644
index 0000000..97bfa50
--- /dev/null
+++ b/services/base_pages/__init__.py
@@ -0,0 +1,3 @@
+"""
+Base page objects shared across all test suites.
+"""
diff --git a/services/base_pages/login_page.py b/services/base_pages/login_page.py
new file mode 100644
index 0000000..809d6b6
--- /dev/null
+++ b/services/base_pages/login_page.py
@@ -0,0 +1,77 @@
+"""
+Generic login page object.
+
+Provides a reusable login page that navigates to a URL and fills
+standard username/password credentials. Override selectors in your
+own subclass to match the specific application under test.
+"""
+
+import logging
+
+from playwright.async_api import Page
+
+from core.ui.base_page import BasePage
+
+logger = logging.getLogger(__name__)
+
+
+class LoginPage(BasePage):
+    """
+    Generic login page for common username/password flows.
+
+    Override the selector class attributes in a subclass when your
+    application uses different element identifiers.
+
+    Example — default selectors::
+
+        login_page = LoginPage(page)
+        await login_page.login("user", "pass", "https://app.example.com/login")
+
+    Example — custom selectors::
+
+        class MyAppLoginPage(LoginPage):
+            username_input = '[data-testid="username"]'
+            password_input = '[data-testid="password"]'
+            login_button   = '[data-testid="submit"]'
+    """
+
+    # Override these in a subclass to match your application's selectors.
+    username_input: str = "#username"
+    password_input: str = "#password"
+    login_button: str = '[type="submit"]'
+
+    def __init__(self, page: Page) -> None:
+        super().__init__(page)
+
+    async def login(self, username: str, password: str, url: str) -> None:
+        """
+        Navigate to *url* and perform a username/password login.
+
+        Args:
+            username: The username (or email) to log in with.
+            password: The corresponding password.
+            url: Full URL of the login page (e.g. ``https://app.com/login``).
+
+        Example::
+
+            await login_page.login(
+                Config.get_test_username(),
+                Config.get_test_password(),
+                f"{Config.get_base_url()}/login",
+            )
+        """
+        logger.info(f"Navigating to login page: {url}")
+        await self.page.goto(url)
+        await self.wait.wait_for_page_load()
+
+        logger.debug(f"Filling credentials for user: {username}")
+        await self.fill_data(
+            {
+                self.username_input: username,
+                self.password_input: password,
+            }
+        )
+
+        await self.page.click(self.login_button)
+        await self.wait.wait_for_page_load()
+        logger.info("Login submitted successfully")
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 0000000..46816dd
--- /dev/null
+++ b/tests/__init__.py
@@ -0,0 +1 @@
+"""Tests package."""
diff --git a/tests/test_api_examples.py b/tests/test_api_examples.py
new file mode 100644
index 0000000..7c48324
--- /dev/null
+++ b/tests/test_api_examples.py
@@ -0,0 +1,386 @@
+"""
+API Testing Examples
+====================
+
+Demonstrates how to use the framework's API client for REST API testing.
+
+All examples target https://jsonplaceholder.typicode.com (a free fake REST API)
+so they can be run without a private backend.
+
+Run::
+
+    pytest tests/test_api_examples.py -v
+"""
+
+import pytest
+import pytest_asyncio
+from playwright.async_api import BrowserContext
+from pydantic import BaseModel
+
+from core.api.base_client import BaseAPIClient
+from core.api.config import HTTPConfig
+from core.api.services.auth import APIKeyAuth, BasicAuth, BearerTokenAuth, CompositeAuth, CustomHeaderAuth
+from utils.config import Config
+
+# ---------------------------------------------------------------------------
+# Pydantic models for response validation
+# ---------------------------------------------------------------------------
+
+BASE_URL = "https://jsonplaceholder.typicode.com"
+
+
+class Post(BaseModel):
+    """JSONPlaceholder post schema."""
+
+    userId: int
+    id: int
+    title: str
+    body: str
+
+
+class Comment(BaseModel):
+    """JSONPlaceholder comment schema."""
+
+    postId: int
+    id: int
+    name: str
+    email: str
+    body: str
+
+
+class CreatePostResponse(BaseModel):
+    """Response schema for post creation (JSONPlaceholder fakes 201)."""
+
+    id: int
+    title: str
+    body: str
+    userId: int
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest_asyncio.fixture
+async def posts_client(context: BrowserContext) -> BaseAPIClient:
+    """API client pre-configured for JSONPlaceholder."""
+    return BaseAPIClient(
+        context.request,
+        base_url=BASE_URL,
+        http_config=HTTPConfig.standard(),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Tests — GET requests
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.smoke_test
+async def test_get_all_posts(posts_client: BaseAPIClient) -> None:
+    """
+    Smoke test: GET /posts returns a non-empty list of posts.
+
+    Demonstrates:
+    - BaseAPIClient.get() with no authentication
+    - response.is_success check
+    - validate_response_type for list responses
+    """
+    response = await posts_client.get("/posts")
+
+    assert response.is_success
+    posts_client.validation.validate_response_type(response.data, list)
+    posts_client.validation.validate_list_length(response.data, min_length=1)
+
+
+@pytest.mark.smoke_test
+async def test_get_single_post(posts_client: BaseAPIClient) -> None:
+    """
+    Smoke test: GET /posts/1 returns a correctly-shaped post.
+
+    Demonstrates:
+    - validate_schema() with a Pydantic model for type-safe access
+    - JSON path validation
+    """
+    response = await posts_client.get("/posts/1")
+
+    assert response.is_success
+    post = posts_client.validation.validate_schema(response.data, Post)
+    assert post.id == 1
+    assert post.userId > 0
+    assert post.title
+
+
+@pytest.mark.regression
+async def test_get_posts_with_query_params(posts_client: BaseAPIClient) -> None:
+    """
+    Regression test: filter posts by userId query parameter.
+
+    Demonstrates:
+    - Query parameters via the params argument
+    - Filtering and counting results
+    """
+    response = await posts_client.get("/posts", params={"userId": 1})
+
+    assert response.is_success
+    posts_client.validation.validate_response_type(response.data, list)
+    for post_data in response.data:
+        assert post_data["userId"] == 1
+
+
+@pytest.mark.regression
+async def test_get_post_comments(posts_client: BaseAPIClient) -> None:
+    """
+    Regression test: retrieve comments for a specific post.
+
+    Demonstrates:
+    - Nested resource endpoints
+    - Schema validation on a list of items
+    """
+    response = await posts_client.get("/posts/1/comments")
+
+    assert response.is_success
+    assert len(response.data) > 0
+    comment = posts_client.validation.validate_schema(response.data[0], Comment)
+    assert comment.postId == 1
+
+
+# ---------------------------------------------------------------------------
+# Tests — POST / PUT / PATCH / DELETE
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.regression
+async def test_create_post(posts_client: BaseAPIClient) -> None:
+    """
+    Regression test: POST /posts creates a new resource.
+
+    Demonstrates:
+    - post() with a JSON body
+    - 201 status code assertion
+    - Schema validation of the created resource
+    """
+    response = await posts_client.post(
+        "/posts",
+        data={"title": "Test Post", "body": "Framework example", "userId": 1},
+        expected_status=201,
+    )
+
+    assert response.status_code == 201
+    created = posts_client.validation.validate_schema(response.data, CreatePostResponse)
+    assert created.title == "Test Post"
+    assert created.id > 0
+
+
+@pytest.mark.regression
+async def test_update_post_put(posts_client: BaseAPIClient) -> None:
+    """
+    Regression test: PUT /posts/1 performs a full update.
+
+    Demonstrates:
+    - put() for full resource replacement
+    - 200 status on update
+    """
+    response = await posts_client.put(
+        "/posts/1",
+        data={"id": 1, "title": "Updated Title", "body": "Updated body", "userId": 1},
+    )
+
+    assert response.is_success
+    assert response.data["title"] == "Updated Title"
+
+
+@pytest.mark.regression
+async def test_patch_post(posts_client: BaseAPIClient) -> None:
+    """
+    Regression test: PATCH /posts/1 performs a partial update.
+
+    Demonstrates:
+    - patch() for partial resource updates
+    - Only the changed field is sent in the request body
+    """
+    response = await posts_client.patch("/posts/1", data={"title": "Patched Title"})
+
+    assert response.is_success
+    assert response.data["title"] == "Patched Title"
+
+
+@pytest.mark.regression
+async def test_delete_post(posts_client: BaseAPIClient) -> None:
+    """
+    Regression test: DELETE /posts/1 removes the resource.
+
+    Demonstrates:
+    - delete() with 200 status (JSONPlaceholder returns 200 not 204)
+    """
+    response = await posts_client.delete("/posts/1", expected_status=200)
+
+    assert response.is_success
+
+
+# ---------------------------------------------------------------------------
+# Tests — Response validation helpers
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.regression
+async def test_validate_required_fields(posts_client: BaseAPIClient) -> None:
+    """
+    Regression test: validate required fields are present in the response.
+
+    Demonstrates:
+    - validate_required_fields() for presence checks
+    """
+    response = await posts_client.get("/posts/1")
+
+    posts_client.validation.validate_required_fields(
+        response.data, ["id", "userId", "title", "body"]
+    )
+
+
+@pytest.mark.regression
+async def test_validate_json_path(posts_client: BaseAPIClient) -> None:
+    """
+    Regression test: JSON path assertion on nested response data.
+
+    Demonstrates:
+    - validate_json_path() for deep value checks
+    """
+    response = await posts_client.get("/posts/1")
+
+    posts_client.validation.validate_json_path(response.data, "id", expected_value=1)
+    posts_client.validation.validate_json_path(response.data, "userId", expected_value=1)
+
+
+@pytest.mark.regression
+async def test_response_elapsed_time(posts_client: BaseAPIClient) -> None:
+    """
+    Regression test: verify response time is within acceptable bounds.
+
+    Demonstrates:
+    - response.elapsed_ms for performance assertions
+    """
+    response = await posts_client.get("/posts/1")
+
+    assert response.elapsed_ms > 0
+    # Performance gate: should respond within 10 seconds
+    assert response.elapsed_ms < 10_000
+
+
+# ---------------------------------------------------------------------------
+# Tests — Authentication strategies
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+async def test_bearer_token_auth_headers() -> None:
+    """
+    Unit test: BearerTokenAuth adds the correct Authorization header.
+
+    Demonstrates:
+    - BearerTokenAuth strategy
+    - Direct header inspection
+    """
+    auth = BearerTokenAuth(token="test-jwt-token-abc123")
+    headers = await auth.get_auth_headers()
+
+    assert headers["Authorization"] == "Bearer test-jwt-token-abc123"
+
+
+@pytest.mark.unit
+async def test_api_key_auth_headers() -> None:
+    """
+    Unit test: APIKeyAuth adds the API key in the specified header.
+
+    Demonstrates:
+    - APIKeyAuth with a custom header name
+    """
+    auth = APIKeyAuth(api_key="sk_test_123456", header_name="X-API-Key")
+    headers = await auth.get_auth_headers()
+
+    assert headers["X-API-Key"] == "sk_test_123456"
+
+
+@pytest.mark.unit
+async def test_basic_auth_headers() -> None:
+    """
+    Unit test: BasicAuth encodes credentials as Base64.
+
+    Demonstrates:
+    - BasicAuth strategy
+    - Presence of Authorization header
+    """
+    auth = BasicAuth(username="admin", password="secret")
+    headers = await auth.get_auth_headers()
+
+    assert "Authorization" in headers
+    assert headers["Authorization"].startswith("Basic ")
+
+
+@pytest.mark.unit
+async def test_custom_header_auth() -> None:
+    """
+    Unit test: CustomHeaderAuth injects arbitrary headers.
+
+    Demonstrates:
+    - CustomHeaderAuth for non-standard auth schemes
+    """
+    auth = CustomHeaderAuth(headers={"X-Tenant-ID": "tenant-42", "X-API-Version": "v2"})
+    headers = await auth.get_auth_headers()
+
+    assert headers["X-Tenant-ID"] == "tenant-42"
+    assert headers["X-API-Version"] == "v2"
+
+
+@pytest.mark.unit
+async def test_composite_auth_merges_headers() -> None:
+    """
+    Unit test: CompositeAuth merges headers from multiple strategies.
+
+    Demonstrates:
+    - CompositeAuth for combining authentication strategies
+    """
+    auth = CompositeAuth(
+        [
+            BearerTokenAuth(token="jwt-abc"),
+            CustomHeaderAuth(headers={"X-Tenant-ID": "tenant-1"}),
+        ]
+    )
+    headers = await auth.get_auth_headers()
+
+    assert headers["Authorization"] == "Bearer jwt-abc"
+    assert headers["X-Tenant-ID"] == "tenant-1"
+
+
+# ---------------------------------------------------------------------------
+# Tests — set_* convenience methods on BaseAPIClient
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+async def test_set_bearer_token_on_client(context: BrowserContext) -> None:
+    """
+    Unit test: set_bearer_token() configures the client's auth strategy.
+
+    Demonstrates:
+    - Programmatic auth configuration after client creation
+    - This test does need a context to create a BaseAPIClient
+    """
+    client = BaseAPIClient(context.request, BASE_URL)
+    client.set_bearer_token("runtime-token-xyz")
+
+    headers = await client._auth_strategy.get_auth_headers()
+    assert headers["Authorization"] == "Bearer runtime-token-xyz"
+
+
+@pytest.mark.unit
+async def test_set_api_key_on_client(context: BrowserContext) -> None:
+    """
+    Unit test: set_api_key() configures the client's auth strategy.
+    """
+    client = BaseAPIClient(context.request, BASE_URL)
+    client.set_api_key("api-key-value", header_name="X-API-Key")
+
+    headers = await client._auth_strategy.get_auth_headers()
+    assert headers["X-API-Key"] == "api-key-value"
diff --git a/tests/test_crud_example.py b/tests/test_crud_example.py
new file mode 100644
index 0000000..67c86b8
--- /dev/null
+++ b/tests/test_crud_example.py
@@ -0,0 +1,284 @@
+"""
+Complete CRUD Example
+=====================
+
+Demonstrates a full end-to-end CRUD workflow combining UI and API testing.
+
+UI target: https://the-internet.herokuapp.com (free public test site)
+API target: https://jsonplaceholder.typicode.com (free fake REST API)
+
+This example shows the recommended patterns for:
+- Page Object Model with BasePage
+- TestDataGenerator for consistent, random test data
+- API client + service client pattern
+- Hybrid tests that mix UI navigation with API verification
+
+Run::
+
+    pytest tests/test_crud_example.py -v
+"""
+
+import pytest
+import pytest_asyncio
+from playwright.async_api import BrowserContext, Page
+from pydantic import BaseModel
+
+from core.api.base_client import BaseAPIClient
+from core.ui.base_page import BasePage
+from utils.test_helpers import TestDataGenerator
+
+# ---------------------------------------------------------------------------
+# Pydantic models
+# ---------------------------------------------------------------------------
+
+
+class Post(BaseModel):
+    """JSONPlaceholder post."""
+
+    userId: int
+    id: int
+    title: str
+    body: str
+
+
+# ---------------------------------------------------------------------------
+# Page Objects
+# ---------------------------------------------------------------------------
+
+
+class LoginPage(BasePage):
+    """Heroku test app login page."""
+
+    username_input = "#username"
+    password_input = "#password"
+    submit_button = '[type="submit"]'
+
+    async def login(self, username: str, password: str) -> None:
+        """Fill and submit login form."""
+        await self.fill_data(
+            {
+                self.username_input: username,
+                self.password_input: password,
+            }
+        )
+        await self.page.click(self.submit_button)
+        await self.wait.wait_for_page_load()
+
+
+class SecurePage(BasePage):
+    """Heroku secure area page."""
+
+    heading = "h2"
+    logout_link = "a[href='/logout']"
+
+    async def get_heading(self) -> str:
+        """Return the page heading text."""
+        return await self.page.locator(self.heading).inner_text()
+
+    async def logout(self) -> None:
+        """Click the logout link."""
+        await self.page.click(self.logout_link)
+        await self.wait.wait_for_page_load()
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest_asyncio.fixture
+async def api_client(context: BrowserContext) -> BaseAPIClient:
+    """API client for JSONPlaceholder."""
+    return BaseAPIClient(context.request, base_url="https://jsonplaceholder.typicode.com")
+
+
+# ---------------------------------------------------------------------------
+# CRUD Tests — API layer
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.regression
+async def test_api_create_read_update_delete(api_client: BaseAPIClient) -> None:
+    """
+    Regression test: full CRUD lifecycle via REST API.
+
+    Demonstrates:
+    - POST → validate created resource
+    - GET → validate retrieved resource
+    - PUT → validate full update
+    - PATCH → validate partial update
+    - DELETE → validate removal
+    """
+    # --- CREATE ---
+    title = TestDataGenerator.random_string(12)
+    body = TestDataGenerator.random_string(50)
+
+    create_resp = await api_client.post(
+        "/posts",
+        data={"title": title, "body": body, "userId": 1},
+        expected_status=201,
+    )
+    assert create_resp.status_code == 201
+    created_id = create_resp.data["id"]
+
+    # --- READ (list) ---
+    list_resp = await api_client.get("/posts", params={"userId": 1})
+    assert list_resp.is_success
+    api_client.validation.validate_list_length(list_resp.data, min_length=1)
+
+    # --- READ (single) ---
+    read_resp = await api_client.get("/posts/1")
+    post = api_client.validation.validate_schema(read_resp.data, Post)
+    assert post.id == 1
+
+    # --- UPDATE (full) ---
+    updated_title = TestDataGenerator.random_string(12)
+    put_resp = await api_client.put(
+        "/posts/1",
+        data={"id": 1, "title": updated_title, "body": body, "userId": 1},
+    )
+    assert put_resp.is_success
+    assert put_resp.data["title"] == updated_title
+
+    # --- UPDATE (partial) ---
+    patch_title = TestDataGenerator.random_string(12)
+    patch_resp = await api_client.patch("/posts/1", data={"title": patch_title})
+    assert patch_resp.is_success
+    assert patch_resp.data["title"] == patch_title
+
+    # --- DELETE ---
+    del_resp = await api_client.delete(f"/posts/{created_id}", expected_status=200)
+    assert del_resp.is_success
+
+
+# ---------------------------------------------------------------------------
+# CRUD Tests — UI layer
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.regression
+async def test_ui_login_and_secure_area(page: Page) -> None:
+    """
+    Regression test: full UI login → secure area → logout flow.
+
+    Demonstrates:
+    - Page Object Model with BasePage
+    - fill_data() for forms
+    - validation service
+    - TestDataGenerator (credentials shown statically for a known app)
+    """
+    login_page = LoginPage(page)
+    await page.goto("https://the-internet.herokuapp.com/login")
+    await login_page.wait.wait_for_page_load()
+
+    # Login with known test credentials
+    await login_page.login("tomsmith", "SuperSecretPassword!")
+
+    # Assert successful login
+    secure = SecurePage(page)
+    heading = await secure.get_heading()
+    assert "Secure Area" in heading
+
+    # Logout
+    await secure.logout()
+    assert "/login" in page.url
+
+
+# ---------------------------------------------------------------------------
+# Hybrid Test — UI + API
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.integration
+async def test_hybrid_ui_and_api(page: Page, api_client: BaseAPIClient) -> None:
+    """
+    Integration test: use UI and API in the same test.
+
+    Demonstrates:
+    - UI login to obtain a session
+    - Parallel API validation to cross-check backend state
+    - Hybrid testing pattern
+
+    The UI part uses the Heroku test site; the API part uses JSONPlaceholder.
+    In a real test, both would target the same application.
+    """
+    # --- Step 1: Log in via UI ---
+    login_page = LoginPage(page)
+    await page.goto("https://the-internet.herokuapp.com/login")
+    await login_page.login("tomsmith", "SuperSecretPassword!")
+    assert "/secure" in page.url
+
+    # --- Step 2: Validate backend data via API (simulated cross-check) ---
+    response = await api_client.get("/users/1")
+    assert response.is_success
+    # Simulate: assert that the logged-in user's backend record exists
+    api_client.validation.validate_required_fields(
+        response.data, ["id", "name", "email"]
+    )
+    assert response.data["id"] == 1
+
+    # --- Step 3: Create data via API and verify ---
+    post_response = await api_client.post(
+        "/posts",
+        data={
+            "title": TestDataGenerator.random_string(10),
+            "body": "Hybrid test post",
+            "userId": 1,
+        },
+        expected_status=201,
+    )
+    assert post_response.status_code == 201
+
+    # --- Step 4: Take screenshot as evidence ---
+    base = BasePage(page)
+    await base.screenshot.take_screenshot("hybrid_test_evidence")
+
+
+# ---------------------------------------------------------------------------
+# Data Generation Examples (no browser required)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+def test_data_generator_full_suite() -> None:
+    """
+    Unit test: verify all TestDataGenerator methods return valid data.
+
+    Runs without a browser — demonstrates available generators.
+    """
+    gen = TestDataGenerator
+
+    # Identity
+    assert gen.random_name("first")
+    assert gen.random_name("last")
+    assert " " in gen.random_name("full")
+
+    # Contact
+    assert "@" in gen.random_email()
+    assert "@" in gen.random_email("company.com")
+    assert "(" in gen.random_phone("us")
+    assert gen.random_phone("international").startswith("+1")
+
+    # Credentials
+    password = gen.random_password(length=16, include_special=True)
+    assert len(password) == 16
+
+    # Dates
+    future = gen.random_future_date(max_days=30)
+    assert len(future) == 10
+    past = gen.random_past_date(max_days=30)
+    assert len(past) == 10
+
+    # Numeric
+    assert 1 <= gen.random_number(1, 10) <= 10
+    price = float(gen.random_price(5.0, 10.0))
+    assert 5.0 <= price <= 10.0
+
+    # Misc
+    assert gen.random_company_name()
+    assert gen.random_url().startswith("https://")
+    assert len(gen.random_uuid()) == 36
+    assert gen.random_color_hex().startswith("#")
+
+    address = gen.random_address()
+    assert "street" in address and "city" in address and "zip_code" in address
diff --git a/tests/test_database_examples.py b/tests/test_database_examples.py
new file mode 100644
index 0000000..f64231d
--- /dev/null
+++ b/tests/test_database_examples.py
@@ -0,0 +1,242 @@
+"""
+Database Testing Examples
+=========================
+
+Demonstrates how to use the DatabaseClient and RedisClient in tests.
+
+These tests require the corresponding infrastructure to be running.
+Set environment variables before running::
+
+    DB_TEST=true
+    DB_TYPE=postgresql
+    DB_HOST=localhost
+    DB_PORT=5432
+    DB_NAME=testdb
+    DB_USER=postgres
+    DB_PASSWORD=password
+
+or start the Docker Compose stack::
+
+    docker-compose --profile with-db --profile with-redis up
+
+Run::
+
+    DB_TEST=true pytest tests/test_database_examples.py -v
+
+Tests will be **skipped automatically** when DB_TEST is not set to ``true``.
+Redis tests skip automatically when the Redis host is unreachable.
+"""
+
+import pytest
+import pytest_asyncio
+
+from helpers.database import DatabaseClient
+from helpers.redis_client import RedisClient
+from utils.config import Config
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+# NOTE: The db_client fixture is already defined in conftest.py and uses
+# DB_TEST=true to gate execution. These tests rely on it.
+
+
+@pytest_asyncio.fixture
+async def redis_client():
+    """
+    Provide a connected Redis client, skipping if Redis is unreachable.
+
+    This fixture is defined locally so these tests can skip gracefully
+    without affecting the rest of the suite.
+    """
+    cfg = Config.get_redis_config()
+    client = RedisClient(port=str(cfg["port"]), db=int(cfg["db"]))
+    try:
+        # Verify connectivity
+        await client.set("__health_check__", "1")
+        await client.delete("__health_check__")
+    except Exception as exc:
+        await client.close()
+        pytest.skip(f"Redis unavailable: {exc}")
+    yield client
+    await client.close()
+
+
+# ---------------------------------------------------------------------------
+# Database tests
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.integration
+async def test_db_fetch_one(db_client: DatabaseClient) -> None:
+    """
+    Integration test: fetch a single row from an information_schema table.
+
+    Demonstrates:
+    - DatabaseClient.fetch_one() with parameterised query
+    - Row returned as a plain dict
+    """
+    result = await db_client.fetch_one(
+        "SELECT table_name FROM information_schema.tables "
+        "WHERE table_schema = :schema LIMIT 1",
+        {"schema": "information_schema"},
+    )
+
+    assert result is not None
+    assert "table_name" in result
+
+
+@pytest.mark.integration
+async def test_db_fetch_all(db_client: DatabaseClient) -> None:
+    """
+    Integration test: fetch multiple rows.
+
+    Demonstrates:
+    - DatabaseClient.fetch_all() returning a list of dicts
+    """
+    rows = await db_client.fetch_all(
+        "SELECT table_name FROM information_schema.tables "
+        "WHERE table_schema = :schema",
+        {"schema": "information_schema"},
+    )
+
+    assert isinstance(rows, list)
+    assert len(rows) > 0
+    for row in rows:
+        assert "table_name" in row
+
+
+@pytest.mark.integration
+async def test_db_execute_and_verify(db_client: DatabaseClient) -> None:
+    """
+    Integration test: INSERT a row then verify it with SELECT.
+
+    Demonstrates:
+    - DatabaseClient.execute() for write operations
+    - Transactional commit and SELECT verification
+
+    Note: This test creates and then cleans up a temporary table.
+    """
+    # Create a temporary table for this test
+    await db_client.execute(
+        "CREATE TEMP TABLE IF NOT EXISTS framework_test_run "
+        "(id SERIAL PRIMARY KEY, label TEXT NOT NULL)"
+    )
+
+    await db_client.execute(
+        "INSERT INTO framework_test_run (label) VALUES (:label)",
+        {"label": "example_run"},
+    )
+
+    row = await db_client.fetch_one(
+        "SELECT label FROM framework_test_run WHERE label = :label",
+        {"label": "example_run"},
+    )
+
+    assert row is not None
+    assert row["label"] == "example_run"
+
+
+@pytest.mark.integration
+async def test_db_session_maker(db_client: DatabaseClient) -> None:
+    """
+    Integration test: use the session_maker directly for ORM-style access.
+
+    Demonstrates:
+    - Direct SQLAlchemy async session for advanced queries
+    - session_maker context manager usage
+    """
+    from sqlalchemy import text
+
+    async with db_client.session_maker() as session:
+        result = await session.execute(
+            text("SELECT current_database()")
+        )
+        db_name = result.scalar()
+        assert isinstance(db_name, str)
+        assert len(db_name) > 0
+
+
+# ---------------------------------------------------------------------------
+# Redis tests
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.integration
+async def test_redis_set_get(redis_client: RedisClient) -> None:
+    """
+    Integration test: write a value to Redis and read it back.
+
+    Demonstrates:
+    - RedisClient.set() and get()
+    - Bytes-to-string decoding of returned values
+    """
+    await redis_client.set("framework:test_key", "hello_redis")
+    raw = await redis_client.get("framework:test_key")
+
+    assert raw is not None
+    assert raw.decode() == "hello_redis"
+
+    await redis_client.delete("framework:test_key")
+
+
+@pytest.mark.integration
+async def test_redis_key_existence(redis_client: RedisClient) -> None:
+    """
+    Integration test: check key existence and deletion.
+
+    Demonstrates:
+    - RedisClient.exists() and delete()
+    """
+    key = "framework:existence_test"
+    await redis_client.set(key, "1")
+
+    assert await redis_client.exists(key) == 1
+
+    await redis_client.delete(key)
+
+    assert await redis_client.exists(key) == 0
+
+
+@pytest.mark.integration
+async def test_redis_list_keys(redis_client: RedisClient) -> None:
+    """
+    Integration test: list keys matching a pattern.
+
+    Demonstrates:
+    - RedisClient.list_keys() with a glob pattern
+    """
+    await redis_client.set("framework:a", "1")
+    await redis_client.set("framework:b", "2")
+
+    keys = await redis_client.list_keys("framework:*")
+    decoded_keys = [k.decode() if isinstance(k, bytes) else k for k in keys]
+
+    assert "framework:a" in decoded_keys
+    assert "framework:b" in decoded_keys
+
+    # Cleanup
+    await redis_client.delete("framework:a")
+    await redis_client.delete("framework:b")
+
+
+@pytest.mark.integration
+async def test_redis_context_manager() -> None:
+    """
+    Integration test: RedisClient used as an async context manager.
+
+    Demonstrates:
+    - async with RedisClient() pattern
+    - Automatic connection cleanup on exit
+    """
+    cfg = Config.get_redis_config()
+    try:
+        async with RedisClient(port=str(cfg["port"]), db=int(cfg["db"])) as client:
+            await client.set("framework:ctx_test", "ctx_value")
+            value = await client.get("framework:ctx_test")
+            assert value is not None
+            assert value.decode() == "ctx_value"
+            await client.delete("framework:ctx_test")
+    except Exception as exc:
+        pytest.skip(f"Redis unavailable: {exc}")
diff --git a/tests/test_ui_examples.py b/tests/test_ui_examples.py
new file mode 100644
index 0000000..81decda
--- /dev/null
+++ b/tests/test_ui_examples.py
@@ -0,0 +1,275 @@
+"""
+UI Testing Examples
+===================
+
+Demonstrates how to use the framework for browser-based UI automation.
+
+All examples target https://the-internet.herokuapp.com (a free test site)
+so they can be run without a private application.
+
+Run::
+
+    pytest tests/test_ui_examples.py -v
+
+Run with visible browser::
+
+    pytest tests/test_ui_examples.py --headed -v
+"""
+
+import pytest
+from playwright.async_api import Page
+
+from core.ui.base_page import BasePage
+from utils.config import Config
+from utils.test_helpers import TestDataGenerator
+
+# ---------------------------------------------------------------------------
+# Page Objects
+# ---------------------------------------------------------------------------
+
+
+class HerokuLoginPage(BasePage):
+    """Login page for https://the-internet.herokuapp.com/login."""
+
+    username_input = "#username"
+    password_input = "#password"
+    login_button = '[type="submit"]'
+    flash_message = "#flash"
+
+    async def login(self, username: str, password: str) -> None:
+        """Fill and submit the login form."""
+        await self.fill_data(
+            {
+                self.username_input: username,
+                self.password_input: password,
+            }
+        )
+        await self.page.click(self.login_button)
+        await self.wait.wait_for_page_load()
+
+    async def get_flash_message(self) -> str:
+        """Return the text of the flash notification."""
+        return (await self.page.locator(self.flash_message).inner_text()).strip()
+
+
+class HerokuCheckboxPage(BasePage):
+    """Checkboxes demo page."""
+
+    checkbox1 = "input[type='checkbox']:nth-of-type(1)"
+    checkbox2 = "input[type='checkbox']:nth-of-type(2)"
+
+
+class HerokuDropdownPage(BasePage):
+    """Dropdown demo page."""
+
+    dropdown = "#dropdown"
+
+
+class HerokuDynamicContentPage(BasePage):
+    """Dynamic content page (demonstrates waiting strategies)."""
+
+    content_rows = ".large-10"
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.smoke_test
+async def test_successful_login(page: Page) -> None:
+    """
+    Smoke test: successful login with valid credentials.
+
+    Demonstrates:
+    - Page Object Model with BasePage
+    - fill_data() for form filling
+    - validation service for assertions
+    """
+    login_page = HerokuLoginPage(page)
+    await page.goto("https://the-internet.herokuapp.com/login")
+    await login_page.wait.wait_for_page_load()
+
+    await login_page.login("tomsmith", "SuperSecretPassword!")
+
+    # Verify redirect to secure area
+    assert "/secure" in page.url
+    await login_page.validation.assert_visible(".flash.success")
+
+
+@pytest.mark.smoke_test
+async def test_failed_login(page: Page) -> None:
+    """
+    Smoke test: failed login with invalid credentials.
+
+    Demonstrates:
+    - Negative testing with the framework
+    - Flash message validation
+    """
+    login_page = HerokuLoginPage(page)
+    await page.goto("https://the-internet.herokuapp.com/login")
+
+    await login_page.login("wronguser", "wrongpassword")
+
+    flash = await login_page.get_flash_message()
+    assert "Your username is invalid" in flash
+
+
+@pytest.mark.regression
+async def test_checkbox_interactions(page: Page) -> None:
+    """
+    Regression test: checkbox checking and unchecking.
+
+    Demonstrates:
+    - Boolean values in fill_data() for checkboxes
+    - Validation service assert_checked / assert_not_checked
+    """
+    await page.goto("https://the-internet.herokuapp.com/checkboxes")
+    checkbox_page = HerokuCheckboxPage(page)
+
+    # Check checkbox 1 (initially unchecked)
+    await checkbox_page.fill_data({checkbox_page.checkbox1: True})
+    await checkbox_page.validation.assert_checked(checkbox_page.checkbox1)
+
+    # Uncheck checkbox 2 (initially checked)
+    await checkbox_page.fill_data({checkbox_page.checkbox2: False})
+    await checkbox_page.validation.assert_not_checked(checkbox_page.checkbox2)
+
+
+@pytest.mark.regression
+async def test_dropdown_selection(page: Page) -> None:
+    """
+    Regression test: native <select> dropdown interaction.
+
+    Demonstrates:
+    - Auto-detected select strategy via fill_data()
+    - Validating the selected value
+    """
+    await page.goto("https://the-internet.herokuapp.com/dropdown")
+    dropdown_page = HerokuDropdownPage(page)
+
+    await dropdown_page.fill_data({dropdown_page.dropdown: "Option 1"})
+
+    selected = await page.locator(f"{dropdown_page.dropdown} option:checked").inner_text()
+    assert selected == "Option 1"
+
+
+@pytest.mark.regression
+async def test_page_screenshot_on_demand(page: Page) -> None:
+    """
+    Regression test: manual screenshot capture.
+
+    Demonstrates:
+    - screenshot service usage
+    - Evidence capture for reporting
+    """
+    await page.goto("https://the-internet.herokuapp.com/")
+    base = BasePage(page)
+
+    # Take a named screenshot (saved to screenshots/ directory)
+    await base.screenshot.take_screenshot("homepage_evidence")
+
+
+@pytest.mark.regression
+async def test_storage_manipulation(page: Page) -> None:
+    """
+    Regression test: localStorage read/write via Storage service.
+
+    Demonstrates:
+    - Storage service for setting and reading localStorage
+    """
+    await page.goto("https://the-internet.herokuapp.com/")
+    base = BasePage(page)
+
+    await base.storage.set_local_storage("test_key", "hello_framework")
+    value = await base.storage.get_local_storage("test_key")
+    assert value == "hello_framework"
+
+
+@pytest.mark.regression
+async def test_dynamic_content_wait(page: Page) -> None:
+    """
+    Regression test: waiting for dynamic page content.
+
+    Demonstrates:
+    - wait service for page-load events
+    - locator count verification
+    """
+    await page.goto("https://the-internet.herokuapp.com/dynamic_content")
+    content_page = HerokuDynamicContentPage(page)
+
+    await content_page.wait.wait_for_page_load()
+    rows = page.locator(content_page.content_rows)
+    count = await rows.count()
+    assert count > 0, "Expected at least one dynamic content row"
+
+
+@pytest.mark.regression
+async def test_tab_window_management(page: Page) -> None:
+    """
+    Regression test: multi-tab management using TabWindow service.
+
+    Demonstrates:
+    - Opening a link that triggers a new tab
+    - Closing tabs
+    """
+    await page.goto("https://the-internet.herokuapp.com/windows")
+    base = BasePage(page)
+
+    # Click the link that opens a new window/tab
+    new_page = await base.tab_window.wait_for_new_tab_and_switch(
+        lambda: page.click("a[href='/windows/new']")
+    )
+
+    assert new_page is not None
+    await new_page.wait_for_load_state()
+    assert "New Window" in await new_page.title()
+    await new_page.close()
+
+
+@pytest.mark.integration
+async def test_full_crud_workflow_example(page: Page) -> None:
+    """
+    Integration test: login → interact → logout workflow.
+
+    Demonstrates a complete end-to-end flow using multiple services.
+    """
+    login_page = HerokuLoginPage(page)
+    await page.goto("https://the-internet.herokuapp.com/login")
+    await login_page.login("tomsmith", "SuperSecretPassword!")
+    await login_page.validation.assert_visible(".flash.success")
+
+    # Interact with the secure page
+    await login_page.validation.assert_visible("h2")
+    heading = await page.locator("h2").inner_text()
+    assert "Secure Area" in heading
+
+    # Logout
+    await page.click("a[href='/logout']")
+    await login_page.wait.wait_for_page_load()
+    assert "/login" in page.url
+
+
+@pytest.mark.unit
+def test_data_generator_produces_valid_data() -> None:
+    """
+    Unit test: TestDataGenerator generates correctly-typed values.
+
+    Demonstrates the test data utilities available in utils/test_helpers.py.
+    These run without a browser.
+    """
+    name = TestDataGenerator.random_name()
+    assert isinstance(name, str)
+    assert len(name) > 0
+
+    email = TestDataGenerator.random_email()
+    assert "@" in email
+
+    phone = TestDataGenerator.random_phone("us")
+    assert "(" in phone and ")" in phone
+
+    future_date = TestDataGenerator.random_future_date()
+    assert len(future_date) == 10  # YYYY-MM-DD
+
+    price = TestDataGenerator.random_price()
+    assert float(price) > 0
diff --git a/utils/config.py b/utils/config.py
index 27384e8..2ad681d 100644
--- a/utils/config.py
+++ b/utils/config.py
@@ -343,22 +343,6 @@ def get_api_password() -> str:
         return os.getenv("API_PASSWORD", Config.get_test_password())
 
     # ========== Basic Auth Settings ==========
-    @staticmethod
-    def get_api_username() -> str:
-        """Get API username for login flows or basic auth."""
-        return os.getenv("API_USERNAME", Config.get_test_username())
-
-    @staticmethod
-    def get_api_password() -> str:
-        """Get API password for login flows or basic auth."""
-        return os.getenv("API_PASSWORD", Config.get_test_password())
-
-    # ========== Bearer Token Settings ==========
-    @staticmethod
-    def get_api_bearer_token() -> str:
-        """Get API bearer token for authentication."""
-        return os.getenv("API_BEARER_TOKEN", "")
-
     # ========== OAuth2 Settings ==========
     @staticmethod
     def get_oauth_client_id() -> str:
@@ -381,11 +365,6 @@ def get_oauth_scope() -> str:
         return os.getenv("OAUTH_SCOPE", "")
 
     # ========= API Key Settings ==========
-    @staticmethod
-    def get_api_key() -> str:
-        """Get API key for authentication."""
-        return os.getenv("API_KEY", "")
-
     @staticmethod
     def get_api_key_header_name() -> str:
         """Get API key header name."""