pyplaykit 1.8.0__tar.gz → 1.8.2__tar.gz

{pyplaykit-1.8.0 → pyplaykit-1.8.2}/MANIFEST.in

@@ -1,4 +1,6 @@
 include README.md
+include PIP_INSTALL_GUIDE.md
+include LICENSE
 recursive-include config *.yaml
 recursive-include test_data *.json
 recursive-include pyplaykit *.py

pyplaykit-1.8.2/PIP_INSTALL_GUIDE.md

@@ -0,0 +1,493 @@
+# PyPlayKit Installation Guide
+
+Welcome to **PyPlayKit** - Enterprise Python + Playwright Test Automation Framework!
+
+## 🚀 Quick Installation
+
+```bash
+# Install PyPlayKit
+pip install pyplaykit
+
+# Install Playwright browsers
+playwright install
+```
+
+## 📋 System Requirements
+
+- **Python:** 3.11 or higher
+- **Operating System:** Windows, macOS, Linux
+- **RAM:** 4GB minimum (8GB recommended)
+- **Disk Space:** 2GB for browsers
+
+## 🔧 Complete Setup
+
+### 1. Create Virtual Environment
+
+```bash
+# Windows PowerShell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+
+# Linux/macOS
+python -m venv .venv
+source .venv/bin/activate
+```
+
+### 2. Install PyPlayKit
+
+```bash
+pip install pyplaykit
+```
+
+### 3. Install Playwright Browsers
+
+```bash
+# Install all browsers (Chromium, Firefox, WebKit)
+playwright install
+
+# Or install specific browser
+playwright install chromium
+playwright install firefox
+playwright install webkit
+```
+
+### 4. Verify Installation
+
+```bash
+python -c "import pyplaykit; print(f'PyPlayKit {pyplaykit.__version__} installed successfully!')"
+```
+
+## 🗄️ Database Driver Installation (Optional)
+
+PyPlayKit supports multiple enterprise databases. **Database drivers are optional** - install only what you need:
+
+### Quick Install with Optional Dependencies
+
+```bash
+# Install PyPlayKit with specific database support
+pip install pyplaykit[postgresql]      # PostgreSQL
+pip install pyplaykit[sqlserver]       # SQL Server
+pip install pyplaykit[oracle]          # Oracle
+pip install pyplaykit[db2]             # IBM DB2
+pip install pyplaykit[informix]        # IBM Informix
+pip install pyplaykit[mysql]           # MySQL
+pip install pyplaykit[snowflake]       # Snowflake
+
+# Install multiple databases
+pip install pyplaykit[postgresql,sqlserver,oracle]
+
+# Install ALL database drivers at once
+pip install pyplaykit[all-databases]
+
+# Install with data comparison tools (Excel, CSV)
+pip install pyplaykit[data-comparison]
+
+# Install everything
+pip install pyplaykit[all-databases,data-comparison]
+```
+
+### Manual Driver Installation
+
+If you prefer to install drivers manually:
+
+#### PostgreSQL
+```bash
+pip install psycopg2-binary
+```
+
+#### SQL Server
+```bash
+pip install pyodbc
+
+# Also install ODBC Driver:
+# Windows: Download from Microsoft
+# Linux: sudo apt-get install msodbcsql17
+# macOS: brew install msodbcsql17
+```
+
+#### Oracle
+```bash
+pip install oracledb
+# No additional Oracle Client required (uses thin mode)
+```
+
+#### DB2
+```bash
+pip install ibm_db ibm_db_dbi
+# May require IBM Data Server Driver
+```
+
+#### Informix
+```bash
+pip install IfxPy IfxPyDbi
+# Requires IBM Informix Client SDK
+```
+
+#### MySQL
+```bash
+pip install mysql-connector-python
+```
+
+#### Snowflake
+```bash
+pip install snowflake-connector-python
+```
+
+## 🎯 Quick Start Example
+
+### 1. Create Test Directory Structure
+
+```bash
+mkdir my-test-project
+cd my-test-project
+mkdir -p tests/functional/ui
+mkdir -p pages
+mkdir -p config
+```
+
+### 2. Create Configuration
+
+**config/config.yaml:**
+```yaml
+browser:
+  type: chromium
+  headless: true
+  viewport:
+    width: 1920
+    height: 1080
+
+timeouts:
+  page_load: 30
+  element_wait: 10
+
+logging:
+  level: INFO
+```
+
+**config/environments.yaml:**
+```yaml
+environments:
+  qa:
+    base_url: https://qa.example.com
+    api_base_url: https://api-qa.example.com
+  
+  prod:
+    base_url: https://example.com
+    api_base_url: https://api.example.com
+```
+
+### 3. Create Your First Page Object
+
+**pages/login_page.py:**
+```python
+from pyplaykit import BasePage
+
+class LoginPage(BasePage):
+    # Locators
+    USERNAME_INPUT = "#username"
+    PASSWORD_INPUT = "#password"
+    LOGIN_BUTTON = "button[type='submit']"
+    
+    def login(self, username: str, password: str):
+        """Perform login action."""
+        self.fill(self.USERNAME_INPUT, username)
+        self.fill(self.PASSWORD_INPUT, password)
+        self.click(self.LOGIN_BUTTON)
+    
+    def is_login_successful(self) -> bool:
+        """Check if login was successful."""
+        return self.page.url.endswith("/dashboard")
+```
+
+### 4. Create Your First Test
+
+**tests/functional/ui/test_login.py:**
+```python
+import pytest
+from pages.login_page import LoginPage
+
+@pytest.mark.smoke
+def test_successful_login(page, base_url, runtime_options):
+    """Test successful user login."""
+    # Navigate to login page
+    page.goto(base_url)
+    
+    # Create page object
+    login_page = LoginPage(page, runtime_options["resilience_policy"])
+    
+    # Perform login
+    login_page.login("test_user", "test_password")
+    
+    # Verify success
+    assert login_page.is_login_successful()
+```
+
+### 5. Run Your Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run specific marker
+pytest -m smoke
+
+# Run with specific browser
+pytest --pyplaykit-browser firefox
+
+# Run in headed mode
+pytest --pyplaykit-headed
+
+# Run with environment
+pytest --pyplaykit-env qa
+```
+
+## 📚 Essential Commands
+
+### Test Execution
+```bash
+# Basic execution
+pytest
+
+# With environment
+pytest --pyplaykit-env qa
+
+# With browser override
+pytest --pyplaykit-browser chromium
+pytest --pyplaykit-browser firefox
+pytest --pyplaykit-browser webkit
+
+# Headed mode (see browser)
+pytest --pyplaykit-headed
+
+# Parallel execution
+pytest -n 4
+
+# Specific markers
+pytest -m smoke
+pytest -m regression
+pytest -m "smoke and login"
+
+# With readiness checks
+pytest --pyplaykit-readiness-check
+```
+
+### Coverage and Reports
+```bash
+# Run tests with coverage
+pytest --cov=. --cov-report=html
+
+# View coverage report
+# Open reports/coverage-html/index.html in browser
+
+# Generate HTML report
+pytest --html=reports/report.html
+```
+
+### Database Testing
+```bash
+# Example test with database
+pytest tests/functional/database/
+```
+
+## 🌐 Environment Variables
+
+Create a `.env` file in your project root:
+
+```bash
+# Database credentials
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=testdb
+DB_USER=testuser
+DB_PASSWORD=testpass
+
+# Test credentials
+PYPLAYKIT_TEST_USERNAME=test_user
+PYPLAYKIT_TEST_PASSWORD=test_password
+
+# API credentials
+API_KEY=your-api-key-here
+API_SECRET=your-api-secret-here
+```
+
+## 📖 Available Fixtures
+
+PyPlayKit provides these pytest fixtures out of the box:
+
+| Fixture | Scope | Description |
+|---------|-------|-------------|
+| `page` | function | Playwright page object |
+| `context` | function | Browser context |
+| `browser` | function | Browser instance |
+| `base_url` | session | Base URL from config |
+| `runtime_options` | session | Resolved configuration |
+| `config_reader` | session | Config reader utility |
+| `logger` | session | Framework logger |
+| `db_client` | function | Database client (PostgreSQL) |
+| `api_client` | function | HTTP API client |
+
+## 🎨 Test Markers
+
+Available test markers (define in `pytest.ini`):
+
+```python
+@pytest.mark.smoke        # Smoke tests
+@pytest.mark.sanity       # Sanity tests
+@pytest.mark.regression   # Regression tests
+@pytest.mark.flaky        # Flaky tests with retries
+@pytest.mark.login        # Login-specific tests
+@pytest.mark.negative     # Negative test cases
+```
+
+## 🔍 Troubleshooting
+
+### Issue: "playwright not found"
+```bash
+# Solution: Install Playwright browsers
+playwright install
+```
+
+### Issue: "Module 'pyplaykit' has no attribute 'X'"
+```bash
+# Solution: Verify installation
+pip show pyplaykit
+pip install --upgrade pyplaykit
+```
+
+### Issue: Database connection fails
+```bash
+# Solution: Check credentials and install driver
+pip install psycopg2-binary  # PostgreSQL
+pip install pyodbc           # SQL Server
+pip install oracledb         # Oracle
+```
+
+### Issue: Tests fail with timeout
+```bash
+# Solution: Increase timeout in config.yaml
+timeouts:
+  page_load: 60
+  element_wait: 30
+```
+
+### Issue: Browser doesn't open in headed mode
+```bash
+# Solution: Verify browser installation
+playwright install chromium --force
+```
+
+## 📂 Project Structure
+
+Recommended project structure:
+
+```
+my-test-project/
+├── .env                          # Environment variables (gitignore this!)
+├── pytest.ini                    # Pytest configuration
+├── config/
+│   ├── config.yaml              # Framework configuration
+│   └── environments.yaml        # Environment-specific settings
+├── pages/                       # Page object models
+│   ├── __init__.py
+│   ├── login_page.py
+│   └── dashboard_page.py
+├── tests/
+│   ├── functional/
+│   │   ├── ui/                  # UI tests
+│   │   ├── api/                 # API tests
+│   │   └── database/            # Database tests
+│   └── integration/             # Integration tests
+├── test_data/                   # Test data files
+│   └── users.json
+└── reports/                     # Test reports (auto-generated)
+    ├── screenshots/
+    ├── videos/
+    └── report.html
+```
+
+## 🛠️ Advanced Features
+
+### Cross-Database Testing
+```python
+from pyplaykit import DbClientFactory
+
+# Create SQL Server client
+sqlserver = DbClientFactory.create(
+    db_type="sqlserver",
+    host="server.com",
+    database="mydb",
+    user="user",
+    password="pass"
+)
+
+# Create Oracle client
+oracle = DbClientFactory.create(
+    db_type="oracle",
+    host="oracle.com",
+    database="PROD",
+    user="user",
+    password="pass"
+)
+
+# Compare data
+from pyplaykit import compare_query_results
+comparison = compare_query_results(
+    source_client=sqlserver,
+    target_client=oracle,
+    source_query="SELECT * FROM customers",
+    target_query="SELECT * FROM customers",
+    key_columns=["id"]
+)
+```
+
+### API Testing
+```python
+from pyplaykit import ApiClient
+
+api = ApiClient(base_url="https://api.example.com", timeout_seconds=10)
+response = api.get("/users/123")
+
+assert response.status_code == 200
+assert response.json()["name"] == "John Doe"
+```
+
+### Data Validation
+```python
+from pyplaykit import validate_required_fields, validate_datetime_format
+
+# Validate data structure
+validate_required_fields(
+    record={"id": 1, "name": "Alice"},
+    required=["id", "name", "email"]  # Will fail - missing email
+)
+
+# Validate datetime format
+validate_datetime_format(
+    value="2024-01-15 10:30:00",
+    expected_format="%Y-%m-%d %H:%M:%S"
+)
+```
+
+## 📞 Support and Resources
+
+- **Documentation:** [https://github.com/ShanKonduru/pyplaykit](https://github.com/ShanKonduru/pyplaykit)
+- **Issues:** [https://github.com/ShanKonduru/pyplaykit/issues](https://github.com/ShanKonduru/pyplaykit/issues)
+- **PyPI:** [https://pypi.org/project/pyplaykit/](https://pypi.org/project/pyplaykit/)
+
+## 🎓 Next Steps
+
+1. ✅ Read `QUICK_START_QE.md` for QE engineer onboarding
+2. ✅ Check `CONTRIBUTING.md` for contribution guidelines
+3. ✅ Review `docs/DATABASE_SUPPORT.md` for database testing
+4. ✅ Explore `examples/` directory for code samples
+5. ✅ Join our community and contribute!
+
+## 📄 License
+
+PyPlayKit is released under the MIT License.
+
+---
+
+**Happy Testing with PyPlayKit!** 🎉
+
+For detailed documentation, visit: https://github.com/ShanKonduru/pyplaykit

{pyplaykit-1.8.0/pyplaykit.egg-info → pyplaykit-1.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyplaykit
-Version: 1.8.0
+Version: 1.8.2
 Summary: Enterprise Python + Playwright automation framework
 Author-email: Shan Konduru <shankonduru@gmail.com>
 License: MIT
@@ -24,18 +24,74 @@ 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: pytest-html==4.2.0
-Requires-Dist: allure-pytest==2.16.0
 Requires-Dist: PyYAML==6.0.2
 Requires-Dist: python-dotenv>=1.0.0
-Requires-Dist: httpx>=0.27.0
-Requires-Dist: jmespath>=1.0.0
-Requires-Dist: xlrd>=2.0.1
-Requires-Dist: zeep>=4.2.1
-Requires-Dist: gql[httpx]>=3.5.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
 

{pyplaykit-1.8.0 → pyplaykit-1.8.2}/pyplaykit/cli.py

@@ -2,6 +2,7 @@
 
 Usage:
     pyplaykit init [PROJECT_DIR]
+    pyplaykit docs
 """
 
 from __future__ import annotations
@@ -78,12 +79,50 @@ def _init(project_dir: Path) -> None:
     print("  3. Run: pytest --pyplaykit-env qa")
 
 
+def _docs() -> None:
+    """Show location of PyPlayKit documentation."""
+    package_dir = Path(__file__).parent.parent
+
+    print()
+    print("=" * 70)
+    print("📚 PyPlayKit Documentation")
+    print("=" * 70)
+    print()
+
+    # Check for PIP_INSTALL_GUIDE.md
+    guide_path = package_dir / "PIP_INSTALL_GUIDE.md"
+    if guide_path.exists():
+        print(f"✅ Installation Guide: {guide_path}")
+        print(f"   View: cat {guide_path}")
+    else:
+        print(f"⚠️  Installation Guide not found at: {guide_path}")
+
+    print()
+
+    # Check for README.md
+    readme_path = package_dir / "README.md"
+    if readme_path.exists():
+        print(f"✅ README: {readme_path}")
+        print(f"   View: cat {readme_path}")
+    else:
+        print(f"⚠️  README not found at: {readme_path}")
+
+    print()
+    print("📖 Online Documentation:")
+    print("   https://github.com/ShanKonduru/pyplaykit")
+    print()
+    print("=" * 70)
+    print()
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         prog="pyplaykit",
         description="PyPlayKit project scaffolding CLI",
     )
     sub = parser.add_subparsers(dest="command")
+
+    # init command
     init_p = sub.add_parser("init", help="Scaffold a new pyplaykit project")
     init_p.add_argument(
         "project_dir",
@@ -92,12 +131,19 @@ def main(argv: list[str] | None = None) -> int:
         help="Directory to scaffold into (default: current directory)",
     )
 
+    # docs command
+    sub.add_parser("docs", help="Show location of installed documentation")
+
     args = parser.parse_args(argv)
 
     if args.command == "init":
         _init(Path(args.project_dir).resolve())
         return 0
 
+    if args.command == "docs":
+        _docs()
+        return 0
+
     parser.print_help()
     return 1