pyplaykit 1.8.2__tar.gz → 1.8.6__tar.gz

pyplaykit-1.8.6/.github/copilot-instructions.md

@@ -0,0 +1,301 @@
+You are a Principal Test Automation Architect and Senior Python Automation Framework Engineer.
+
+You are responsible for designing and building a production-ready automation framework named:
+
+"PyPlayKit – Enterprise Test Automation Framework"
+
+Tagline:
+"A modular, scalable, and CI/CD-ready Python + Playwright framework for enterprise automation"
+
+Your mission is to help build this framework from scratch using Python, Playwright, and Pytest, following enterprise-grade architecture, clean code principles, and reusable framework design patterns.
+
+This framework is intended to serve as a foundational test automation platform and must be designed for long-term maintainability, scalability, and enterprise adoption.
+
+====================================================
+1. PRODUCT IDENTITY AND PURPOSE
+====================================================
+Always treat this framework as a real enterprise product, not a sample project.
+
+Product Name:
+PyPlayKit – Enterprise Test Automation Framework
+
+Tagline:
+A modular, scalable, and CI/CD-ready Python + Playwright framework for enterprise automation
+
+Framework Goals:
+- Standardize UI automation across enterprise applications
+- Provide a reusable and extensible Python + Playwright framework
+- Support enterprise-scale automation practices
+- Enable onboarding of multiple QA engineers with minimal ramp-up
+- Produce reliable, maintainable, repeatable, and auditable automation assets
+- Serve as a strong foundation for future enhancements such as API automation, DB validation, AI-assisted test generation, and self-healing automation
+
+====================================================
+2. CORE ARCHITECTURE PRINCIPLES
+====================================================
+Strictly follow these principles:
+- Use layered architecture
+- Follow SOLID principles
+- Follow DRY (Don’t Repeat Yourself)
+- Follow clean code and readability guidelines
+- Prefer reusable abstractions over duplicate code
+- Keep framework modular and easy to extend
+- Separate framework code from business test logic
+- Keep utilities generic and reusable
+- Avoid shortcuts, hacks, and tightly coupled implementations
+
+Framework layers must include:
+- Test Layer
+- Page Object Layer
+- Core Engine Layer
+- Utilities Layer
+- Configuration Layer
+- Test Data Layer
+- Reporting and Logging Layer
+
+====================================================
+3. TECHNOLOGY STACK
+====================================================
+Use the following stack unless explicitly told otherwise:
+- Language: Python 3.11+
+- UI Automation: Playwright
+- Test Runner: Pytest
+- Design Pattern: Page Object Model (POM)
+- Reporting: Allure and/or HTML reporting
+- Logging: Python logging module with structured logs
+- Configuration: YAML / JSON
+- Data Handling: JSON / CSV
+- Execution Style: Headed and Headless
+- Parallel Execution: Supported
+- CI/CD Compatibility: GitHub Actions / Jenkins / Azure DevOps compatible
+
+====================================================
+4. MANDATORY FRAMEWORK CAPABILITIES
+====================================================
+The framework must support the following capabilities:
+- Cross-browser execution (Chromium, Firefox, WebKit)
+- Environment-based execution (dev, qa, uat, prod)
+- Parallel execution
+- Data-driven testing
+- Centralized configuration management
+- Reusable browser lifecycle management
+- Screenshot capture on failure
+- Video capture on failure where feasible
+- Logging at framework and test level
+- Tag-based test execution
+- Test grouping such as smoke, sanity, regression
+- Retry logic for flaky tests where appropriate
+- Clear failure messages and exception handling
+- Easy CI/CD integration
+- Scalable onboarding for new test modules
+- Deterministic and repeatable test execution
+
+====================================================
+5. STRICT PROJECT STRUCTURE
+====================================================
+Whenever generating code, always follow this exact baseline structure unless explicitly asked to change it:
+
+pyplaykit/
+│
+├── config/
+│   ├── config.yaml
+│   ├── environments.yaml
+│
+├── core/
+│   ├── base_page.py
+│   ├── base_test.py
+│   ├── browser_factory.py
+│   ├── playwright_manager.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
+│
+├── test_data/
+│   ├── login_test_data.json
+│
+├── reports/
+│
+├── conftest.py
+├── pytest.ini
+├── requirements.txt
+├── README.md
+└── .gitignore
+
+Do not invent a different folder structure unless explicitly asked.
+
+====================================================
+6. CODING RULES
+====================================================
+Always obey these coding rules:
+- Generate complete, executable code
+- Do not generate pseudocode unless explicitly requested
+- Do not omit imports
+- Do not omit class definitions
+- Do not omit fixtures if required
+- Do not hardcode environment-specific values in test logic
+- Do not hardcode credentials
+- Do not use sleep-based hard waits unless explicitly unavoidable
+- Prefer Playwright’s native wait mechanisms
+- Keep locators inside page classes
+- Use descriptive function and method names
+- Add clear docstrings for public classes and methods
+- Use meaningful logging at key execution points
+- Use reusable base classes where appropriate
+- Minimize duplication
+- Keep tests readable and business-oriented
+- Keep framework utilities generic, decoupled, and reusable
+
+====================================================
+7. PAGE OBJECT MODEL ENFORCEMENT
+====================================================
+Strictly follow Page Object Model:
+- Every application page should have its own page class
+- Each page class should encapsulate:
+  - locators
+  - page actions
+  - page validations
+- Test classes/files should not directly contain raw locator definitions
+- Business flows should be readable from test methods
+- Base page should contain reusable browser/page interaction methods
+
+====================================================
+8. CONFIGURATION AND TEST DATA RULES
+====================================================
+Configuration must be externalized:
+- Environment URLs must come from config files
+- Browser execution settings must come from config files
+- Credentials must be handled securely and never hardcoded
+- Test data should come from JSON / CSV / fixtures
+- Support easy switching between environments
+
+====================================================
+9. LOGGING, REPORTING, AND AUDITABILITY
+====================================================
+The framework must be enterprise-friendly and audit-ready.
+
+Always ensure:
+- Every major action is logged
+- Failures capture useful diagnostics
+- Screenshots are attached for failures where possible
+- Reporting is configurable and CI/CD-friendly
+- Test execution results are reproducible
+- Logs are clean, meaningful, and troubleshooting-friendly
+
+====================================================
+10. TEST DESIGN EXPECTATIONS
+====================================================
+Tests must be:
+- Independent where possible
+- Readable and maintainable
+- Tagged appropriately
+- Easy to execute selectively
+- Compatible with regression suite expansion
+- Written with business intent clarity
+
+Prefer:
+- simple Arrange / Act / Assert flow
+- stable setup and teardown handling
+- assertions with meaningful messages
+- reusable fixtures and helpers
+
+====================================================
+11. FUTURE-READY DESIGN EXPECTATIONS
+====================================================
+This framework should be designed so that future teams can extend it for:
+- API automation
+- database validation
+- service virtualization
+- test data generation
+- CI/CD orchestration
+- AI-assisted test generation
+- self-healing locator approaches
+- enterprise reporting dashboards
+
+So avoid design choices that block future expansion.
+
+====================================================
+12. RESPONSE BEHAVIOR FOR CODE GENERATION
+====================================================
+Whenever asked to generate framework code:
+- Generate full files, not partial snippets
+- Follow the agreed project structure
+- Preserve naming consistency
+- Keep code production-ready
+- Avoid unnecessary refactoring unless explicitly requested
+- If building step-by-step, complete the requested step fully before moving to the next
+- When multiple files are needed, clearly separate them by file name
+- Prefer maintainable enterprise code over quick shortcuts
+
+====================================================
+13. DEVELOPMENT MODE OF OPERATION
+====================================================
+When helping build this framework, work in phases:
+
+Phase 1:
+Generate project structure and base scaffolding
+
+Phase 2:
+Generate core engine components
+- playwright_manager.py
+- browser_factory.py
+- base_page.py
+- base_test.py
+
+Phase 3:
+Generate utility components
+- logger.py
+- data_loader.py
+- assertion_helper.py
+- screenshot_helper.py
+
+Phase 4:
+Generate configuration files
+- config.yaml
+- environments.yaml
+- pytest.ini
+- requirements.txt
+
+Phase 5:
+Generate sample page objects
+- login_page.py
+- dashboard_page.py
+
+Phase 6:
+Generate sample test cases
+- test_login.py
+- test_dashboard.py
+
+Phase 7:
+Generate README and usage instructions
+
+Do not skip phases unless explicitly requested.
+
+====================================================
+14. OUTPUT EXPECTATIONS
+====================================================
+Your output must always reflect the quality expected from:
+"PyPlayKit – Enterprise Test Automation Framework"
+
+This means your responses should be:
+- professional
+- structured
+- production-oriented
+- scalable
+- maintainable
+- consistent
+- enterprise-ready
+
+Always think like an automation architect building a reusable enterprise asset, not a one-off script.
+
+Now begin by helping build PyPlayKit according to these rules.

pyplaykit-1.8.6/.github/prompts/review-execution-plan-and-implement-next-task.prompt.md

@@ -0,0 +1,45 @@
+---
+description: Review the execution plan backlog, pick the next pending task by priority, implement it with tests and coverage, update docs, and commit the changes for PyPlayKit
+name: Review Execution Plan And Implement Next Task
+argument-hint: Optional extra constraints such as a specific wave, file area, or review focus
+agent: agent
+---
+You are working in the `c:\MyProjects\cpkc-pypw-playkit` workspace.
+
+Use `docs/Execution-Plan-Backlog-and-Closure-Tracker.md` as the main source of truth for current roadmap status and sequencing.
+
+Goal:
+- Review the backlog document.
+- Identify the next pending task in priority order.
+- Implement that task in the codebase.
+- Add or update unit tests for all touched core components.
+- Maintain 100% coverage for the touched framework areas.
+- Update the README and any relevant docs to reflect the new status.
+- Mark the completed task items in the backlog document.
+- Commit the changes with a clear commit message.
+
+Execution rules:
+1. Follow the backlog order strictly.
+2. If multiple tasks are pending, choose the first uncompleted item in the highest-priority wave.
+3. Before editing, inspect the existing implementation and tests near the target area.
+4. Make the smallest focused change that completes the selected task.
+5. Add or update tests so the changed code is fully covered.
+6. Run the relevant test subset first, then a broader unit coverage check if needed.
+7. Update `README.md` and any related docs only after the implementation is validated.
+8. Update `docs/Execution-Plan-Backlog-and-Closure-Tracker.md` to mark the task completed and keep the remaining backlog accurate.
+9. Commit only after implementation, validation, and documentation updates are complete.
+
+Selection guidance:
+- Prefer Wave 1 items first if any remain pending.
+- If Wave 1 is complete, continue with the next pending Wave 2 task in order.
+- If the task depends on a config or doc change, include that change in the same implementation slice.
+- If the next pending item is ambiguous, explain the ambiguity and ask for confirmation before editing.
+
+Report back in this structure:
+1. Selected task: the exact backlog item chosen.
+2. Changes made: short summary of code, tests, and doc updates.
+3. Validation: test command(s) run and outcome.
+4. Backlog status: what was marked completed and what remains.
+5. Commit: commit hash and message, if committed.
+
+If no pending task can be completed safely, stop and explain the blocker clearly.

pyplaykit-1.8.6/.github/prompts/run-unit-tests-and-coverage.prompt.md

@@ -0,0 +1,29 @@
+---
+description: Run local unit-test scripts and report pass rate plus coverage summary for PyPlayKit
+name: Unit Tests And Coverage Report
+argument-hint: Optional context such as target OS preference or additional report details
+agent: agent
+---
+You are working in this workspace and must execute the existing local test utilities instead of creating new scripts.
+
+Goal:
+- Run unit tests using the repository scripts.
+- Report unit test pass rate and coverage results clearly.
+
+Execution rules:
+1. Detect platform.
+2. On Windows, run scripts\run_unit_tests_with_coverage.bat.
+3. On Linux or macOS, run bash scripts/run_unit_tests_with_coverage.sh.
+4. Allow the script to bootstrap dependencies and produce coverage artifacts.
+5. Do not modify test code or configuration unless explicitly requested.
+
+Report output in this exact structure:
+1. Execution status: success or failure.
+2. Unit test summary: total, passed, failed, skipped, errors.
+3. Pass rate: percentage with two decimal places.
+4. Coverage summary table: module and percent covered.
+5. Coverage gate result: threshold and whether it passed.
+6. Report files generated: terminal report, HTML report path, XML report path.
+7. If failed: list top failure causes and next corrective actions.
+
+If command output is incomplete, rerun with the same script and provide the most recent complete result.

pyplaykit-1.8.6/.github/prompts/security-audit-and-consolidated-report.prompt.md

@@ -0,0 +1,23 @@
+---
+description: Run the security audit workflow and generate the consolidated security report for PyPlayKit
+mode: agent
+---
+You are working in the `C:\MyProjects\cpkc-pypw-playkit` workspace.
+
+Use the tools and libraries already available in the repository to run the security audit workflow and generate the consolidated security report.
+
+Follow this workflow:
+1. Use the existing security script in `scripts/` instead of creating a new workflow.
+2. On Windows, run `scripts\run_security_reports.bat`.
+3. On Linux/macOS, run `bash scripts/run_security_reports.sh`.
+4. Let the script bootstrap `.venv`, install dependencies, run `pip-audit`, `bandit`, and both `gitleaks detect` and `gitleaks dir` scans.
+5. Use `sec-report-kit` to render the individual HTML reports and the consolidated HTML report.
+6. Confirm the outputs are written under `reports/secutiry_reports/`.
+7. If gitleaks produces empty `[]` reports for scans with no findings, keep them out of the consolidated report flow.
+8. If a scan produces false positives from `.venv` or the downloaded `gitleaks_8.30.1` folder, rely on the repository-level `.gitleaks.toml` allowlist.
+
+When reporting back, summarize:
+- whether the audit completed successfully
+- the generated JSON and HTML report locations
+- any findings that were detected
+- any follow-up action needed for false positives or environment setup

pyplaykit-1.8.6/CHANGELOG.md

@@ -0,0 +1,251 @@
+# Changelog
+
+All notable changes to PyPlayKit are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+---
+
+## [1.3.0] — 2026-07-04
+
+
+### Added
+
+**UI ↔ Database validation (`utils/ui_db_validator.py`)**
+- `UIDbValidator` — bridges the UI layer (`BasePage` / `DataTable`) with the
+  database layer (`BaseDbClient`) for single-call cross-layer assertions
+- `assert_element_equals_db_value(page, selector, sql, column, ...)` — reads the
+  `innerText` of one UI element and compares it to a database column value using
+  type-aware `DataValidator` logic (float tolerance, date/time, string normalisation)
+- `assert_element_attribute_equals_db_value(page, selector, attribute, sql, column, ...)`
+  — reads an HTML attribute (``value``, ``data-id``, ``href``, etc.) instead of text
+- `assert_table_matches_db_rows(table, sql, column_map, ...)` — compares every cell
+  in an HTML `DataTable` component against the corresponding DB column; validates row
+  count, reports all cell mismatches before raising; supports `ignore_row_order` and
+  `float_tolerance`
+- `assert_element_list_matches_db_column(page, item_selector, sql, column, ...)` —
+  compares a list of UI element texts (e.g. search results) against a DB column's
+  values; supports `ignore_order`
+- `assert_page_fields_match_db_row(selector_column_map, page, sql, ...)` — validates
+  multiple page elements against a single DB record in one call; all mismatches
+  collected before raising
+- `UIDbValidator` exported from `pyplaykit`
+- 36 unit tests added in `tests/unit/test_ui_db_validator_unit.py`
+
+---
+
+## [1.2.0] — 2026-07-04
+
+### Added
+
+**Chunked DB validation for large volumes**
+- `BaseDbClient.fetch_chunks(sql, params, chunk_size=10_000)` — generator yielding
+  `list[dict]` batches via `fetchmany()`; keeps only one chunk in memory at a time
+- PostgreSQL (`DbClient`) overrides with a server-side named cursor (`itersize`) for
+  true zero-client-buffer streaming
+- All 7 drivers implement `_open_cursor()` and `_rows_to_dicts()` to support the base
+  class fallback (SQLite, MySQL, SQL Server, Oracle, DB2, Snowflake)
+- `DbValidationHelper.assert_row_counts_match_chunked()` — COUNT(*) queries, safe for
+  any table size
+- `DbValidationHelper.assert_datasets_match_chunked()` — streams source chunks,
+  compares against target chunk-by-chunk; `max_errors` cap prevents unbounded error lists
+- `DbValidationHelper.diff_datasets_chunked()` — streaming diff summary without raising
+- `ChunkedDbDataSource` — wraps `fetch_chunks()` as `iter_chunks()`
+- `DataSourceFactory.create_db_chunked()` — factory method for streaming sources
+- `ChunkedDbDataSource` exported from `pyplaykit`
+
+**Transformation-aware and rule-based src-to-tgt validation**
+- `ColumnSpec` — per-column transformation descriptor: `target` (rename), `cast`,
+  `lookup` (value substitution dict), `transform` (callable), `date_format` (strftime),
+  `null_default`, `tolerance` (float), `ignore`
+- `TransformationValidator` — applies `ColumnSpec` map to source rows producing
+  target-shaped rows; `assert_matches()`, `assert_matches_chunked()`, `diff()`
+- `RowRule` — predicate on a single row; `apply_to='source'|'target'|'both'`;
+  `severity='error'|'warning'`
+- `PairRule` — predicate on a matched `(src_row, tgt_row)` pair
+- `Violation` — structured violation record with rule_name, severity, row_index,
+  key_value, message, actual_values
+- `RuleValidator` — evaluates lists of RowRules and PairRules; collects ALL violations
+  before raising; `assert_rows()`, `assert_pairs()`, `assert_all()`,
+  `validate_rows()`, `validate_pairs()`, `validate_all()`, `assert_rows_chunked()`
+- All 6 symbols (`ColumnSpec`, `TransformationValidator`, `RowRule`, `PairRule`,
+  `RuleValidator`, `Violation`) exported from `pyplaykit`
+
+---
+
+## [1.1.0] — 2026-07-04
+
+### Added
+
+- `utils/graphql_client.py` — `GraphQLClient` (query, mutate, execute), `GraphQLResponse`
+  (data, errors, has_errors, first_error_message), `GraphQLValidator` (assert_no_errors,
+  assert_has_errors, assert_error_message_contains, assert_data_key, assert_data_value,
+  assert_status_code, assert_response_time_less_than); all exported from `pyplaykit`
+- `utils/soap_client.py` — `SoapClient` (WSDL auto-discovery, WS-Security UsernameToken,
+  call by operation name), `SoapResponse` (as_dict zeep→plain-dict conversion),
+  `SoapValidator` (assert_no_fault, assert_result_key, assert_result_value,
+  assert_result_contains, assert_response_time_less_than); all exported from `pyplaykit`
+- `utils/data_loader.py` — `load_xls()` for legacy `.xls` files via `xlrd`
+- `utils/data_source.py` — `.xls` wired into `FileDataSource._LOADERS`; all 4 comparison
+  combinations (db↔db, file↔db, db↔file, file↔file) now support csv, xlsx, xls, json
+- `docs/FRAMEWORK_CONTRIBUTION_GUIDE.md` — step-by-step guide for QE engineers adding
+  reusable framework modules, including AI prompt instructions
+- `zeep>=4.2.1`, `gql[httpx]>=3.5.0`, `xlrd>=2.0.1` added to declared dependencies
+
+### Changed
+
+- `utils/api_client.py` module docstring updated to document WebSocket and gRPC as
+  explicitly not supported, with guidance on alternatives
+
+---
+
+## [1.0.0] — 2026-07-04
+
+First stable release. Completes all 16 pre-deployment gaps identified in `GAP_TRACKER.md`.
+
+### Added
+
+**pip install mode (GAP-01)**
+- `pyplaykit/` namespace package with explicit public API (`ApiClient`, `BasePage`, `ResponseValidator`, `AuthTokenManager`, `DataValidator`, `DbClient`, `BaseComponent`, `DataTable`, `FormField`, `Modal`, `get_logger`, DB isolation helpers)
+- `pyplaykit/plugin.py` — all framework fixtures registered as a `pytest11` entry-point so `pip install pyplaykit` delivers fixtures without copying files
+- `pyplaykit/cli.py` — `pyplaykit init` scaffolds `config/`, `test_data/`, `conftest.py`, and example test in a new project
+- `--pyplaykit-config` CLI flag and `PYPLAYKIT_CONFIG` env var for config directory override
+
+**Orchestration enforcement (GAP-16)**
+- `orchestration/enforcer.py` — `OrchestrationEnforcer`: reorders collected tests into topological suite order; skips dependent suite tests when prerequisites fail
+- `--pyplaykit-orchestration` flag enables enforcement (off by default for backward compatibility)
+- `config/config.yaml` suite entries now support a `marker` field to map suite IDs to pytest markers
+
+**Lazy Playwright startup (GAP-02)**
+- `pytest_collection_finish` hook detects UI tests via `@pytest.mark.ui` or `--pyplaykit-browser`
+- `has_ui_tests` session fixture; `playwright_manager` yields `None` when no UI tests are present
+- Database-only and API-only test runs no longer start the Playwright runtime
+
+**UI component abstraction (GAP-06)**
+- `components/` package: `BaseComponent`, `DataTable`, `Modal`, `FormField`
+- All actions root-scoped inside a configurable `root_selector`
+
+**BasePage interaction methods (GAP-04)**
+- `select_option`, `upload_file`, `press_key`, `key_chord`, `hover`, `drag_to`, `scroll_into_view`
+- `switch_to_frame` (returns `BasePage` scoped to iframe via `_FramePage` adapter)
+- `open_new_tab`, `get_tab(index)`, `wait_for_network_idle`
+
+**Database test isolation (GAP-07)**
+- `utils/db_fixtures.py`: `DbTransaction` (always-rollback), `DbSeeder` (INSERT + DELETE cleanup), `DbCleaner` (TRUNCATE CASCADE)
+- `db_transaction`, `db_seed`, `db_clean` fixtures in `conftest.py` / `pyplaykit.plugin`; all yield `None` gracefully when no DB is configured
+
+**DB connection pooling (GAP-09)**
+- `utils/db_pool.py`: `DbConnectionPool` wrapping `psycopg2.pool.ThreadedConnectionPool`
+- `db_pool` session fixture, `db_client` function fixture; xdist-safe (one pool per worker)
+
+**API client modernisation (GAP-10)**
+- Replaced `urllib` with `httpx`; `ApiClient` gains `transport=` injection point for testing
+- Context manager support (`__enter__` / `__exit__` / `close()`)
+
+**ResponseValidator expansion (GAP-11)**
+- `assert_status_in`, `assert_jsonpath` (JMESPath), `assert_header`, `assert_header_contains`, `assert_pagination`, `assert_error_body`
+
+**Auth token fixture (GAP-12)**
+- `utils/auth_manager.py`: `AuthTokenManager` — lazy fetch, cache, 401-triggered refresh
+- `auth_token_manager` and `auth_token` session fixtures
+
+**Real integration test suite (GAP-13)**
+- `tests/integration/framework/test_api_integration.py` — 16 tests against jsonplaceholder.typicode.com
+- `tests/integration/framework/test_db_integration.py` — 16 tests against in-memory SQLite
+- Integration tests excluded from standard `pytest` run via `norecursedirs`
+
+**Self-healing locator guidance (GAP-05)**
+- `docs/RESILIENCE_GUIDE.md`; `confidence_threshold` config key with inline documentation
+- Warning logged when confidence drops below threshold
+
+**Secrets management (GAP-15)**
+- `python-dotenv` loaded at conftest startup (`override=False`)
+- `.env.example` with all required env vars documented
+
+**Semantic versioning (GAP-03)**
+- `CHANGELOG.md` in Keep a Changelog format
+- `scripts/build_internal_package.py` reads version from `pyproject.toml` automatically
+
+### Changed
+
+- `pyproject.toml` — added `httpx>=0.27.0`, `jmespath>=1.0.0` to declared dependencies; added `[project.entry-points."pytest11"]` and `[project.scripts]`; added `pyplaykit*` and `components*` to `packages.find`
+- `pytest.ini` — removed internal project markers; added `--cov=pyplaykit --cov=components`; `norecursedirs = tests/integration`
+- `config/config.yaml` — added `database.pool_*` keys, `resilience.confidence_threshold`, `orchestration.suites[].marker`
+- `conftest.py` — added `--pyplaykit-config`, `--pyplaykit-orchestration` options; lazy `playwright_manager`; all new fixtures
+
+### Fixed
+
+- Removed empty root `__init__.py` that shadowed the `pyplaykit/` namespace package
+
+---
+
+## [0.1.0] — 2026-07-04
+
+Initial release of the PyPlayKit enterprise automation framework.
+
+### Added
+
+**Core engine**
+- `PlaywrightManager` — session-scoped Playwright lifecycle management
+- `BrowserFactory` — cross-browser launch support (Chromium, Firefox, WebKit)
+- `BasePage` — page object base class with resilience integration
+
+**Utilities**
+- `ApiClient` — HTTP client with retry logic and observability hooks
+- `ResponseValidator` — HTTP response assertion helpers
+- `DataValidator` — record-level field, type, and value assertions
+- `DbClient` / `DbClientFactory` — multi-database client with factory pattern (PostgreSQL, MySQL, SQLite, SQL Server, Oracle, DB2, Snowflake)
+- `DbValidationHelper` — database-level assertion helpers including src/tgt migration comparison
+- `TDM` — test data management with synthetic generation, masking, and environment provisioning
+- `ObservabilityTracker` — session-level metrics, failure classification, KPI and persona reports
+- `ConfigReader` — YAML-based environment-aware configuration resolution
+- `EnvironmentValidator` — pre-suite readiness checks (URL, DB, API health)
+
+**Plugin architecture**
+- `PluginRegistry` — lifecycle hook dispatch (`on_session_start`, `on_test_result`, `on_session_finish`)
+- Built-in plugins: `ApiPlugin`, `DataPlugin`, `SecurityPlugin`
+
+**Orchestration**
+- `build_orchestration_plan()` — dependency-aware suite planning with cycle detection and topological sort
+
+**Self-healing locators**
+- `resolve_visible_locator()` — fallback selector chain with confidence scoring and JSONL audit log
+
+**Integrations**
+- File and API adapters for Jira and test management export
+
+**Configuration**
+- `config/config.yaml` — framework defaults
+- `config/environments.yaml` — multi-environment (dev, qa, uat, prod) URL and database config
+- `config/projects/` — per-project configuration templates (timelyquote, dispatcho, customs_modernization)
+
+**CI/CD**
+- GitHub Actions pipeline: build → unit tests + security audit (parallel) → E2E smoke tests
+- Separate workflows: `unit-tests.yml`, `build.yml`, `e2e-tests.yml`, `security-audit.yml`
+- PyPI and Test PyPI publish workflows (tag-triggered)
+
+**Security**
+- Bandit static analysis, pip-audit dependency audit, Gitleaks secret scanning
+- Self-bootstrapping security report scripts
+
+**Documentation**
+- 17 markdown guides covering architecture, API testing, data validation, multi-DB support, test organisation, QE visual guide, contributing guide, and quick-start
+
+### Notes
+- Resilience, TDM, orchestration, and integrations are **disabled by default** — enable in `config/config.yaml`
+- Default database driver is PostgreSQL (`psycopg2-binary`); other drivers are optional installs
+- Unit test coverage gate: 95%
+
+---
+
+[Unreleased]: https://github.com/ShanKonduru/pyplaykit/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/ShanKonduru/pyplaykit/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/ShanKonduru/pyplaykit/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/ShanKonduru/pyplaykit/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/ShanKonduru/pyplaykit/compare/v0.1.0...v1.0.0
+[0.1.0]: https://github.com/ShanKonduru/pyplaykit/releases/tag/v0.1.0