pyplaykit 0.1.0__py3-none-any.whl

utils/observability.py

@@ -0,0 +1,164 @@
+"""Observability utilities for execution metrics, failure classification, and KPI summaries."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+class ObservabilityTracker:
+    """Track test execution outcomes and produce observability reports."""
+
+    def __init__(self) -> None:
+        self.results: list[dict[str, Any]] = []
+
+    @staticmethod
+    def classify_failure(message: str) -> str:
+        """Classify failure message into high-level category."""
+        normalized = (message or "").lower()
+        if any(token in normalized for token in ("timeout", "connection", "network", "dns", "refused")):
+            return "infrastructure"
+        if any(token in normalized for token in ("assert", "expected", "mismatch")):
+            return "test_logic"
+        if any(token in normalized for token in ("data", "schema", "json", "csv")):
+            return "test_data"
+        return "application"
+
+    def record_test_result(
+        self,
+        nodeid: str,
+        outcome: str,
+        duration_seconds: float,
+        failure_message: str = "",
+    ) -> None:
+        """Record one test result entry."""
+        entry = {
+            "nodeid": nodeid,
+            "outcome": outcome,
+            "duration_seconds": float(duration_seconds),
+            "failure_type": self.classify_failure(failure_message) if failure_message else None,
+        }
+        self.results.append(entry)
+
+    def summarize(self) -> dict[str, Any]:
+        """Compute execution summary metrics."""
+        total = len(self.results)
+        passed = sum(1 for item in self.results if item["outcome"] == "passed")
+        failed = sum(1 for item in self.results if item["outcome"] == "failed")
+        skipped = sum(1 for item in self.results if item["outcome"] == "skipped")
+        total_duration = sum(float(item["duration_seconds"]) for item in self.results)
+        pass_rate = round((passed / total) * 100, 2) if total else 0.0
+        average_duration = round(total_duration / total, 4) if total else 0.0
+        flaky_tests = self._identify_flaky_tests()
+
+        return {
+            "total": total,
+            "passed": passed,
+            "failed": failed,
+            "skipped": skipped,
+            "pass_rate": pass_rate,
+            "total_duration_seconds": round(total_duration, 4),
+            "average_duration_seconds": average_duration,
+            "flaky_tests": flaky_tests,
+            "flaky_test_count": len(flaky_tests),
+        }
+
+    def build_kpi_summary(self, automation_coverage: float | None = None) -> dict[str, Any]:
+        """Generate KPI-oriented summary for leadership reporting."""
+        summary = self.summarize()
+        denominator = summary["total"] if summary["total"] else 1
+        failure_rate = round((summary["failed"] / denominator) * 100, 2)
+        flaky_rate = round((summary["flaky_test_count"] / denominator) * 100, 2)
+        return {
+            "execution_success_rate": summary["pass_rate"],
+            "execution_failure_rate": failure_rate,
+            "flaky_test_rate": flaky_rate,
+            "mean_test_duration_seconds": summary["average_duration_seconds"],
+            "automation_coverage_percent": automation_coverage,
+        }
+
+    def write_json_report(
+        self,
+        summary_path: str,
+        kpi_path: str,
+        automation_coverage: float | None = None,
+    ) -> tuple[str, str]:
+        """Write summary and KPI reports to JSON files."""
+        summary = self.summarize()
+        kpi_summary = self.build_kpi_summary(automation_coverage=automation_coverage)
+
+        summary_output = Path(summary_path)
+        kpi_output = Path(kpi_path)
+        summary_output.parent.mkdir(parents=True, exist_ok=True)
+        kpi_output.parent.mkdir(parents=True, exist_ok=True)
+
+        summary_output.write_text(json.dumps(summary, indent=2), encoding="utf-8")
+        kpi_output.write_text(json.dumps(kpi_summary, indent=2), encoding="utf-8")
+        return str(summary_output.resolve()), str(kpi_output.resolve())
+
+    def build_persona_reports(self, automation_coverage: float | None = None) -> dict[str, dict[str, Any]]:
+        """Build persona-specific report payloads from shared execution state."""
+        summary = self.summarize()
+        kpi = self.build_kpi_summary(automation_coverage=automation_coverage)
+        failed_tests = [
+            {
+                "nodeid": item["nodeid"],
+                "failure_type": item["failure_type"],
+                "duration_seconds": item["duration_seconds"],
+            }
+            for item in self.results
+            if item["outcome"] == "failed"
+        ]
+
+        return {
+            "engineering": {
+                "report_type": "engineering",
+                "failed_tests": failed_tests,
+                "flaky_tests": summary["flaky_tests"],
+                "total_duration_seconds": summary["total_duration_seconds"],
+            },
+            "qa": {
+                "report_type": "qa_functional",
+                "total": summary["total"],
+                "passed": summary["passed"],
+                "failed": summary["failed"],
+                "skipped": summary["skipped"],
+                "pass_rate": summary["pass_rate"],
+                "flaky_test_count": summary["flaky_test_count"],
+            },
+            "leadership": {
+                "report_type": "leadership_kpi",
+                "execution_success_rate": kpi["execution_success_rate"],
+                "execution_failure_rate": kpi["execution_failure_rate"],
+                "flaky_test_rate": kpi["flaky_test_rate"],
+                "automation_coverage_percent": kpi["automation_coverage_percent"],
+            },
+        }
+
+    def write_persona_reports(
+        self,
+        engineering_path: str,
+        qa_path: str,
+        leadership_path: str,
+        automation_coverage: float | None = None,
+    ) -> dict[str, str]:
+        """Write engineering, QA, and leadership persona reports to JSON files."""
+        reports = self.build_persona_reports(automation_coverage=automation_coverage)
+        targets = {
+            "engineering": Path(engineering_path),
+            "qa": Path(qa_path),
+            "leadership": Path(leadership_path),
+        }
+
+        for key, output_path in targets.items():
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_text(json.dumps(reports[key], indent=2), encoding="utf-8")
+
+        return {name: str(path.resolve()) for name, path in targets.items()}
+
+    def _identify_flaky_tests(self) -> list[str]:
+        outcomes_by_test: dict[str, set[str]] = {}
+        for item in self.results:
+            outcomes_by_test.setdefault(item["nodeid"], set()).add(item["outcome"])
+        return sorted(nodeid for nodeid, outcomes in outcomes_by_test.items() if {"passed", "failed"}.issubset(outcomes))

utils/response_validator.py

@@ -0,0 +1,58 @@
+"""Reusable response validation helpers for API testing."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from utils.api_client import ApiResponse
+
+
+class ResponseValidator:
+    """Collection of assertion-style helpers for API response checks."""
+
+    @staticmethod
+    def assert_status_code(response: ApiResponse, expected_status: int) -> None:
+        """Assert response status code equals expected value."""
+        if response.status_code != expected_status:
+            raise AssertionError(
+                f"Expected status code {expected_status}, found {response.status_code}. Response body: {response.text}"
+            )
+
+    @staticmethod
+    def assert_json_has_keys(response: ApiResponse, required_keys: list[str]) -> None:
+        """Assert response JSON object contains required top-level keys."""
+        payload = response.json()
+        missing = [key for key in required_keys if key not in payload]
+        if missing:
+            raise AssertionError(f"Response JSON is missing required keys: {missing}. Payload: {payload}")
+
+    @staticmethod
+    def assert_json_value(response: ApiResponse, path: str, expected_value: Any) -> None:
+        """Assert JSON value at dot-notation path equals expected value."""
+        actual_value = ResponseValidator._read_path(response.json(), path)
+        if actual_value != expected_value:
+            raise AssertionError(
+                f"Expected JSON path '{path}' to be '{expected_value}', found '{actual_value}'."
+            )
+
+    @staticmethod
+    def assert_response_time_less_than(response: ApiResponse, max_elapsed_ms: float) -> None:
+        """Assert API response duration is within threshold."""
+        if response.elapsed_ms > max_elapsed_ms:
+            raise AssertionError(
+                f"Expected response time <= {max_elapsed_ms}ms, found {response.elapsed_ms:.2f}ms."
+            )
+
+    @staticmethod
+    def _read_path(payload: Any, path: str) -> Any:
+        """Read nested JSON data by dot-notation path, supporting list indexes."""
+        current = payload
+        for token in path.split("."):
+            if isinstance(current, list):
+                index = int(token)
+                current = current[index]
+                continue
+            if not isinstance(current, dict) or token not in current:
+                raise AssertionError(f"JSON path '{path}' not found in payload: {payload}")
+            current = current[token]
+        return current

utils/screenshot_helper.py

@@ -0,0 +1,17 @@
+"""Screenshot helper utilities for failure diagnostics."""
+
+from datetime import UTC, datetime
+from pathlib import Path
+import re
+
+from playwright.sync_api import Page
+
+
+def capture_screenshot(page: Page, test_name: str, output_dir: str = "reports/screenshots") -> str:
+    """Capture and persist screenshot; return absolute file path."""
+    timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S_%f")
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
+    safe_test_name = re.sub(r"[^a-zA-Z0-9_.-]", "_", test_name)
+    file_path = Path(output_dir) / f"{safe_test_name}_{timestamp}.png"
+    page.screenshot(path=str(file_path), full_page=True)
+    return str(file_path.resolve())

utils/tdm.py

@@ -0,0 +1,213 @@
+"""Test Data Management (TDM) utilities for synthetic data, masking, reset, and provisioning."""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Any, Callable
+
+
+_SUPPORTED_SYNTHETIC_TYPES = {"string", "int", "float", "bool", "email"}
+_SUPPORTED_MASKING_STRATEGIES = {"full", "partial"}
+_SUPPORTED_RESET_MODES = {"none", "list", "dict", "callable"}
+
+
+def generate_synthetic_record(
+    schema: dict[str, str],
+    seed: str = "default",
+) -> dict[str, Any]:
+    """Generate deterministic synthetic data based on schema and seed.
+
+    Supported schema value types: string, int, float, bool, email.
+    """
+    record: dict[str, Any] = {}
+    for field, field_type in schema.items():
+        normalized_type = field_type.strip().lower()
+        basis = _stable_number(f"{seed}:{field}")
+
+        if normalized_type == "string":
+            record[field] = f"{field}_{basis % 10000}"
+        elif normalized_type == "int":
+            record[field] = basis % 10000
+        elif normalized_type == "float":
+            record[field] = round((basis % 100000) / 100.0, 2)
+        elif normalized_type == "bool":
+            record[field] = bool(basis % 2)
+        elif normalized_type == "email":
+            record[field] = f"user{basis % 10000}@example.test"
+        else:
+            raise ValueError(f"Unsupported synthetic field type: '{field_type}'")
+
+    return record
+
+
+def mask_value(
+    value: Any,
+    strategy: str = "partial",
+    visible_prefix: int = 2,
+    visible_suffix: int = 2,
+    mask_char: str = "*",
+) -> str:
+    """Mask a value using full or partial strategy."""
+    text = "" if value is None else str(value)
+    normalized_strategy = strategy.strip().lower()
+
+    if normalized_strategy == "full":
+        return mask_char * len(text)
+
+    if normalized_strategy == "partial":
+        if len(text) <= visible_prefix + visible_suffix:
+            return mask_char * len(text)
+        middle_len = len(text) - (visible_prefix + visible_suffix)
+        return f"{text[:visible_prefix]}{mask_char * middle_len}{text[-visible_suffix:]}"
+
+    raise ValueError(f"Unsupported masking strategy: '{strategy}'")
+
+
+def mask_record(
+    record: dict[str, Any],
+    field_rules: dict[str, dict[str, Any]],
+) -> dict[str, Any]:
+    """Mask selected fields in a record according to field-level rules."""
+    masked = dict(record)
+    for field, rules in field_rules.items():
+        if field not in masked:
+            continue
+        masked[field] = mask_value(
+            masked[field],
+            strategy=rules.get("strategy", "partial"),
+            visible_prefix=int(rules.get("visible_prefix", 2)),
+            visible_suffix=int(rules.get("visible_suffix", 2)),
+            mask_char=str(rules.get("mask_char", "*")),
+        )
+    return masked
+
+
+def reset_data_store(store: Any) -> bool:
+    """Reset in-memory data store structures used by tests.
+
+    Supported stores:
+    - list: cleared in place
+    - dict: cleared in place
+    - callable: invoked and expected to return truthy on success
+    """
+    if isinstance(store, list):
+        store.clear()
+        return True
+
+    if isinstance(store, dict):
+        store.clear()
+        return True
+
+    if callable(store):
+        return bool(store())
+
+    raise TypeError(f"Unsupported data store type for reset: {type(store)}")
+
+
+def provision_environment_data(
+    environment: str,
+    provisioners: dict[str, Callable[[], dict[str, Any]]],
+    default_provisioner: Callable[[], dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    """Provision environment-specific data using configured provisioners."""
+    key = environment.strip().lower()
+    if key in provisioners:
+        return provisioners[key]()
+
+    if default_provisioner is not None:
+        return default_provisioner()
+
+    supported = ", ".join(sorted(provisioners.keys()))
+    raise KeyError(f"No provisioner found for environment '{environment}'. Supported: {supported}")
+
+
+def _stable_number(text: str) -> int:
+    digest = hashlib.sha256(text.encode("utf-8")).hexdigest()
+    return int(digest[:12], 16)
+
+
+def parse_tdm_policy(raw_policy: dict[str, Any] | None, environment: str | None = None) -> dict[str, Any]:
+    """Parse and normalize a TDM policy loaded from configuration."""
+    source = dict(raw_policy or {})
+    parsed = {
+        "enabled": bool(source.get("enabled", False)),
+        "synthetic_schema": dict(source.get("synthetic_schema", {})),
+        "masking_rules": dict(source.get("masking_rules", {})),
+        "reset_mode": str(source.get("reset_mode", "none")).strip().lower(),
+        "provisioning_by_env": {
+            str(env_key).strip().lower(): str(profile).strip()
+            for env_key, profile in dict(source.get("provisioning_by_env", {})).items()
+        },
+        "default_provisioner": source.get("default_provisioner"),
+    }
+
+    env_key = (environment or "").strip().lower()
+    active_profile = parsed["provisioning_by_env"].get(env_key)
+    if active_profile is None and parsed["default_provisioner"] is not None:
+        active_profile = str(parsed["default_provisioner"]).strip()
+    parsed["active_provisioner"] = active_profile
+
+    return validate_tdm_policy(parsed)
+
+
+def validate_tdm_policy(policy: dict[str, Any]) -> dict[str, Any]:
+    """Validate normalized TDM policy and raise clear errors for invalid values."""
+    schema = policy.get("synthetic_schema", {})
+    if not isinstance(schema, dict):
+        raise ValueError("tdm.synthetic_schema must be a dictionary")
+    for field, field_type in schema.items():
+        normalized_type = str(field_type).strip().lower()
+        if normalized_type not in _SUPPORTED_SYNTHETIC_TYPES:
+            raise ValueError(
+                f"Unsupported synthetic field type '{field_type}' for field '{field}'. "
+                f"Supported: {sorted(_SUPPORTED_SYNTHETIC_TYPES)}"
+            )
+
+    masking_rules = policy.get("masking_rules", {})
+    if not isinstance(masking_rules, dict):
+        raise ValueError("tdm.masking_rules must be a dictionary")
+    for field, rules in masking_rules.items():
+        if not isinstance(rules, dict):
+            raise ValueError(f"tdm.masking_rules['{field}'] must be a dictionary")
+
+        strategy = str(rules.get("strategy", "partial")).strip().lower()
+        if strategy not in _SUPPORTED_MASKING_STRATEGIES:
+            raise ValueError(
+                f"Unsupported masking strategy '{strategy}' for field '{field}'. "
+                f"Supported: {sorted(_SUPPORTED_MASKING_STRATEGIES)}"
+            )
+
+        for key in ("visible_prefix", "visible_suffix"):
+            if key in rules and int(rules[key]) < 0:
+                raise ValueError(f"tdm.masking_rules['{field}'].{key} must be >= 0")
+
+    reset_mode = str(policy.get("reset_mode", "none")).strip().lower()
+    if reset_mode not in _SUPPORTED_RESET_MODES:
+        raise ValueError(
+            f"Unsupported reset_mode '{reset_mode}'. "
+            f"Supported: {sorted(_SUPPORTED_RESET_MODES)}"
+        )
+
+    provisioning_by_env = policy.get("provisioning_by_env", {})
+    if not isinstance(provisioning_by_env, dict):
+        raise ValueError("tdm.provisioning_by_env must be a dictionary")
+    for env_key, profile in provisioning_by_env.items():
+        if not str(profile).strip():
+            raise ValueError(f"tdm.provisioning_by_env['{env_key}'] must not be empty")
+
+    default_provisioner = policy.get("default_provisioner")
+    if default_provisioner is not None and not str(default_provisioner).strip():
+        raise ValueError("tdm.default_provisioner must not be empty when provided")
+
+    policy["enabled"] = bool(policy.get("enabled", False))
+    policy["synthetic_schema"] = {
+        str(field): str(field_type).strip().lower() for field, field_type in schema.items()
+    }
+    policy["masking_rules"] = masking_rules
+    policy["reset_mode"] = reset_mode
+    policy["provisioning_by_env"] = {
+        str(env_key).strip().lower(): str(profile).strip() for env_key, profile in provisioning_by_env.items()
+    }
+    policy["default_provisioner"] = None if default_provisioner is None else str(default_provisioner).strip()
+    policy["active_provisioner"] = policy.get("active_provisioner")
+    return policy

utils/yaml_config_reader.py

@@ -0,0 +1,104 @@
+"""
+Module for reading and managing framework configuration.
+This includes loading global settings from config.yaml and environment-specific
+settings from environments.yaml.
+"""
+
+import yaml
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+class ConfigReader:
+    """
+    Handles reading configuration from config.yaml and environments.yaml.
+    Provides methods to access framework settings and environment-specific data.
+    """
+    _instance = None
+    _config: Dict[str, Any] = {}
+    _environments: Dict[str, Any] = {}
+    _current_env: str = "qa" # Default environment
+
+    def __new__(cls, config_file: str = "config.yaml", env_file: str = "environments.yaml"):
+        if cls._instance is None:
+            cls._instance = super(ConfigReader, cls).__new__(cls)
+            cls._instance._load_configs(config_file, env_file)
+        return cls._instance
+
+    def _load_configs(self, config_file: str, env_file: str):
+        """Loads configuration from specified YAML files."""
+        config_path = Path(os.path.join(os.path.dirname(__file__), "..", "config", config_file))
+        env_path = Path(os.path.join(os.path.dirname(__file__), "..", "config", env_file))
+
+        if not config_path.is_file():
+            raise FileNotFoundError(f"Config file not found: {config_path}")
+        if not env_path.is_file():
+            raise FileNotFoundError(f"Environments file not found: {env_path}")
+
+        with config_path.open("r", encoding="utf-8") as f:
+            self._config = yaml.safe_load(f)
+
+        with env_path.open("r", encoding="utf-8") as f:
+            self._environments = yaml.safe_load(f)
+
+        # Set initial environment from config.yaml, can be overridden by pytest --pyplaykit-env
+        self._current_env = self._config.get("execution", {}).get("environment", "qa")
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """
+        Retrieves a configuration value from config.yaml.
+        Supports dot notation for nested keys (e.g., "execution.browser").
+        """
+        keys = key.split('.')
+        val = self._config
+        for k in keys:
+            if isinstance(val, dict):
+                val = val.get(k, default)
+            else:
+                return default
+        return val
+
+    def get_environment_settings(self, env: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Retrieves all settings for a specific environment.
+        If env is None, uses the current environment.
+        """
+        target_env = env if env else self.get_env()
+        return self._environments.get("environments", {}).get(target_env, {})
+
+    def get_base_url(self, env: Optional[str] = None) -> str:
+        """Retrieves the base URL for a specific environment."""
+        settings = self.get_environment_settings(env)
+        return settings.get("base_url", "")
+
+    def get_env(self) -> str:
+        """Returns the current active environment."""
+        return self._current_env
+
+    def set_env(self, env: str):
+        """Sets the current active environment (e.g., from a pytest fixture)."""
+        self._current_env = env
+
+    def get_browser(self) -> str:
+        """Retrieves the browser type from config.yaml."""
+        return self.get("execution.browser", "chromium")
+
+    def get_headless_mode(self) -> bool:
+        """Retrieves the headless mode setting from config.yaml."""
+        return self.get("execution.headless", True)
+
+    def get_timeout(self) -> int:
+        """Retrieves the default timeout from config.yaml."""
+        return self.get("execution.timeout_ms", 30000)
+
+    def get_navigation_timeout(self) -> int:
+        """Retrieves the navigation timeout from config.yaml."""
+        return self.get("execution.navigation_timeout_ms", 45000)
+
+    def get_screenshot_on_failure(self) -> bool:
+        """Retrieves the screenshot on failure setting from config.yaml."""
+        return self.get("execution.screenshot_on_failure", True)
+
+    def get_video_on_failure(self) -> bool:
+        """Retrieves the video on failure setting from config.yaml."""
+        return self.get("execution.video_on_failure", True)