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.
