pyplaykit 0.1.0__py3-none-any.whl

pages/orangehrm_login_page.py

@@ -0,0 +1,58 @@
+from playwright.sync_api import Page
+from core.base_page import BasePage
+from utils.yaml_config_reader import ConfigReader
+from utils.logger import get_logger
+
+class OrangeHRMLoginPage(BasePage):
+    """
+    Page object for the OrangeHRM Login page.
+    Encapsulates locators and actions related to the login functionality.
+    """
+
+    # Locators
+    USERNAME_INPUT = "#app > div.orangehrm-login-layout > div > div.orangehrm-login-container > div > div.orangehrm-login-slot > div.orangehrm-login-form > form > div:nth-child(2) > div > div:nth-child(2) > input"
+    PASSWORD_INPUT = "#app > div.orangehrm-login-layout > div > div.orangehrm-login-container > div > div.orangehrm-login-slot > div.orangehrm-login-form > form > div:nth-child(3) > div > div:nth-child(2) > input"
+    LOGIN_BUTTON = "#app > div.orangehrm-login-layout > div > div.orangehrm-login-container > div > div.orangehrm-login-slot > div.orangehrm-login-form > form > div.oxd-form-actions.orangehrm-login-action > button"
+    DASHBOARD_HEADER = "h6.oxd-text.oxd-text--h6.oxd-topbar-header-breadcrumb-module" # A locator to verify successful login
+    INVALID_CREDENTIALS_MESSAGE = "div.oxd-alert-content.oxd-alert-content--error > p.oxd-text--p"
+
+    def __init__(self, page: Page, config: ConfigReader):
+        super().__init__(page)
+        self.config = config
+        self.logger = get_logger(OrangeHRMLoginPage.__name__)
+        self.base_url = self.config.get_base_url(self.config.get_env()) # Get base URL for the current environment
+
+    def navigate(self):
+        """Navigates to the OrangeHRM login page."""
+        self.page.goto(self.base_url + "/web/index.php/auth/login")
+        self.logger.info(f"Navigated to: {self.page.url}")
+
+    def login(self, username, password):
+        """
+        Performs a login action with the given username and password.
+        """
+        self.fill(self.USERNAME_INPUT, username)
+        self.fill(self.PASSWORD_INPUT, password)
+        self.click(self.LOGIN_BUTTON)
+        self.logger.info(f"Attempted login with username: {username}")
+
+    def verify_login_success(self):
+        """
+        Verifies that the login was successful by checking for a dashboard element.
+        """
+        # Playwright's expect.to_be_visible() is implicitly used by is_visible() which auto-waits
+        is_visible = self.is_visible(self.DASHBOARD_HEADER)
+        self.logger.info(f"Dashboard header visibility: {is_visible}")
+        return is_visible
+
+    def get_dashboard_header_text(self):
+        """
+        Gets the text of the dashboard header after successful login.
+        """
+        return self.text(self.DASHBOARD_HEADER)
+
+    def is_error_message_visible(self) -> bool:
+        """
+        Checks if the invalid credentials error message is visible.
+        """
+        return self.is_visible(self.INVALID_CREDENTIALS_MESSAGE)

pages/saucedemo_inventory_page.py

@@ -0,0 +1,100 @@
+"""SauceDemo Inventory Page Object for UI Validation Examples."""
+
+from playwright.sync_api import Page, Locator
+from core.base_page import BasePage
+from typing import Any
+
+
+class SauceDemoInventoryPage(BasePage):
+    """Page object for SauceDemo inventory/products page."""
+
+    # Locators
+    APP_LOGO = 'div.app_logo'
+    INVENTORY_CONTAINER = 'div.inventory_container'
+    INVENTORY_ITEMS = 'div.inventory_item'
+    PRODUCT_NAME = 'div.inventory_item_name'
+    PRODUCT_PRICE = 'div.inventory_item_price'
+    ADD_TO_CART_BUTTON = 'button[data-test^="add-to-cart"]'
+    REMOVE_FROM_CART_BUTTON = 'button[data-test^="remove"]'
+    SHOPPING_CART_BADGE = 'span.shopping_cart_badge'
+    SHOPPING_CART_LINK = 'a.shopping_cart_link'
+    PRODUCT_SORT_DROPDOWN = 'select.product_sort_container'
+    BURGER_MENU = 'button#react-burger-menu-btn'
+    LOGOUT_LINK = 'a#logout_sidebar_link'
+
+    def __init__(self, page: Page, resilience_policy: dict[str, Any] | None = None):
+        """Initialize SauceDemo inventory page."""
+        super().__init__(page, resilience_policy)
+
+    def is_on_inventory_page(self) -> bool:
+        """Verify user is on inventory page."""
+        return self.is_visible(self.INVENTORY_CONTAINER, timeout=10000)
+
+    def get_page_title(self) -> str:
+        """Get page title text from app logo."""
+        return self.text(self.APP_LOGO)
+
+    def get_product_count(self) -> int:
+        """Get total number of products displayed."""
+        items = self.page.locator(self.INVENTORY_ITEMS).all()
+        return len(items)
+
+    def get_product_names(self) -> list[str]:
+        """Get list of all product names."""
+        names = []
+        items = self.page.locator(self.INVENTORY_ITEMS).all()
+        for item in items:
+            name_locator = item.locator(self.PRODUCT_NAME)
+            names.append(name_locator.inner_text())
+        return names
+
+    def get_product_prices(self) -> list[float]:
+        """Get list of all product prices as floats."""
+        prices = []
+        items = self.page.locator(self.INVENTORY_ITEMS).all()
+        for item in items:
+            price_locator = item.locator(self.PRODUCT_PRICE)
+            price_text = price_locator.inner_text().replace("$", "")
+            prices.append(float(price_text))
+        return prices
+
+    def add_product_to_cart_by_name(self, product_name: str) -> None:
+        """Add specific product to cart by product name."""
+        product_selector = f'{self.INVENTORY_ITEMS}:has-text("{product_name}")'
+        product_item = self.page.locator(product_selector)
+        add_button = product_item.locator(self.ADD_TO_CART_BUTTON)
+        add_button.click()
+
+    def add_all_products_to_cart(self) -> int:
+        """Add all products to cart and return count."""
+        buttons = self.page.locator(self.ADD_TO_CART_BUTTON).all()
+        for button in buttons:
+            button.click()
+        return len(buttons)
+
+    def get_cart_badge_count(self) -> int:
+        """Get number displayed in shopping cart badge."""
+        if not self.is_visible(self.SHOPPING_CART_BADGE, timeout=2000):
+            return 0
+        badge_text = self.text(self.SHOPPING_CART_BADGE)
+        return int(badge_text)
+
+    def sort_products(self, sort_option: str) -> None:
+        """Sort products by option (az, za, lohi, hilo)."""
+        self.page.select_option(self.PRODUCT_SORT_DROPDOWN, sort_option)
+
+    def open_burger_menu(self) -> None:
+        """Open burger menu."""
+        self.click(self.BURGER_MENU)
+
+    def logout(self) -> None:
+        """Logout from application."""
+        self.open_burger_menu()
+        self.click(self.LOGOUT_LINK)
+
+    def is_product_in_cart(self, product_name: str) -> bool:
+        """Check if specific product has been added to cart (Remove button visible)."""
+        product_selector = f'{self.INVENTORY_ITEMS}:has-text("{product_name}")'
+        product_item = self.page.locator(product_selector)
+        remove_button = product_item.locator(self.REMOVE_FROM_CART_BUTTON)
+        return remove_button.is_visible()

pages/saucedemo_login_page.py

@@ -0,0 +1,39 @@
+"""SauceDemo Login Page Object for UI Validation Examples."""
+
+from playwright.sync_api import Page
+from core.base_page import BasePage
+from typing import Any
+
+
+class SauceDemoLoginPage(BasePage):
+    """Page object for SauceDemo login page (https://www.saucedemo.com)."""
+
+    # Locators
+    USERNAME_INPUT = 'input[data-test="username"]'
+    PASSWORD_INPUT = 'input[data-test="password"]'
+    LOGIN_BUTTON = 'input[data-test="login-button"]'
+    ERROR_MESSAGE = 'h3[data-test="error"]'
+    ERROR_BUTTON = 'button.error-button'
+
+    def __init__(self, page: Page, resilience_policy: dict[str, Any] | None = None):
+        """Initialize SauceDemo login page."""
+        super().__init__(page, resilience_policy)
+
+    def login(self, username: str, password: str) -> None:
+        """Perform login with credentials."""
+        self.fill(self.USERNAME_INPUT, username)
+        self.fill(self.PASSWORD_INPUT, password)
+        self.click(self.LOGIN_BUTTON)
+
+    def is_error_displayed(self) -> bool:
+        """Check if error message is displayed."""
+        return self.is_visible(self.ERROR_MESSAGE, timeout=5000)
+
+    def get_error_message(self) -> str:
+        """Get error message text."""
+        return self.text(self.ERROR_MESSAGE)
+
+    def clear_login_form(self) -> None:
+        """Clear login form fields."""
+        self.fill(self.USERNAME_INPUT, "")
+        self.fill(self.PASSWORD_INPUT, "")

plugins/__init__.py

@@ -0,0 +1,16 @@
+"""Plugin architecture exports for lifecycle extensibility."""
+
+from .api_plugin import ApiPlugin
+from .base import FrameworkPlugin
+from .data_plugin import DataPlugin
+from .registry import PluginRegistry, build_plugin_registry
+from .security_plugin import SecurityPlugin
+
+__all__ = [
+    "FrameworkPlugin",
+    "PluginRegistry",
+    "build_plugin_registry",
+    "ApiPlugin",
+    "DataPlugin",
+    "SecurityPlugin",
+]

plugins/api_plugin.py

@@ -0,0 +1,11 @@
+"""Built-in API plugin placeholder for lifecycle-driven extension."""
+
+from __future__ import annotations
+
+from plugins.base import FrameworkPlugin
+
+
+class ApiPlugin(FrameworkPlugin):
+    """Default API plugin extension point."""
+
+    name = "api_plugin"

plugins/base.py

@@ -0,0 +1,21 @@
+"""Plugin contracts for framework lifecycle extensibility."""
+
+from __future__ import annotations
+
+from abc import ABC
+from typing import Any, Mapping
+
+
+class FrameworkPlugin(ABC):
+    """Base plugin contract with lifecycle hooks."""
+
+    name: str = "plugin"
+
+    def on_session_start(self, context: Mapping[str, Any]) -> None:
+        """Hook called when a framework session starts."""
+
+    def on_test_result(self, context: Mapping[str, Any]) -> None:
+        """Hook called after each test call-phase result."""
+
+    def on_session_finish(self, context: Mapping[str, Any]) -> None:
+        """Hook called when a framework session ends."""

plugins/data_plugin.py

@@ -0,0 +1,11 @@
+"""Built-in data plugin placeholder for lifecycle-driven extension."""
+
+from __future__ import annotations
+
+from plugins.base import FrameworkPlugin
+
+
+class DataPlugin(FrameworkPlugin):
+    """Default data plugin extension point."""
+
+    name = "data_plugin"

plugins/registry.py

@@ -0,0 +1,77 @@
+"""Plugin registry and configuration-driven plugin loading."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from plugins.api_plugin import ApiPlugin
+from plugins.base import FrameworkPlugin
+from plugins.data_plugin import DataPlugin
+from plugins.security_plugin import SecurityPlugin
+
+
+class PluginRegistry:
+    """Manage plugin registration and lifecycle hook dispatch."""
+
+    def __init__(self, logger=None) -> None:
+        self.logger = logger
+        self._plugins: dict[str, FrameworkPlugin] = {}
+
+    def register(self, plugin: FrameworkPlugin) -> None:
+        """Register one plugin instance by unique name."""
+        name = getattr(plugin, "name", "")
+        if not name:
+            raise ValueError("Plugin name must be a non-empty string")
+        if name in self._plugins:
+            raise ValueError(f"Plugin '{name}' is already registered")
+        self._plugins[name] = plugin
+
+    def names(self) -> list[str]:
+        """Return registered plugin names in insertion order."""
+        return list(self._plugins.keys())
+
+    def dispatch(self, hook_name: str, context: Mapping[str, Any]) -> list[str]:
+        """Dispatch lifecycle hook to all registered plugins."""
+        invoked: list[str] = []
+        for plugin in self._plugins.values():
+            hook = getattr(plugin, hook_name, None)
+            if not callable(hook):
+                continue
+            try:
+                hook(context)
+                invoked.append(plugin.name)
+            except Exception as error:  # pragma: no cover - defensive, covered by unit test via generic Exception
+                raise RuntimeError(f"Plugin hook failed: plugin={plugin.name}, hook={hook_name}") from error
+
+        if self.logger and invoked:
+            self.logger.info("Plugin hook dispatched: %s | plugins=%s", hook_name, ",".join(invoked))
+        return invoked
+
+
+BUILTIN_PLUGIN_FACTORIES = {
+    "api_plugin": ApiPlugin,
+    "data_plugin": DataPlugin,
+    "security_plugin": SecurityPlugin,
+}
+
+
+def build_plugin_registry(config: Mapping[str, Any], logger=None) -> PluginRegistry:
+    """Build plugin registry from framework configuration."""
+    registry = PluginRegistry(logger=logger)
+    if not isinstance(config, Mapping):
+        return registry
+
+    if not bool(config.get("enabled", False)):
+        return registry
+
+    enabled_plugins = config.get("enabled_plugins", [])
+    if not isinstance(enabled_plugins, list):
+        raise ValueError("plugins.enabled_plugins must be a list")
+
+    for plugin_name in enabled_plugins:
+        factory = BUILTIN_PLUGIN_FACTORIES.get(str(plugin_name).strip())
+        if factory is None:
+            raise ValueError(f"Unsupported plugin name: {plugin_name}")
+        registry.register(factory())
+
+    return registry

plugins/security_plugin.py

@@ -0,0 +1,11 @@
+"""Built-in security plugin placeholder for lifecycle-driven extension."""
+
+from __future__ import annotations
+
+from plugins.base import FrameworkPlugin
+
+
+class SecurityPlugin(FrameworkPlugin):
+    """Default security plugin extension point."""
+
+    name = "security_plugin"

pyplaykit-0.1.0.dist-info/METADATA

@@ -0,0 +1,340 @@
+Metadata-Version: 2.4
+Name: pyplaykit
+Version: 0.1.0
+Summary: Enterprise Python + Playwright automation framework
+Author-email: Shan Konduru <shankonduru@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/ShanKonduru/pyplaykit
+Project-URL: Repository, https://github.com/ShanKonduru/pyplaykit
+Project-URL: Bug Tracker, https://github.com/ShanKonduru/pyplaykit/issues
+Keywords: playwright,pytest,automation,framework,enterprise,testing,page-object-model
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: Pytest
+Classifier: Topic :: Software Development :: Testing
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: playwright==1.54.0
+Requires-Dist: pytest==8.4.1
+Requires-Dist: pytest-cov==6.2.1
+Requires-Dist: pytest-xdist==3.6.1
+Requires-Dist: pytest-rerunfailures==15.1
+Requires-Dist: pytest-html==4.1.1
+Requires-Dist: allure-pytest==2.13.5
+Requires-Dist: PyYAML==6.0.2
+
+# PyPlayKit - Enterprise Test Automation Framework
+
+Tagline: A modular, scalable, and CI/CD-ready Python + Playwright framework for enterprise automation.
+
+## Overview
+PyPlayKit is a layered and extensible enterprise UI automation framework built with Python, Playwright, and Pytest.
+
+It is designed to provide:
+- standardized test automation practices
+- strong separation between framework code and business test logic
+- deterministic execution with reusable browser lifecycle management
+- CI/CD-friendly reporting and diagnostics
+
+## Architecture Layers
+- Test Layer: business-readable test flows using Pytest
+- Page Object Layer: encapsulated locators, page actions, and validations
+- Core Engine Layer: Playwright lifecycle and browser/context management
+- Utilities Layer: logging, data loading, assertions, and screenshots
+- API and Data Validation Layer: reusable API client, response validators, and data validators
+- Observability and Readiness Layer: execution metrics, KPI outputs, and environment readiness checks
+- Configuration Layer: externalized YAML configuration and environment mapping
+- Test Data Layer: JSON data sources with environment variable placeholders
+- Reporting and Logging Layer: HTML report output and structured logs
+
+## Project Structure
+pyplaykit/
+- config/
+   - config.yaml
+   - environments.yaml
+- core/
+   - base_page.py
+   - base_test.py
+   - browser_factory.py
+   - playwright_manager.py
+- integrations/
+   - adapters.py
+- orchestration/
+   - planner.py
+- packaging/
+   - distribution.py
+- plugins/
+   - base.py
+   - registry.py
+   - api_plugin.py
+   - data_plugin.py
+   - security_plugin.py
+- resilience/
+   - locator_recovery.py
+- pages/
+   - login_page.py
+   - dashboard_page.py
+- tests/
+   - test_login.py
+   - test_dashboard.py
+- utils/
+   - logger.py
+   - data_loader.py
+   - assertion_helper.py
+   - screenshot_helper.py
+   - api_client.py
+   - response_validator.py
+   - data_validator.py
+   - config_reader.py
+   - observability.py
+   - environment_validator.py
+   - tdm.py
+- test_data/
+   - login_test_data.json
+- reports/
+- conftest.py
+- pyproject.toml
+- MANIFEST.in
+- pytest.ini
+- requirements.txt
+- README.md
+- .gitignore
+
+## Prerequisites
+- Python 3.11 or higher
+- pip
+
+## Setup
+1. Create and activate virtual environment.
+
+    Windows PowerShell:
+    ```powershell
+    python -m venv .venv
+    .\.venv\Scripts\Activate.ps1
+    ```
+
+2. Install framework dependencies.
+
+    ```powershell
+    pip install -r requirements.txt
+    playwright install
+    ```
+
+3. Install dev security tooling.
+
+   ```powershell
+   pip install -r requirements-dev.txt
+   ```
+
+4. Set credentials for tests requiring valid login.
+
+    ```powershell
+    $env:PYPLAYKIT_TEST_USERNAME="standard_user"
+    $env:PYPLAYKIT_TEST_PASSWORD="secret_sauce"
+    ```
+
+## Runtime Configuration
+Primary execution settings are in config/config.yaml.
+
+Supported runtime overrides:
+- --pyplaykit-env dev|qa|uat|prod
+- --pyplaykit-browser chromium|firefox|webkit
+- --pyplaykit-headed
+- --pyplaykit-base-url <url>
+- --pyplaykit-readiness-check
+
+Examples:
+
+```powershell
+pytest --pyplaykit-env qa --pyplaykit-browser chromium
+pytest --pyplaykit-env uat --pyplaykit-browser firefox --pyplaykit-headed
+pytest -m "smoke"
+pytest -m "regression"
+pytest -n 2
+```
+
+## Reporting and Diagnostics
+- HTML report: reports/report.html
+- Framework logs: reports/framework.log
+- Failure screenshots: reports/screenshots/
+- Videos (if enabled): reports/videos/
+- Observability summary: reports/observability/summary.json
+- KPI summary: reports/observability/kpi_summary.json
+- Integration export (Jira): reports/integrations/jira_export.json
+- Integration export (Test Management): reports/integrations/test_management_export.json
+
+## Data-Driven Support
+- JSON test data is stored under test_data/.
+- Placeholder values in the form ${ENV_VAR} are resolved from environment variables.
+
+## API and Data Validation Support
+- API client utility in utils/api_client.py supports GET/POST requests, retry handling, and normalized response objects.
+- API response validators in utils/response_validator.py support status, response time, key presence, and JSON path value checks.
+- Data validators in utils/data_validator.py support required-field validation, type validation, record comparison, and collection subset checks.
+
+## Wave 1 Status (Implemented)
+Wave 1 foundation controls from the enterprise roadmap are now implemented:
+- Observability tracker for execution metrics, failure classification, flaky identification, and KPI summaries.
+- Environment readiness checks for URL availability, API health, and optional DB connectivity.
+- Session-level observability report generation integrated into pytest lifecycle.
+
+Execution notes:
+- Readiness checks are optional by default and can be enabled with `--pyplaykit-readiness-check`.
+- Readiness and observability defaults are configured in config/config.yaml.
+
+## Wave 2 Status (Implemented)
+Wave 2 includes Test Data Management utilities:
+- Deterministic synthetic data generation by schema/seed
+- Field-level masking utilities for sensitive data
+- Reusable data reset helper for list/dict/callback stores
+- Environment-specific data provisioning helper
+- Config-driven TDM policy wiring with parser and validator integrated into runtime options
+
+Wave 2 Multi-level Reporting is now implemented:
+- Engineering report JSON output
+- QA functional report JSON output
+- Leadership KPI summary JSON output
+
+Wave 2 Integration Layer has started with file-based adapters:
+- Integration adapter interface contract for enterprise connectors
+- Jira file export adapter
+- Test management file export adapter
+
+Wave 2 Integration Layer now also includes API adapters:
+- Jira API export adapter
+- Test management API export adapter
+
+## Wave 3 Status (Implemented)
+Wave 3 Plugin Architecture is now implemented:
+- Plugin registry with lifecycle hook dispatch
+- Built-in starter plugins: api_plugin, data_plugin, security_plugin
+- Config-gated plugin enablement to preserve default behavior
+
+Wave 3 Orchestration Layer is now implemented:
+- Config-driven suite orchestration contract
+- Dependency-aware execution graph with cycle and schema validation
+- Ordered pipelines with stage-based execution plans
+
+## Wave 4 Status (In Progress)
+Wave 4 self-healing implementation is now complete:
+- Optional locator fallback chain support
+- DOM re-evaluation retry support for resilient element resolution
+- Config contract for resilience policy in config/config.yaml
+- Confidence-scored fallback selection based on retries and fallback depth
+- JSONL audit log output for each recovery action when enabled
+
+Wave 4 distribution packaging baseline is now implemented:
+- PEP 621 package metadata in pyproject.toml
+- Source and wheel artifact manifest support via MANIFEST.in
+- Internal package build helper and wrappers:
+   - scripts/build_internal_package.py
+   - scripts/build_internal_package.bat
+   - scripts/build_internal_package.sh
+
+Remaining for Wave 4:
+- Semantic versioning, release channels, and compatibility matrix governance
+- Automated release notes from conventional commit history
+
+## CI/CD Notes
+Framework supports GitHub Actions, Jenkins, and Azure DevOps pipelines through:
+- deterministic command-line execution
+- marker-based selective runs
+- parallel execution with pytest-xdist
+- rerun support for flaky tests via pytest-rerunfailures
+
+## Security Scan Reports
+Security scan tooling includes pip-audit, bandit, gitleaks, and sec-report-kit.
+
+The security scripts are self-bootstrapping and do the following automatically:
+- create .venv if missing
+- activate the virtual environment
+- upgrade pip
+- install dependencies from requirements.txt and requirements-dev.txt
+- run pip-audit, bandit, gitleaks detect (committed history), and gitleaks dir (working tree) and generate JSON outputs
+- render individual HTML reports and a consolidated HTML report using sec-report-kit
+
+Scripts:
+- scripts/run_security_reports.bat
+- scripts/run_security_reports.sh
+
+Note:
+- scripts prefer repo-local gitleaks binary if present (for example gitleaks_8.30.1/gitleaks.exe), otherwise they use PATH.
+- the gitleaks dir scan is intentionally limited to tracked project source folders and key files, so third-party package code under .venv is not scanned.
+
+Install gitleaks CLI:
+
+Windows (winget):
+```powershell
+winget install --id Gitleaks.Gitleaks -e
+```
+
+Windows (choco):
+```powershell
+choco install gitleaks
+```
+
+macOS (brew):
+```bash
+brew install gitleaks
+```
+
+Linux (Homebrew/Linuxbrew):
+```bash
+brew install gitleaks
+```
+
+Run on Windows:
+
+```powershell
+scripts\run_security_reports.bat
+```
+
+Run on Linux/macOS:
+
+```bash
+bash scripts/run_security_reports.sh
+```
+
+Outputs:
+- JSON reports: reports/secutiry_reports/json/
+   - pip_audit_report.json
+   - bandit_report.json
+   - gitleaks_git_report.json
+   - gitleaks_dir_report.json
+- HTML reports: reports/secutiry_reports/html/
+   - pip_audit_report.html
+   - bandit_report.html
+   - gitleaks_git_report.html
+   - gitleaks_dir_report.html
+- Consolidated HTML report: reports/secutiry_reports/html/security_consolidated_report.html
+
+## Unit Test Coverage
+Run framework unit tests with coverage metrics.
+
+Windows:
+
+```powershell
+scripts\run_unit_tests_with_coverage.bat
+```
+
+Linux/macOS:
+
+```bash
+bash scripts/run_unit_tests_with_coverage.sh
+```
+
+Coverage outputs:
+- Terminal summary with missing lines
+- HTML report: reports/coverage-html/index.html
+- XML report: reports/coverage.xml
+
+## Design and Extension Guidance
+- Keep locators in page classes only.
+- Keep tests business-readable and independent.
+- Avoid hardcoded secrets and environment-specific values in test code.
+- Extend under existing layers to preserve maintainability and onboarding simplicity.