pyplaykit 0.1.0__py3-none-any.whl

core/base_page.py

@@ -0,0 +1,94 @@
+"""Base page object with reusable browser interactions and waits."""
+
+from datetime import datetime, timezone
+from typing import Any
+
+from playwright.sync_api import Locator, Page, expect
+
+from resilience.locator_recovery import resolve_visible_locator, write_resilience_audit_event
+
+
+class BasePage:
+    """Base class for all page objects."""
+
+    def __init__(self, page: Page, resilience_policy: dict[str, Any] | None = None) -> None:
+        self.page = page
+        self.resilience_policy = resilience_policy or {}
+
+    def navigate(self, url: str) -> None:
+        """Navigate to a URL and wait for DOM readiness."""
+        self.page.goto(url, wait_until="domcontentloaded")
+
+    def wait_for_url_contains(self, url_part: str) -> None:
+        """Wait until current page URL contains expected partial value."""
+        expect(self.page).to_have_url(lambda current_url: url_part in current_url)
+
+    def wait_for_visible(
+        self,
+        selector: str,
+        fallback_selectors: list[str] | None = None,
+        dom_retry_count: int | None = None,
+    ) -> Locator:
+        """Wait for selector visibility with optional fallback chain and retry-based DOM re-evaluation."""
+        policy = self.resilience_policy
+        policy_enabled = bool(policy.get("enabled", False))
+
+        if dom_retry_count is None:
+            dom_retry_count = int(policy.get("dom_retry_count", 0)) if policy_enabled else 0
+        if fallback_selectors is None:
+            fallback_selectors = list(policy.get("fallback_selectors", [])) if policy_enabled else []
+
+        if not fallback_selectors and int(dom_retry_count) <= 0:
+            locator = self.page.locator(selector)
+            expect(locator).to_be_visible()
+            return locator
+
+        locator, resolved_selector, resolved_attempt, recovery_event = resolve_visible_locator(
+            locator_getter=self.page.locator,
+            visible_assertion=lambda candidate: expect(candidate).to_be_visible(),
+            primary_selector=selector,
+            fallback_selectors=fallback_selectors,
+            dom_retry_count=int(dom_retry_count),
+            confidence_decay_per_hop=float(policy.get("confidence_decay_per_hop", 0.15)),
+            confidence_decay_per_retry=float(policy.get("confidence_decay_per_retry", 0.1)),
+        )
+
+        if recovery_event.get("used_fallback") or recovery_event.get("used_retry"):
+            audit_event = {
+                "event_type": "locator_recovery",
+                "timestamp_utc": datetime.now(timezone.utc).isoformat(),
+                "primary_selector": selector,
+                "resolved_selector": resolved_selector,
+                "resolved_attempt": resolved_attempt,
+                **recovery_event,
+            }
+            self.resilience_policy["last_recovery_event"] = audit_event
+            if bool(policy.get("audit_enabled", False)) and policy.get("audit_log_path"):
+                write_resilience_audit_event(str(policy.get("audit_log_path")), audit_event)
+
+        return locator
+
+    def click(self, selector: str) -> None:
+        """Click an element after waiting for visibility."""
+        self.wait_for_visible(selector).click()
+
+    def fill(self, selector: str, value: str) -> None:
+        """Fill field after waiting for visibility."""
+        self.wait_for_visible(selector).fill(value)
+
+    def text(self, selector: str) -> str:
+        """Return inner text after waiting for visibility."""
+        return self.wait_for_visible(selector).inner_text().strip()
+
+    def is_visible(self, selector: str, timeout: float = 5000) -> bool:
+        """Return visibility state for selector, auto-waiting for it to be visible."""
+        locator = self.page.locator(selector)
+        try:
+            expect(locator).to_be_visible(timeout=timeout)
+            return True
+        except AssertionError:
+            return False
+
+    def get_title(self) -> str:
+        """Return current page title."""
+        return self.page.title()

core/base_test.py

@@ -0,0 +1,27 @@
+"""Base test abstractions for common runtime metadata and assertions."""
+
+from dataclasses import dataclass
+
+from core.base_page import BasePage
+
+
+@dataclass
+class BaseTestContext:
+    """Container for common test runtime metadata."""
+
+    environment: str
+    browser: str
+    headless: bool
+
+
+class BaseTest:
+    """Base test utility methods shared across test modules."""
+
+    @staticmethod
+    def assert_page_title_contains(page_object: BasePage, expected_text: str) -> None:
+        """Assert that page title contains expected text."""
+        actual_title = page_object.get_title()
+        if expected_text not in actual_title:
+            raise AssertionError(
+                f"Expected title to contain '{expected_text}', actual title: '{actual_title}'."
+            )

core/browser_factory.py

@@ -0,0 +1,30 @@
+"""Browser factory for cross-browser launch control."""
+
+from playwright.sync_api import Browser, BrowserType, Playwright
+
+
+class BrowserFactory:
+    """Create Playwright browser instances based on configuration."""
+
+    _SUPPORTED_BROWSERS = {
+        "chromium": "chromium",
+        "firefox": "firefox",
+        "webkit": "webkit",
+    }
+
+    @classmethod
+    def create_browser(
+        cls,
+        playwright: Playwright,
+        browser_name: str,
+        headless: bool = True,
+        slow_mo_ms: int = 0,
+    ) -> Browser:
+        """Launch and return a browser instance for the given browser name."""
+        normalized_name = browser_name.strip().lower()
+        if normalized_name not in cls._SUPPORTED_BROWSERS:
+            supported = ", ".join(sorted(cls._SUPPORTED_BROWSERS.keys()))
+            raise ValueError(f"Unsupported browser '{browser_name}'. Supported: {supported}")
+
+        browser_type: BrowserType = getattr(playwright, cls._SUPPORTED_BROWSERS[normalized_name])
+        return browser_type.launch(headless=headless, slow_mo=slow_mo_ms)

core/playwright_manager.py

@@ -0,0 +1,40 @@
+"""Playwright lifecycle manager for centralized runtime control."""
+
+from contextlib import AbstractContextManager
+from typing import Optional
+
+from playwright.sync_api import Playwright, sync_playwright
+
+
+class PlaywrightManager(AbstractContextManager):
+    """Manage Playwright process startup and shutdown for the test session."""
+
+    def __init__(self) -> None:
+        self._playwright: Optional[Playwright] = None
+
+    @property
+    def instance(self) -> Playwright:
+        """Return active Playwright instance."""
+        if self._playwright is None:
+            raise RuntimeError("Playwright is not started. Call start() first.")
+        return self._playwright
+
+    def start(self) -> Playwright:
+        """Start Playwright if not active and return the current instance."""
+        if self._playwright is not None:
+            return self._playwright
+        self._playwright = sync_playwright().start()
+        return self._playwright
+
+    def stop(self) -> None:
+        """Stop Playwright if active."""
+        if self._playwright is not None:
+            self._playwright.stop()
+            self._playwright = None
+
+    def __enter__(self) -> "PlaywrightManager":
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.stop()

dist_pkg/__init__.py

@@ -0,0 +1,5 @@
+"""Internal distribution packaging helpers."""
+
+from .distribution import build_distribution_plan, normalize_distribution_name
+
+__all__ = ["normalize_distribution_name", "build_distribution_plan"]

dist_pkg/distribution.py

@@ -0,0 +1,51 @@
+"""Helpers for packaging the framework for internal distribution."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Mapping
+
+
+def normalize_distribution_name(framework_name: str) -> str:
+    """Normalize display name into a package-safe distribution name."""
+    normalized = re.sub(r"[^a-z0-9]+", "-", framework_name.strip().lower())
+    normalized = re.sub(r"-+", "-", normalized).strip("-")
+    if not normalized:
+        raise ValueError("framework_name must contain at least one alphanumeric character")
+    return normalized
+
+
+def build_distribution_plan(
+    framework_config: Mapping[str, Any],
+    *,
+    version: str,
+    output_dir: str = "dist",
+) -> dict[str, Any]:
+    """Build an internal distribution plan for wheel/sdist artifacts."""
+    if not version or not version.strip():
+        raise ValueError("version must be a non-empty string")
+
+    framework = framework_config.get("framework", {}) if isinstance(framework_config, Mapping) else {}
+    framework_name = str(framework.get("name", "PyPlayKit"))
+    distribution_name = normalize_distribution_name(framework_name)
+
+    command = [
+        "python",
+        "-m",
+        "build",
+        "--sdist",
+        "--wheel",
+        "--outdir",
+        output_dir,
+    ]
+    artifact_patterns = [
+        f"{output_dir}/{distribution_name}-{version}.tar.gz",
+        f"{output_dir}/{distribution_name}-{version}-*.whl",
+    ]
+
+    return {
+        "distribution_name": distribution_name,
+        "version": version,
+        "build_command": command,
+        "artifact_patterns": artifact_patterns,
+    }

integrations/__init__.py

@@ -0,0 +1,21 @@
+"""Integration adapters for external enterprise systems."""
+
+from .adapters import (
+    ApiJiraAdapter,
+    ApiTestManagementAdapter,
+    build_api_adapters,
+    FileJiraAdapter,
+    FileTestManagementAdapter,
+    IntegrationAdapter,
+    build_file_adapters,
+)
+
+__all__ = [
+    "IntegrationAdapter",
+    "FileJiraAdapter",
+    "FileTestManagementAdapter",
+    "ApiJiraAdapter",
+    "ApiTestManagementAdapter",
+    "build_file_adapters",
+    "build_api_adapters",
+]

integrations/adapters.py

@@ -0,0 +1,155 @@
+"""Integration adapter interfaces and file-based adapter implementations."""
+
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Mapping
+
+from utils.api_client import ApiClient
+
+
+class IntegrationAdapter(ABC):
+    """Contract for exporting execution results to enterprise systems."""
+
+    system_name: str
+
+    @abstractmethod
+    def export(self, payload: Mapping[str, Any]) -> str:
+        """Export execution payload and return written artifact path."""
+
+
+class _FileIntegrationAdapter(IntegrationAdapter):
+    """Common file export behavior for integration adapters."""
+
+    def __init__(self, output_path: str, run_metadata: Mapping[str, Any] | None = None) -> None:
+        if not output_path or not output_path.strip():
+            raise ValueError("output_path must be a non-empty string")
+        self.output_path = output_path
+        self.run_metadata = dict(run_metadata or {})
+
+    def export(self, payload: Mapping[str, Any]) -> str:
+        if not isinstance(payload, Mapping):
+            raise TypeError("payload must be a mapping")
+
+        output = Path(self.output_path)
+        output.parent.mkdir(parents=True, exist_ok=True)
+        envelope = {
+            "target_system": self.system_name,
+            "generated_at_utc": datetime.now(timezone.utc).isoformat(),
+            "run_metadata": self.run_metadata,
+            "payload": dict(payload),
+        }
+        output.write_text(json.dumps(envelope, indent=2), encoding="utf-8")
+        return str(output.resolve())
+
+
+class FileJiraAdapter(_FileIntegrationAdapter):
+    """File-based export adapter for Jira ingestion pipelines."""
+
+    system_name = "jira"
+
+
+class FileTestManagementAdapter(_FileIntegrationAdapter):
+    """File-based export adapter for test management ingestion pipelines."""
+
+    system_name = "test_management"
+
+
+class _ApiIntegrationAdapter(IntegrationAdapter):
+    """Common API export behavior for integration adapters."""
+
+    def __init__(
+        self,
+        api_client: ApiClient,
+        endpoint: str,
+        run_metadata: Mapping[str, Any] | None = None,
+    ) -> None:
+        if not endpoint or not endpoint.strip():
+            raise ValueError("endpoint must be a non-empty string")
+        self.api_client = api_client
+        self.endpoint = endpoint
+        self.run_metadata = dict(run_metadata or {})
+
+    def export(self, payload: Mapping[str, Any]) -> str:
+        if not isinstance(payload, Mapping):
+            raise TypeError("payload must be a mapping")
+
+        envelope = {
+            "target_system": self.system_name,
+            "generated_at_utc": datetime.now(timezone.utc).isoformat(),
+            "run_metadata": self.run_metadata,
+            "payload": dict(payload),
+        }
+        response = self.api_client.post(self.endpoint, json_body=envelope)
+        if response.status_code >= 400:
+            raise RuntimeError(
+                f"{self.system_name} integration export failed with status {response.status_code}"
+            )
+        return f"api:{self.system_name}:{response.status_code}"
+
+
+class ApiJiraAdapter(_ApiIntegrationAdapter):
+    """API-based export adapter for Jira integrations."""
+
+    system_name = "jira"
+
+
+class ApiTestManagementAdapter(_ApiIntegrationAdapter):
+    """API-based export adapter for test management integrations."""
+
+    system_name = "test_management"
+
+
+def build_file_adapters(config: Mapping[str, Any], run_metadata: Mapping[str, Any] | None = None) -> dict[str, IntegrationAdapter]:
+    """Build file-based integration adapters from config."""
+    if not isinstance(config, Mapping):
+        return {}
+
+    if not bool(config.get("enabled", False)):
+        return {}
+
+    jira_path = str(config.get("jira_export_path", "")).strip()
+    tms_path = str(config.get("test_management_export_path", "")).strip()
+
+    if not jira_path:
+        raise ValueError("integrations.jira_export_path is required when integrations.enabled=true")
+    if not tms_path:
+        raise ValueError("integrations.test_management_export_path is required when integrations.enabled=true")
+
+    return {
+        "jira": FileJiraAdapter(jira_path, run_metadata=run_metadata),
+        "test_management": FileTestManagementAdapter(tms_path, run_metadata=run_metadata),
+    }
+
+
+def build_api_adapters(
+    config: Mapping[str, Any],
+    api_client: ApiClient,
+    run_metadata: Mapping[str, Any] | None = None,
+) -> dict[str, IntegrationAdapter]:
+    """Build API-based integration adapters from config."""
+    if not isinstance(config, Mapping):
+        return {}
+
+    if not bool(config.get("api_enabled", False)):
+        return {}
+
+    jira_endpoint = str(config.get("jira_api_endpoint", "")).strip()
+    tms_endpoint = str(config.get("test_management_api_endpoint", "")).strip()
+
+    if not jira_endpoint:
+        raise ValueError("integrations.jira_api_endpoint is required when integrations.api_enabled=true")
+    if not tms_endpoint:
+        raise ValueError("integrations.test_management_api_endpoint is required when integrations.api_enabled=true")
+
+    return {
+        "jira_api": ApiJiraAdapter(api_client=api_client, endpoint=jira_endpoint, run_metadata=run_metadata),
+        "test_management_api": ApiTestManagementAdapter(
+            api_client=api_client,
+            endpoint=tms_endpoint,
+            run_metadata=run_metadata,
+        ),
+    }

orchestration/__init__.py

@@ -0,0 +1,5 @@
+"""Orchestration exports for dependency-aware execution planning."""
+
+from .planner import build_orchestration_plan
+
+__all__ = ["build_orchestration_plan"]

orchestration/planner.py

@@ -0,0 +1,137 @@
+"""Suite orchestration planner with dependency-aware execution ordering."""
+
+from __future__ import annotations
+
+from collections import deque
+from typing import Any, Mapping
+
+
+def build_orchestration_plan(config: Mapping[str, Any]) -> dict[str, Any]:
+    """Build orchestration plan from config with dependency and pipeline validation."""
+    if not isinstance(config, Mapping) or not bool(config.get("enabled", False)):
+        return {
+            "enabled": False,
+            "dependency_graph": {},
+            "suite_order": [],
+            "pipelines": [],
+        }
+
+    suites = config.get("suites", [])
+    if not isinstance(suites, list):
+        raise ValueError("orchestration.suites must be a list")
+
+    dependency_graph: dict[str, list[str]] = {}
+    for suite in suites:
+        if not isinstance(suite, Mapping):
+            raise ValueError("Each orchestration suite entry must be a mapping")
+        suite_id = str(suite.get("id", "")).strip()
+        depends_on = suite.get("depends_on", [])
+        if not suite_id:
+            raise ValueError("Each orchestration suite must define a non-empty id")
+        if not isinstance(depends_on, list):
+            raise ValueError(f"orchestration suite '{suite_id}' depends_on must be a list")
+        if suite_id in dependency_graph:
+            raise ValueError(f"Duplicate orchestration suite id: {suite_id}")
+        dependency_graph[suite_id] = [str(dep).strip() for dep in depends_on]
+
+    for suite_id, dependencies in dependency_graph.items():
+        for dependency in dependencies:
+            if dependency not in dependency_graph:
+                raise ValueError(f"Suite '{suite_id}' depends on unknown suite '{dependency}'")
+
+    suite_order = _resolve_suite_order(dependency_graph)
+    pipelines = _normalize_pipelines(config.get("pipelines", []), dependency_graph)
+
+    return {
+        "enabled": True,
+        "dependency_graph": dependency_graph,
+        "suite_order": suite_order,
+        "pipelines": pipelines,
+    }
+
+
+def _resolve_suite_order(dependency_graph: Mapping[str, list[str]]) -> list[str]:
+    dependents_by_suite: dict[str, list[str]] = {suite_id: [] for suite_id in dependency_graph}
+    remaining_dependencies: dict[str, int] = {
+        suite_id: len(dependencies)
+        for suite_id, dependencies in dependency_graph.items()
+    }
+    for suite_id, dependencies in dependency_graph.items():
+        for dependency in dependencies:
+            dependents_by_suite[dependency].append(suite_id)
+
+    ready = deque([suite_id for suite_id in dependency_graph if remaining_dependencies[suite_id] == 0])
+    ordered: list[str] = []
+
+    while ready:
+        suite_id = ready.popleft()
+        ordered.append(suite_id)
+        for dependent in dependents_by_suite[suite_id]:
+            remaining_dependencies[dependent] -= 1
+            if remaining_dependencies[dependent] == 0:
+                ready.append(dependent)
+
+    if len(ordered) != len(dependency_graph):
+        raise ValueError("Orchestration dependency graph contains a cycle")
+    return ordered
+
+
+def _normalize_pipelines(
+    pipelines_config: Any,
+    dependency_graph: Mapping[str, list[str]],
+) -> list[dict[str, Any]]:
+    if not pipelines_config:
+        return []
+    if not isinstance(pipelines_config, list):
+        raise ValueError("orchestration.pipelines must be a list")
+
+    normalized: list[dict[str, Any]] = []
+    known_suites = set(dependency_graph.keys())
+
+    for pipeline in pipelines_config:
+        if not isinstance(pipeline, Mapping):
+            raise ValueError("Each orchestration pipeline entry must be a mapping")
+        pipeline_name = str(pipeline.get("name", "")).strip()
+        stages = pipeline.get("stages", [])
+        if not pipeline_name:
+            raise ValueError("Each orchestration pipeline must define a non-empty name")
+        if not isinstance(stages, list):
+            raise ValueError(f"orchestration pipeline '{pipeline_name}' stages must be a list")
+
+        stage_index_by_suite: dict[str, int] = {}
+        normalized_stages: list[dict[str, Any]] = []
+        for index, stage in enumerate(stages):
+            if not isinstance(stage, Mapping):
+                raise ValueError(f"Pipeline '{pipeline_name}' stage entry must be a mapping")
+            stage_name = str(stage.get("name", "")).strip()
+            suites = stage.get("suites", [])
+            if not stage_name:
+                raise ValueError(f"Pipeline '{pipeline_name}' stage must define a non-empty name")
+            if not isinstance(suites, list):
+                raise ValueError(f"Pipeline '{pipeline_name}' stage '{stage_name}' suites must be a list")
+
+            normalized_suites: list[str] = []
+            for suite_name in suites:
+                suite_id = str(suite_name).strip()
+                if suite_id not in known_suites:
+                    raise ValueError(f"Pipeline '{pipeline_name}' references unknown suite '{suite_id}'")
+                if suite_id in stage_index_by_suite:
+                    raise ValueError(f"Pipeline '{pipeline_name}' includes suite '{suite_id}' multiple times")
+                stage_index_by_suite[suite_id] = index
+                normalized_suites.append(suite_id)
+            normalized_stages.append({"name": stage_name, "suites": normalized_suites})
+
+        for suite_id, dependencies in dependency_graph.items():
+            if suite_id not in stage_index_by_suite:
+                continue
+            for dependency in dependencies:
+                if dependency not in stage_index_by_suite:
+                    continue
+                if stage_index_by_suite[dependency] > stage_index_by_suite[suite_id]:
+                    raise ValueError(
+                        f"Pipeline '{pipeline_name}' places dependency '{dependency}' after '{suite_id}'"
+                    )
+
+        normalized.append({"name": pipeline_name, "stages": normalized_stages})
+
+    return normalized

pages/dashboard_page.py

@@ -0,0 +1,24 @@
+"""Dashboard page object for SauceDemo inventory page."""
+
+from core.base_page import BasePage
+
+
+class DashboardPage(BasePage):
+    """Page object representing dashboard page operations."""
+
+    PAGE_TITLE = "[data-test='title']"
+    INVENTORY_ITEMS = ".inventory_item"
+    CART_LINK = "[data-test='shopping-cart-link']"
+
+    def is_loaded(self) -> bool:
+        """Return true when dashboard page key elements are visible."""
+        return self.is_visible(self.PAGE_TITLE) and self.is_visible(self.CART_LINK)
+
+    def get_inventory_count(self) -> int:
+        """Return number of inventory cards displayed on dashboard."""
+        self.wait_for_visible(self.PAGE_TITLE)
+        return self.page.locator(self.INVENTORY_ITEMS).count()
+
+    def open_cart(self) -> None:
+        """Open cart page from dashboard."""
+        self.click(self.CART_LINK)

pages/login_page.py

@@ -0,0 +1,31 @@
+"""Login page object for SauceDemo sample application."""
+
+from core.base_page import BasePage
+
+
+class LoginPage(BasePage):
+    """Page object representing login page operations."""
+
+    USERNAME_INPUT = "#user-name"
+    PASSWORD_INPUT = "#password"
+    LOGIN_BUTTON = "#login-button"
+    ERROR_BANNER = "[data-test='error']"
+
+    def open(self, base_url: str) -> None:
+        """Navigate to login page."""
+        self.navigate(base_url)
+        self.wait_for_visible(self.USERNAME_INPUT)
+
+    def login(self, username: str, password: str) -> None:
+        """Perform login action with provided credentials."""
+        self.fill(self.USERNAME_INPUT, username)
+        self.fill(self.PASSWORD_INPUT, password)
+        self.click(self.LOGIN_BUTTON)
+
+    def get_error_message(self) -> str:
+        """Return login failure message."""
+        return self.text(self.ERROR_BANNER)
+
+    def is_loaded(self) -> bool:
+        """Return true when login page fields are visible."""
+        return self.is_visible(self.USERNAME_INPUT) and self.is_visible(self.LOGIN_BUTTON)