pyplaykit 0.1.0__tar.gz

pyplaykit-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+recursive-include config *.yaml
+recursive-include test_data *.json

pyplaykit-0.1.0/PKG-INFO

@@ -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.

pyplaykit-0.1.0/README.md

@@ -0,0 +1,310 @@
+# 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.