Metadata-Version: 2.4
Name: pyplaykit
Version: 1.8.13
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==9.1.1
Requires-Dist: pytest-cov==7.1.0
Requires-Dist: pytest-xdist==3.8.0
Requires-Dist: pytest-rerunfailures==16.4
Requires-Dist: PyYAML==6.0.2
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: api-client
Requires-Dist: httpx>=0.27.0; extra == "api-client"
Requires-Dist: jmespath>=1.0.0; extra == "api-client"
Provides-Extra: graphql-client
Requires-Dist: gql[httpx]>=3.5.0; extra == "graphql-client"
Requires-Dist: httpx>=0.27.0; extra == "graphql-client"
Provides-Extra: soap-client
Requires-Dist: zeep>=4.2.1; extra == "soap-client"
Provides-Extra: data-comparison
Requires-Dist: pandas>=2.0.0; extra == "data-comparison"
Requires-Dist: openpyxl>=3.1.0; extra == "data-comparison"
Requires-Dist: xlrd>=2.0.1; extra == "data-comparison"
Provides-Extra: postgresql
Requires-Dist: psycopg2-binary>=2.9.0; extra == "postgresql"
Provides-Extra: sqlserver
Requires-Dist: pyodbc>=4.0.0; extra == "sqlserver"
Provides-Extra: oracle
Requires-Dist: oracledb>=1.0.0; extra == "oracle"
Provides-Extra: db2
Requires-Dist: ibm_db>=3.0.0; extra == "db2"
Requires-Dist: ibm_db_dbi>=3.0.0; extra == "db2"
Provides-Extra: informix
Requires-Dist: IfxPy>=3.0.0; extra == "informix"
Requires-Dist: IfxPyDbi>=3.0.0; extra == "informix"
Provides-Extra: mysql
Requires-Dist: mysql-connector-python>=8.0.0; extra == "mysql"
Provides-Extra: snowflake
Requires-Dist: snowflake-connector-python>=3.0.0; extra == "snowflake"
Provides-Extra: allure-reporting
Requires-Dist: allure-pytest==2.16.0; extra == "allure-reporting"
Provides-Extra: html-reporting
Requires-Dist: pytest-html==4.2.0; extra == "html-reporting"
Provides-Extra: all-databases
Requires-Dist: psycopg2-binary>=2.9.0; extra == "all-databases"
Requires-Dist: pyodbc>=4.0.0; extra == "all-databases"
Requires-Dist: oracledb>=1.0.0; extra == "all-databases"
Requires-Dist: ibm_db>=3.0.0; extra == "all-databases"
Requires-Dist: ibm_db_dbi>=3.0.0; extra == "all-databases"
Requires-Dist: IfxPy>=3.0.0; extra == "all-databases"
Requires-Dist: IfxPyDbi>=3.0.0; extra == "all-databases"
Requires-Dist: mysql-connector-python>=8.0.0; extra == "all-databases"
Requires-Dist: snowflake-connector-python>=3.0.0; extra == "all-databases"
Provides-Extra: all-api-clients
Requires-Dist: httpx>=0.27.0; extra == "all-api-clients"
Requires-Dist: jmespath>=1.0.0; extra == "all-api-clients"
Requires-Dist: gql[httpx]>=3.5.0; extra == "all-api-clients"
Requires-Dist: zeep>=4.2.1; extra == "all-api-clients"
Provides-Extra: all
Requires-Dist: httpx>=0.27.0; extra == "all"
Requires-Dist: jmespath>=1.0.0; extra == "all"
Requires-Dist: gql[httpx]>=3.5.0; extra == "all"
Requires-Dist: zeep>=4.2.1; extra == "all"
Requires-Dist: pandas>=2.0.0; extra == "all"
Requires-Dist: openpyxl>=3.1.0; extra == "all"
Requires-Dist: xlrd>=2.0.1; extra == "all"
Requires-Dist: psycopg2-binary>=2.9.0; extra == "all"
Requires-Dist: pyodbc>=4.0.0; extra == "all"
Requires-Dist: oracledb>=1.0.0; extra == "all"
Requires-Dist: ibm_db>=3.0.0; extra == "all"
Requires-Dist: ibm_db_dbi>=3.0.0; extra == "all"
Requires-Dist: IfxPy>=3.0.0; extra == "all"
Requires-Dist: IfxPyDbi>=3.0.0; extra == "all"
Requires-Dist: mysql-connector-python>=8.0.0; extra == "all"
Requires-Dist: snowflake-connector-python>=3.0.0; extra == "all"
Requires-Dist: allure-pytest==2.16.0; extra == "all"
Requires-Dist: pytest-html==4.2.0; extra == "all"

# PyPlayKit - Enterprise Test Automation Framework

**Tagline**: A modular, scalable, and CI/CD-ready Python + Playwright framework for enterprise automation supporting multiple projects and 50+ QE engineers.

---

## Overview

PyPlayKit is a **multi-project enterprise test automation framework** built with Python, Playwright, and Pytest. It supports multiple independent projects with UI, API, Database, and Integration testing capabilities.

**Key Features**:
- 🏢 **Multi-Project Support**: Separate test organization for multiple applications
- 👥 **Scalable**: Designed for 50-100 QE engineers working simultaneously
- 🎯 **Zero Merge Conflicts**: Project-first organization eliminates conflicts
- 📊 **Data Comparison**: File-to-File, File-to-DB, DB-to-File validation (Excel, CSV, JSON)
- 📈 **Interactive HTML Reports**: Filterable validation reports with KPIs ⭐ **NEW**
- 📚 **Comprehensive Documentation**: 8,700+ lines across 15+ guides
- 🔧 **Extensible**: Plugin architecture with orchestration support
- 🔍 **Self-Healing**: Locator recovery with fallback chains
- 🔭 **Observable**: Comprehensive metrics and reporting

---

## Quick Start

### Prerequisites
- Python 3.11 or higher
- pip

### Setup (5 minutes)

```powershell
# Windows PowerShell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
playwright install
pip install -r requirements-dev.txt
```

### Set Environment Variables

```powershell
# Required for tests
$env:PYPLAYKIT_TEST_USERNAME="standard_user"
$env:PYPLAYKIT_TEST_PASSWORD="secret_sauce"
```

### Run Tests

```bash
# Run all smoke tests
pytest -m smoke

# Run specific project tests
pytest tests/projects/timelyquote/
pytest tests/projects/dispatcho/
pytest tests/projects/customs_modernization/

# Run by marker
pytest -m timelyquote
pytest -m dispatcho
pytest -m customs_modernization
```

---

## Architecture

### Multi-Project Structure

PyPlayKit supports multiple independent projects with separate test suites:

```
tests/
├── projects/                              # Multi-project organization
│   ├── timelyquote/                      # Project 1: Quote management
│   │   ├── functional/
│   │   │   ├── ui/                       # UI tests
│   │   │   ├── api/                      # API tests
│   │   │   └── database/                 # Database tests
│   │   └── integration/                  # Integration tests
│   │
│   ├── dispatcho/                        # Project 2: Dispatch & logistics
│   │   ├── functional/
│   │   │   ├── ui/
│   │   │   ├── api/
│   │   │   └── database/
│   │   └── integration/
│   │
│   └── customs_modernization/            # Project 3: Customs management
│       ├── functional/
│       │   ├── ui/
│       │   ├── api/
│       │   └── database/
│       └── integration/
│
└── unit/                                  # Framework unit tests
```

### Layered Architecture

1. **Test Layer** (`tests/`) - Multi-project organization with Pytest
2. **Page Object Layer** (`pages/`) - Encapsulated locators per project
3. **Core Engine Layer** (`core/`) - Playwright lifecycle and browser management
4. **Utilities Layer** (`utils/`) - Logging, data loading, assertions, API clients
5. **Configuration Layer** (`config/`) - Framework + project-specific configs
6. **Plugin Layer** (`plugins/`) - Extensible plugin architecture
7. **Orchestration Layer** (`orchestration/`) - Dependency-aware execution
8. **Resilience Layer** (`resilience/`) - Self-healing locator resolution
9. **Integration Layer** (`integrations/`) - Jira and test management adapters

---

## Project Structure

```
pyplaykit/
├── config/
│   ├── config.yaml                       # Framework configuration
│   ├── environments.yaml                 # Global environments
│   └── projects/                         # Project-specific configs
│       ├── timelyquote.yaml
│       ├── dispatcho.yaml
│       └── customs_modernization.yaml
│
├── core/
│   ├── base_page.py
│   ├── base_test.py
│   ├── browser_factory.py
│   └── playwright_manager.py
│
├── integrations/
│   └── adapters.py
│
├── orchestration/
│   └── planner.py
│
├── plugins/
│   ├── base.py
│   ├── registry.py
│   ├── api_plugin.py
│   ├── data_plugin.py
│   └── security_plugin.py
│
├── resilience/
│   └── locator_recovery.py
│
├── pages/                                # Page objects per project
│   ├── timelyquote/
│   ├── dispatcho/
│   └── customs_modernization/
│
├── tests/
│   ├── projects/                         # All project tests
│   │   ├── timelyquote/
│   │   ├── dispatcho/
│   │   └── customs_modernization/
│   └── unit/                             # Framework unit tests
│
├── utils/
│   ├── logger.py
│   ├── data_loader.py
│   ├── assertion_helper.py
│   ├── api_client.py
│   ├── response_validator.py
│   ├── data_validator.py
│   ├── config_reader.py
│   ├── observability.py
│   ├── environment_validator.py
│   └── tdm.py
│
├── test_data/                            # Test data per project
│   ├── timelyquote/
│   ├── dispatcho/
│   └── customs_modernization/
│
├── reports/                              # Test reports and artifacts
│
├── conftest.py                           # Pytest configuration
├── pytest.ini                            # Pytest settings
├── pyproject.toml                        # Package metadata
├── requirements.txt                      # Dependencies
└── README.md                             # This file
```

---

## Current Projects

### 1. TimelyQuote
**Description**: Quote management and generation system  
**Tests**: `tests/projects/timelyquote/`  
**Config**: `config/projects/timelyquote.yaml`  
**Marker**: `@pytest.mark.timelyquote`

**Run tests**:
```bash
pytest tests/projects/timelyquote/
pytest -m timelyquote
```

### 2. Dispatcho
**Description**: Dispatch and logistics management system  
**Tests**: `tests/projects/dispatcho/`  
**Config**: `config/projects/dispatcho.yaml`  
**Marker**: `@pytest.mark.dispatcho`

**Run tests**:
```bash
pytest tests/projects/dispatcho/
pytest -m dispatcho
```

### 3. Customs Modernization
**Description**: Customs management system modernization  
**Tests**: `tests/projects/customs_modernization/`  
**Config**: `config/projects/customs_modernization.yaml`  
**Marker**: `@pytest.mark.customs_modernization`

**Run tests**:
```bash
pytest tests/projects/customs_modernization/
pytest -m customs_modernization
```

---

## Running Tests

### By Project

```bash
# TimelyQuote
pytest tests/projects/timelyquote/
pytest tests/projects/timelyquote/ -m smoke

# Dispatcho
pytest tests/projects/dispatcho/
pytest tests/projects/dispatcho/ -m smoke

# Customs Modernization
pytest tests/projects/customs_modernization/
pytest tests/projects/customs_modernization/ -m smoke
```

### By Test Type

```bash
# UI tests only
pytest tests/projects/timelyquote/functional/ui/

# API tests only
pytest tests/projects/dispatcho/functional/api/

# Database tests only
pytest tests/projects/customs_modernization/functional/database/

# Integration tests only
pytest tests/projects/timelyquote/integration/
```

### By Marker

```bash
# Project markers
pytest -m timelyquote
pytest -m dispatcho
pytest -m customs_modernization

# Test type markers
pytest -m api
pytest -m ui
pytest -m database
pytest -m integration

# Combined markers
pytest -m "timelyquote and smoke"
pytest -m "dispatcho and api"
```

### All Projects

```bash
# Run smoke tests for all projects
pytest tests/projects/ -m smoke

# Run all tests for all projects
pytest tests/projects/

# Run specific test type across all projects
pytest tests/projects/ -m api
pytest tests/projects/ -m ui
```

### With Options

```bash
# Different environment
pytest tests/projects/timelyquote/ --pyplaykit-env qa
pytest tests/projects/dispatcho/ --pyplaykit-env uat

# Different browser
pytest tests/projects/timelyquote/ --pyplaykit-browser firefox --pyplaykit-headed

# Parallel execution
pytest tests/projects/timelyquote/ -n 4

# With readiness checks
pytest tests/projects/timelyquote/ --pyplaykit-readiness-check
```

---

## Available pytest CLI Options

Registered in `conftest.py`:
- `--pyplaykit-env` — target environment (dev, qa, uat, prod)
- `--pyplaykit-browser` — browser (chromium, firefox, webkit)
- `--pyplaykit-headed` — disable headless mode
- `--pyplaykit-base-url` — override base URL
- `--pyplaykit-readiness-check` — enable environment readiness checks

---

## Test Markers

Defined in `pytest.ini`:

### Suite Markers
- `@pytest.mark.smoke` - Critical path tests
- `@pytest.mark.sanity` - Quick validation tests
- `@pytest.mark.regression` - Full regression suite

### Project Markers
- `@pytest.mark.timelyquote` - TimelyQuote tests
- `@pytest.mark.dispatcho` - Dispatcho tests
- `@pytest.mark.customs_modernization` - Customs Modernization tests

### Test Type Markers
- `@pytest.mark.ui` - UI functional tests
- `@pytest.mark.api` - API functional tests
- `@pytest.mark.database` - Database validation tests
- `@pytest.mark.integration` - Integration tests

### Feature Markers
- `@pytest.mark.login` - Login functionality
- `@pytest.mark.quotes` - Quote management
- `@pytest.mark.logistics` - Logistics/dispatch
- `@pytest.mark.customs_mgmt` - Customs management

---

## Adding Tests

### Where to Add Your Tests

| Test Type | Location | Example |
|-----------|----------|---------|
| **TimelyQuote UI** | `tests/projects/timelyquote/functional/ui/<feature>/` | `test_create_quote.py` |
| **TimelyQuote API** | `tests/projects/timelyquote/functional/api/<domain>/` | `test_quotes_api.py` |
| **Dispatcho UI** | `tests/projects/dispatcho/functional/ui/<feature>/` | `test_dispatch_dashboard.py` |
| **Dispatcho API** | `tests/projects/dispatcho/functional/api/<domain>/` | `test_orders_api.py` |
| **Customs UI** | `tests/projects/customs_modernization/functional/ui/<feature>/` | `test_declarations.py` |
| **Customs API** | `tests/projects/customs_modernization/functional/api/<domain>/` | `test_customs_api.py` |
| **Database tests** | `tests/projects/<project>/functional/database/<category>/` | `test_data_integrity.py` |
| **Integration tests** | `tests/projects/<project>/integration/` | `test_workflow_e2e.py` |

### Example: Adding a New Test

**1. Create page object** (for UI tests):
```python
# pages/timelyquote/quote_creation_page.py
from core.base_page import BasePage

class QuoteCreationPage(BasePage):
    CUSTOMER_SELECT = "#customer"
    SAVE_BUTTON = "#save"
    
    def create_quote(self, customer: str):
        self.click(self.CUSTOMER_SELECT)
        self.click(f"option:has-text('{customer}')")
        self.click(self.SAVE_BUTTON)
```

**2. Create test**:
```python
# tests/projects/timelyquote/functional/ui/quotes/test_create_quote.py
import pytest
from pages.timelyquote.quote_creation_page import QuoteCreationPage

@pytest.mark.timelyquote
@pytest.mark.smoke
@pytest.mark.quotes
def test_create_quote_with_valid_customer(page, runtime_options):
    quote_page = QuoteCreationPage(page, runtime_options["resilience_policy"])
    quote_page.navigate(runtime_options["base_url"] + "/quotes/new")
    quote_page.create_quote("ACME Corp")
    assert quote_page.is_quote_saved()
```

**3. Run your test**:
```bash
pytest tests/projects/timelyquote/functional/ui/quotes/test_create_quote.py -v
```

---

## Data Comparison Patterns

PyPlayKit provides comprehensive data comparison capabilities using the built-in `DataValidator` utility.

### Prerequisites for Data Comparison

```bash
# Option 1: Install with optional dependencies
pip install pyplaykit[data-comparison]

# Option 2: Install dependencies separately
pip install pandas openpyxl

# Option 3: Use the examples requirements file
pip install -r examples/requirements.txt
```

**Note**: Data comparison features require pandas and openpyxl. The framework will work without them for UI/API/Database testing.

### Supported Comparison Types

| Comparison Type | Use Case | Example |
|----------------|----------|---------|
| **File-to-File** | Compare Excel, CSV, JSON files | Validate data export/import |
| **File-to-Database** | Verify data loads into database | ETL validation |
| **Database-to-File** | Validate database exports | Report generation testing |

### Quick Example: Excel-to-Excel Comparison

**Simple One-Line API** (Recommended for QE Engineers):

```python
import pytest
from utils.data_comparison_utils import compare_excel_files

@pytest.mark.data
def test_compare_excel_files(logger):
    # ONE function call - framework handles everything!
    result = compare_excel_files(
        source_file="report_baseline.xlsx",
        target_file="report_current.xlsx",
        float_tolerance=0.01
    )
    
    # Check results
    logger.info(f"{result.summary}")
    logger.info(f"HTML Report: {result.report_path}")
    
    if not result.passed:
        pytest.fail(f"Validation failed! {result.failed_count} discrepancies found.")
```

**Manual Validation** (For custom logic):

```python
import pytest
import pandas as pd
from pyplaykit import DataValidator

@pytest.mark.data
def test_compare_with_custom_logic(logger):
    df1 = pd.read_excel("baseline.xlsx")
    df2 = pd.read_excel("current.xlsx")
    
    records1 = df1.to_dict('records')
    records2 = df2.to_dict('records')
    
    for idx, (r1, r2) in enumerate(zip(records1, records2)):
        DataValidator.assert_records_equal(r1, r2)
    
    logger.info("✓ Files match!")
```

### DataValidator Methods

| Method | Purpose |
|--------|---------|
| `assert_records_equal()` | Compare two dictionaries exactly |
| `assert_floats_equal()` | Compare numeric values with tolerance |
| `assert_strings_equal_normalized()` | Compare strings with normalization |
| `assert_collection_contains_record()` | Check if record exists in collection |
| `assert_datetimes_equal()` | Compare datetime values |

### Runnable Examples

See **[examples/data_comparison_examples.py](examples/data_comparison_examples.py)** for 8 complete examples:

```bash
# Run all data comparison examples
pytest examples/data_comparison_examples.py -v -s

# Run specific example
pytest examples/data_comparison_examples.py::test_excel_to_excel_basic -v -s
```

### Interactive HTML Reports ⭐ **NEW**

**Option 1: Automatic Report Generation** (Recommended):

```python
from utils.data_comparison_utils import compare_excel_files

# Framework automatically tracks ALL mismatches and generates HTML report
result = compare_excel_files(
    source_file="baseline.xlsx",
    target_file="current.xlsx",
    float_tolerance=0.01
)

# Result includes:
print(f"Passed: {result.passed}")
print(f"Matched: {result.passed_count}")
print(f"Failed: {result.failed_count}")
print(f"Total Mismatches: {result.total_mismatches}")
print(f"Report: {result.report_path}")
```

**Available Functions:**

*File-to-File:*
- `compare_excel_files()` - Excel to Excel
- `compare_csv_files()` - CSV to CSV

*File-to-Database:*
- `compare_excel_to_db()` - Excel to Database
- `compare_csv_to_db()` - CSV to Database

*Database-to-File:*
- `compare_db_to_excel()` - Database to Excel
- `compare_db_to_csv()` - Database to CSV

*Database-to-Database:*
- `compare_db_to_db()` - Database to Database

*Advanced:*
- `compare_dataframes()` - DataFrame to DataFrame (custom sources)

**Option 2: Manual Report Building** (Advanced):

```python
from utils.data_comparison_report import DataComparisonReport

# For custom comparison logic
report = DataComparisonReport()
report.set_comparison_type("FILE_TO_FILE (Excel)")
report.set_source("baseline.xlsx", 100)
report.set_target("current.xlsx", 100)

# Your custom comparison logic here...
# report.add_mismatch(...) for each discrepancy

report.generate_report("reports/validation.html")
```

**Report Features:**
- 📊 KPI dashboard with pass/fail rates
- 🔍 Column-level filtering and search
- 📋 Row-by-row mismatch details
- 🎨 Color-coded status indicators
- 📱 Mobile-responsive design
- ⚡ Zero manual mismatch tracking required!

**Examples:**
- **Simple API**: [examples/simple_comparison_examples.py](examples/simple_comparison_examples.py) ⭐ **Recommended**
- **Manual Building**: [examples/data_comparison_with_html_report.py](examples/data_comparison_with_html_report.py)

### Full Documentation

- **[docs/PIP_INSTALL_GUIDE.md](docs/PIP_INSTALL_GUIDE.md#step-8--data-comparison-patterns)** - Complete patterns guide
- **[examples/README.md](examples/README.md)** - Examples documentation
- **[docs/DATA_VALIDATION_GUIDE.md](docs/DATA_VALIDATION_GUIDE.md)** - Advanced validation

---

## Unit Testing and Coverage

```bash
# Windows
scripts\run_unit_tests_with_coverage.bat

# Linux/macOS
bash scripts/run_unit_tests_with_coverage.sh

# View coverage report
# Open reports/coverage-html/index.html in browser
```

**Coverage target**: 95% (configured in `pytest.ini`)

---

## Security Scanning

```bash
# Windows
scripts\run_security_reports.bat

# Linux/macOS
bash scripts/run_security_reports.sh

# View reports
# Open reports/security_reports/html/security_consolidated_report.html
```

---

## Building Internal Package

```bash
# Windows
scripts\build_internal_package.bat

# Linux/macOS
bash scripts/build_internal_package.sh
```

---

## Configuration

### Framework Configuration
- `config/config.yaml` - Framework defaults
- `config/environments.yaml` - Global environment settings

### Project Configuration
- `config/projects/timelyquote.yaml` - TimelyQuote settings
- `config/projects/dispatcho.yaml` - Dispatcho settings
- `config/projects/customs_modernization.yaml` - Customs settings

Each project config includes:
- Environment-specific URLs
- API endpoints
- Test users
- Feature flags

---

## Documentation for QE Engineers

### Quick Start
- **[QUICK_START_QE.md](QUICK_START_QE.md)** - Get started in 10 minutes
- **[TEST_LOCATION_CHEATSHEET.md](TEST_LOCATION_CHEATSHEET.md)** - One-page reference
- **[COMMANDS_FOR_YOUR_PROJECTS.md](COMMANDS_FOR_YOUR_PROJECTS.md)** - Command reference
- **[docs/PIP_INSTALL_GUIDE.md](docs/PIP_INSTALL_GUIDE.md)** - Pip install guide with data comparison patterns

### Implementation
- **[YOUR_PROJECTS_IMPLEMENTATION_GUIDE.md](YOUR_PROJECTS_IMPLEMENTATION_GUIDE.md)** - Step-by-step guide
- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Comprehensive contributor guide
- **[FINAL_PROJECT_SETUP.md](FINAL_PROJECT_SETUP.md)** - Complete setup overview

### Architecture
- **[docs/MULTI_PROJECT_STRUCTURE.md](docs/MULTI_PROJECT_STRUCTURE.md)** - Multi-project architecture
- **[docs/TEST_ORGANIZATION.md](docs/TEST_ORGANIZATION.md)** - Organization strategy
- **[docs/QE_VISUAL_GUIDE.md](docs/QE_VISUAL_GUIDE.md)** - Visual guide with diagrams

### Data Comparison & Validation
- **[examples/data_comparison_examples.py](examples/data_comparison_examples.py)** - Runnable examples for Excel, CSV, DB comparison
- **[examples/README.md](examples/README.md)** - Examples documentation
- **[docs/DATA_VALIDATION_GUIDE.md](docs/DATA_VALIDATION_GUIDE.md)** - Advanced validation patterns

### Project Guides
- **[tests/projects/timelyquote/README.md](tests/projects/timelyquote/README.md)** - TimelyQuote guide
- **[tests/projects/dispatcho/README.md](tests/projects/dispatcho/README.md)** - Dispatcho guide
- **[tests/projects/customs_modernization/README.md](tests/projects/customs_modernization/README.md)** - Customs guide

---

## Key Features

### Multi-Project Support
- Separate test suites per project
- Independent configurations
- Project-specific page objects and test data
- No merge conflicts between projects

### Scalability
- Designed for 50-100 QE engineers
- Clear ownership boundaries
- Parallel development across projects
- Independent CI/CD pipelines

### Test Types
- **UI Testing**: Playwright-based with page objects
- **API Testing**: REST API validation with response validators
- **Database Testing**: Data integrity and migration validation
- **Integration Testing**: Cross-layer consistency validation

### Observability
- Session-level metrics and KPIs
- Automatic failure classification
- Flaky test detection
- Multi-persona reports (engineering, QA, leadership)

### Resilience
- Self-healing locators with fallback chains
- DOM retry mechanisms
- Confidence scoring
- Optional audit logging

### Plugin Architecture
- Extensible hook system
- Built-in plugins: API, Data, Security
- Config-gated activation
- Session and test-level hooks

---

## Wave Implementation Status

**Wave 1** ✅ Complete:
- Observability tracker
- Environment readiness checks
- Session-level reporting

**Wave 2** ✅ Complete:
- Test data management utilities
- Multi-level persona reports
- Integration adapters (file and API)

**Wave 3** ✅ Complete:
- Plugin architecture with registry
- Orchestration planner with dependency graphs

**Wave 4** ✅ Complete:
- Self-healing locators with fallback chains
- Distribution packaging baseline
- Multi-project organization structure

---

## Reports and Artifacts

### Test Reports
- HTML report: `reports/report.html`
- JUnit XML: `reports/junit.xml`
- Coverage: `reports/coverage-html/index.html`

### Observability
- Summary: `reports/observability/summary.json`
- KPI summary: `reports/observability/kpi_summary.json`
- Engineering report: `reports/observability/engineering_report.json`
- QA report: `reports/observability/qa_functional_report.json`
- Leadership report: `reports/observability/leadership_kpi_report.json`

### Integration Exports
- Jira export: `reports/integrations/jira_export.json`
- Test management: `reports/integrations/test_management_export.json`

### Resilience
- Audit log: `reports/resilience/recovery_audit.jsonl`

### Failure Artifacts
- Screenshots: `reports/screenshots/`
- Videos: `reports/videos/`
- Logs: `reports/framework.log`

---

## Environment Variables

### Framework
```bash
export PYPLAYKIT_TEST_USERNAME="standard_user"
export PYPLAYKIT_TEST_PASSWORD="secret_sauce"
```

### TimelyQuote
```bash
export TIMELYQUOTE_USERNAME="user"
export TIMELYQUOTE_PASSWORD="pass"
export TIMELYQUOTE_ADMIN_USERNAME="admin"
export TIMELYQUOTE_ADMIN_PASSWORD="admin_pass"
```

### Dispatcho
```bash
export DISPATCHO_DISPATCHER_USERNAME="dispatcher"
export DISPATCHO_DISPATCHER_PASSWORD="pass"
export DISPATCHO_DRIVER_USERNAME="driver"
export DISPATCHO_DRIVER_PASSWORD="pass"
export DISPATCHO_ADMIN_USERNAME="admin"
export DISPATCHO_ADMIN_PASSWORD="admin_pass"
```

### Customs Modernization
```bash
export CUSTOMS_USERNAME="customs_user"
export CUSTOMS_PASSWORD="pass"
export CUSTOMS_ADMIN_USERNAME="admin"
export CUSTOMS_ADMIN_PASSWORD="admin_pass"
export CUSTOMS_OFFICER_USERNAME="officer"
export CUSTOMS_OFFICER_PASSWORD="officer_pass"
```

---

## CI/CD Integration

### GitHub Actions Example

```yaml
name: Multi-Project Tests

on: [push, pull_request]

jobs:
  timelyquote-smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          playwright install
      - name: Run TimelyQuote Smoke Tests
        run: pytest tests/projects/timelyquote/ -m smoke -n 4

  dispatcho-smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          playwright install
      - name: Run Dispatcho Smoke Tests
        run: pytest tests/projects/dispatcho/ -m smoke -n 4

  customs-smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          playwright install
      - name: Run Customs Smoke Tests
        run: pytest tests/projects/customs_modernization/ -m smoke -n 4
```

---

## Team Organization

### Recommended Structure (60 QE Engineers)

**TimelyQuote Team (20 QE)**
- UI Team (10): `tests/projects/timelyquote/functional/ui/`
- API Team (6): `tests/projects/timelyquote/functional/api/`
- Integration Team (4): `tests/projects/timelyquote/integration/`

**Dispatcho Team (20 QE)**
- UI Team (10): `tests/projects/dispatcho/functional/ui/`
- API Team (6): `tests/projects/dispatcho/functional/api/`
- Integration Team (4): `tests/projects/dispatcho/integration/`

**Customs Modernization Team (20 QE)**
- UI Team (8): `tests/projects/customs_modernization/functional/ui/`
- API Team (5): `tests/projects/customs_modernization/functional/api/`
- Database/Migration Team (5): `tests/projects/customs_modernization/functional/database/`
- Integration Team (2): `tests/projects/customs_modernization/integration/`

---

## Contributing

See **[CONTRIBUTING.md](CONTRIBUTING.md)** for comprehensive guidelines on:
- Test development patterns
- Page object creation
- Test data management
- Code quality standards
- Common patterns and examples

---

## Troubleshooting

### Tests not discovered?
```bash
pytest tests/projects/<project>/ --collect-only
```

### Import errors?
```bash
# Activate virtual environment
.\.venv\Scripts\Activate.ps1  # Windows
source .venv/bin/activate      # Linux/Mac
```

### Configuration issues?
```bash
pytest --markers | grep -E "timelyquote|dispatcho|customs"
```

---

## Support

- **Framework Issues**: See [Framework Documentation](CLAUDE.md)
- **Project Setup**: See [Implementation Guide](YOUR_PROJECTS_IMPLEMENTATION_GUIDE.md)
- **Quick Help**: See [Cheatsheet](TEST_LOCATION_CHEATSHEET.md)

---

## License

[Your License Here]

---

## Authors

- Framework Team
- QA Engineering Teams

---

**PyPlayKit** - Enterprise Test Automation at Scale 🚀
