pyplaykit 0.1.0

Enterprise Python + Playwright automation framework

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:

   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   

2. Install framework dependencies.

   pip install -r requirements.txt
   playwright install
   

3. Install dev security tooling.

   pip install -r requirements-dev.txt
   

4. Set credentials for tests requiring valid login.

   $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
• --pyplaykit-readiness-check

Examples:

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):

winget install --id Gitleaks.Gitleaks -e

Windows (choco):

choco install gitleaks

macOS (brew):

brew install gitleaks

Linux (Homebrew/Linuxbrew):

brew install gitleaks

Run on Windows:

scripts\run_security_reports.bat

Run on Linux/macOS:

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:

scripts\run_unit_tests_with_coverage.bat

Linux/macOS:

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.