ankole-framework 1.0.0__py3-none-any.whl

ankole/__init__.py

@@ -0,0 +1,88 @@
+"""
+Ankole Framework - Multi-driver E2E test framework.
+
+Supports Playwright (web), pywinauto (desktop), httpx (API), and subprocess (CLI)
+with full observability: Grafana, Prometheus, Loki, Allure, Kiwi TCMS.
+
+Install:
+    pip install ankole-framework[all]
+
+Usage:
+    from ankole import WebDriver, APIDriver, UIDriver, ConsoleRunner, Evidence
+"""
+
+import importlib
+
+__version__ = "2.0.0"
+
+# Eagerly import cross-platform modules only
+from ankole.driver.evidence import Evidence, StepTracker, tracked_step
+from ankole.driver.console_runner import ConsoleRunner, CommandResult, resolve_platform_config
+from ankole.driver.log_collector import LogCollector, LogMonitor
+from ankole.driver.kiwi_tcms import KiwiReporter
+from ankole.driver.grafana_push import MetricsPusher
+from ankole.driver.health_check import HealthChecker, HealthCheckResult, HealthCheckReport
+from ankole.driver.smoke_gate import SmokeGate
+
+# Lazy import for platform-specific / optional-dep modules
+_LAZY_IMPORTS = {
+    # Desktop (pywinauto)
+    "UIDriver": "ankole.driver.ui_driver",
+    "WindowMonitor": "ankole.driver.window_monitor",
+    "UIAppManager": "ankole.driver.appmanager",
+    # Web (Playwright)
+    "WebDriver": "ankole.driver.web_driver",
+    # API (httpx)
+    "APIDriver": "ankole.driver.api_driver",
+    # Infrastructure
+    "RemoteTrigger": "ankole.driver.remote_trigger",
+    "RemoteResult": "ankole.driver.remote_trigger",
+    "RemoteAgentPool": "ankole.driver.remote_trigger",
+    "LokiLogCollector": "ankole.driver.loki_collector",
+    "DriverProtocol": "ankole.driver.base",
+    "WebDriverProtocol": "ankole.driver.base",
+    "APIDriverProtocol": "ankole.driver.base",
+    "CLIDriver": "ankole.driver.cli_driver",
+    "ConfigValidator": "ankole.driver.config_validator",
+    "ConfigValidationError": "ankole.driver.config_validator",
+    "BasePage": "ankole.pages.base_page",
+}
+
+
+def __getattr__(name):
+    if name in _LAZY_IMPORTS:
+        module = importlib.import_module(_LAZY_IMPORTS[name])
+        return getattr(module, name)
+    raise AttributeError(f"module 'ankole' has no attribute {name!r}")
+
+
+__all__ = [
+    # Core driver infrastructure
+    "UIDriver",
+    "WebDriver",
+    "APIDriver",
+    "DriverProtocol",
+    "WebDriverProtocol",
+    "APIDriverProtocol",
+    "ConsoleRunner",
+    "CommandResult",
+    "resolve_platform_config",
+    "Evidence",
+    "StepTracker",
+    "tracked_step",
+    "LogCollector",
+    "LogMonitor",
+    "LokiLogCollector",
+    "KiwiReporter",
+    "MetricsPusher",
+    "HealthChecker",
+    "HealthCheckResult",
+    "HealthCheckReport",
+    "SmokeGate",
+    "WindowMonitor",
+    "RemoteTrigger",
+    "RemoteResult",
+    "RemoteAgentPool",
+    # Generic Page Object base
+    "BasePage",
+]

ankole/driver/__init__.py

@@ -0,0 +1,42 @@
+"""Driver modules — infrastructure, evidence, integrations.
+
+Re-exports key classes for convenience::
+
+    from ankole.driver import UIDriver, Evidence, tracked_step
+"""
+
+from ankole.driver.appmanager import UIAppManager
+from ankole.driver.cli_driver import CLIDriver
+from ankole.driver.config_validator import ConfigValidationError, ConfigValidator
+from ankole.driver.console_runner import CommandResult, ConsoleRunner, resolve_platform_config
+from ankole.driver.evidence import Evidence, StepTracker, tracked_step
+from ankole.driver.grafana_push import MetricsPusher
+from ankole.driver.health_check import HealthChecker, HealthCheckReport, HealthCheckResult
+from ankole.driver.kiwi_tcms import KiwiReporter
+from ankole.driver.log_collector import LogCollector, LogMonitor
+from ankole.driver.smoke_gate import SmokeGate
+from ankole.driver.zap_scanner import ZAPAlert, ZAPScanner, ZAPScanReport
+
+__all__ = [
+    "Evidence",
+    "StepTracker",
+    "tracked_step",
+    "ConsoleRunner",
+    "CommandResult",
+    "resolve_platform_config",
+    "LogCollector",
+    "LogMonitor",
+    "KiwiReporter",
+    "MetricsPusher",
+    "HealthChecker",
+    "HealthCheckResult",
+    "HealthCheckReport",
+    "SmokeGate",
+    "UIAppManager",
+    "CLIDriver",
+    "ConfigValidator",
+    "ConfigValidationError",
+    "ZAPScanner",
+    "ZAPAlert",
+    "ZAPScanReport",
+]

ankole/driver/a11y.py

@@ -0,0 +1,228 @@
+"""Accessibility testing via axe-core injection.
+
+Injects axe-core into Playwright pages and runs WCAG compliance scans::
+
+    scanner = A11yScanner()
+    report = scanner.scan(web_driver, tags=["wcag2a", "wcag2aa"])
+    report.assert_no_violations(impact=["critical", "serious"])
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+AXE_CDN_URL = "https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.9.1/axe.min.js"
+
+
+@dataclass
+class A11yViolation:
+    """Single accessibility violation."""
+
+    rule_id: str
+    impact: str  # "minor", "moderate", "serious", "critical"
+    description: str
+    help_url: str
+    nodes: list[dict[str, Any]] = field(default_factory=list)
+
+    @property
+    def target_selectors(self) -> list[str]:
+        """CSS selectors of affected elements."""
+        targets = []
+        for node in self.nodes:
+            for target in node.get("target", []):
+                if isinstance(target, list):
+                    targets.extend(target)
+                else:
+                    targets.append(target)
+        return targets
+
+
+@dataclass
+class A11yReport:
+    """Accessibility scan results."""
+
+    url: str
+    violations: list[A11yViolation] = field(default_factory=list)
+    passes: int = 0
+    inapplicable: int = 0
+    incomplete: int = 0
+
+    @property
+    def violation_count(self) -> int:
+        """Total number of violations."""
+        return len(self.violations)
+
+    def violations_by_impact(self, impact: list[str] | None = None) -> list[A11yViolation]:
+        """Filter violations by impact level."""
+        if not impact:
+            return self.violations
+        return [v for v in self.violations if v.impact in impact]
+
+    def assert_no_violations(
+        self, impact: list[str] | None = None, msg: str | None = None,
+    ) -> "A11yReport":
+        """Assert no violations at specified impact levels.
+
+        Args:
+            impact: Impact levels to check (e.g., ["critical", "serious"]).
+                   If None, checks all violations.
+            msg: Custom error message.
+
+        Returns:
+            self for chaining.
+        """
+        filtered = self.violations_by_impact(impact)
+        if filtered:
+            details = "\n".join(
+                f"  - [{v.impact.upper()}] {v.rule_id}: {v.description} "
+                f"({len(v.nodes)} elements)"
+                for v in filtered
+            )
+            error = msg or (
+                f"Found {len(filtered)} accessibility violation(s) "
+                f"at {self.url}:\n{details}"
+            )
+            raise AssertionError(error)
+        return self
+
+    def attach_to_allure(self) -> "A11yReport":
+        """Attach report to Allure as JSON."""
+        try:
+            import allure
+
+            report_data = {
+                "url": self.url,
+                "violations": [
+                    {
+                        "rule_id": v.rule_id,
+                        "impact": v.impact,
+                        "description": v.description,
+                        "help_url": v.help_url,
+                        "elements": v.target_selectors,
+                    }
+                    for v in self.violations
+                ],
+                "summary": {
+                    "violations": self.violation_count,
+                    "passes": self.passes,
+                    "inapplicable": self.inapplicable,
+                    "incomplete": self.incomplete,
+                },
+            }
+            allure.attach(
+                json.dumps(report_data, indent=2),
+                name="Accessibility Report",
+                attachment_type=allure.attachment_type.JSON,
+            )
+        except ImportError:
+            pass
+        return self
+
+    def summary(self) -> str:
+        """Human-readable summary."""
+        return (
+            f"A11y Report for {self.url}: "
+            f"{self.violation_count} violations, {self.passes} passes, "
+            f"{self.inapplicable} inapplicable, {self.incomplete} incomplete"
+        )
+
+
+class A11yScanner:
+    """Accessibility scanner using axe-core via Playwright page.evaluate().
+
+    Injects axe-core from CDN into the page and runs WCAG compliance scans.
+    """
+
+    def __init__(
+        self,
+        axe_cdn_url: str = AXE_CDN_URL,
+        default_tags: list[str] | None = None,
+        disabled_rules: list[str] | None = None,
+    ):
+        self.axe_cdn_url = axe_cdn_url
+        self.default_tags = default_tags or ["wcag2a", "wcag2aa"]
+        self.disabled_rules = disabled_rules or []
+
+    def _inject_axe(self, page: Any) -> None:
+        """Inject axe-core library into the page."""
+        is_loaded = page.evaluate("typeof window.axe !== 'undefined'")
+        if not is_loaded:
+            page.evaluate(
+                """async (url) => {
+                    const script = document.createElement('script');
+                    script.src = url;
+                    document.head.appendChild(script);
+                    await new Promise((resolve, reject) => {
+                        script.onload = resolve;
+                        script.onerror = reject;
+                    });
+                }""",
+                self.axe_cdn_url,
+            )
+            logger.debug("axe-core injected into page")
+
+    def scan(
+        self,
+        driver: Any,
+        selector: str | None = None,
+        tags: list[str] | None = None,
+        disabled_rules: list[str] | None = None,
+    ) -> A11yReport:
+        """Run accessibility scan on the current page.
+
+        Args:
+            driver: WebDriver instance with a `page` property.
+            selector: CSS selector to scope the scan (default: entire page).
+            tags: WCAG tags to test (e.g., ["wcag2a", "wcag2aa"]).
+            disabled_rules: Rule IDs to skip.
+
+        Returns:
+            A11yReport with scan results.
+        """
+        page = driver.page
+        self._inject_axe(page)
+
+        effective_tags = tags or self.default_tags
+        effective_disabled = disabled_rules or self.disabled_rules
+
+        # Build axe.run options
+        options = {"runOnly": {"type": "tag", "values": effective_tags}}
+        if effective_disabled:
+            options["rules"] = {rule: {"enabled": False} for rule in effective_disabled}
+
+        context = f"'{selector}'" if selector else "document"
+
+        results = page.evaluate(
+            f"""async (options) => {{
+                const results = await window.axe.run({context}, options);
+                return results;
+            }}""",
+            options,
+        )
+
+        # Parse violations
+        violations = []
+        for v in results.get("violations", []):
+            violations.append(A11yViolation(
+                rule_id=v["id"],
+                impact=v.get("impact", "unknown"),
+                description=v.get("description", ""),
+                help_url=v.get("helpUrl", ""),
+                nodes=v.get("nodes", []),
+            ))
+
+        report = A11yReport(
+            url=page.url,
+            violations=violations,
+            passes=len(results.get("passes", [])),
+            inapplicable=len(results.get("inapplicable", [])),
+            incomplete=len(results.get("incomplete", [])),
+        )
+
+        logger.info(report.summary())
+        return report

ankole/driver/api_driver.py

@@ -0,0 +1,288 @@
+"""HTTP API driver using httpx.
+
+Wraps httpx with JWT token management, response assertions, and retry logic::
+
+    from ankole.driver.api_driver import APIDriver
+
+    with APIDriver(base_url="http://localhost:8000") as api:
+        api.login("admin", "admin123")
+        resp = api.get("/api/members")
+        resp.assert_status(200)
+        members = resp.json()
+"""
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class APIResponse:
+    """Wrapper around httpx.Response with assertion helpers."""
+
+    status_code: int
+    headers: dict
+    _json: Any = None
+    _text: str = ""
+
+    def json(self) -> Any:
+        """Return parsed JSON body."""
+        return self._json
+
+    @property
+    def text(self) -> str:
+        """Return response body as text."""
+        return self._text
+
+    def assert_status(self, expected: int) -> "APIResponse":
+        """Assert response status code."""
+        assert self.status_code == expected, (
+            f"Expected status {expected}, got {self.status_code}: {self._text[:200]}"
+        )
+        return self
+
+    def assert_json_key(self, key: str, value: Any = None) -> "APIResponse":
+        """Assert JSON response contains a key, optionally with specific value."""
+        data = self.json()
+        assert key in data, f"Key '{key}' not found in response: {data}"
+        if value is not None:
+            assert data[key] == value, (
+                f"Expected {key}={value!r}, got {data[key]!r}"
+            )
+        return self
+
+    def assert_json_key_absent(self, key: str) -> "APIResponse":
+        """Assert JSON response does NOT contain a key."""
+        data = self.json()
+        assert key not in data, f"Key '{key}' should not be in response but found: {key}={data[key]!r}"
+        return self
+
+    def assert_json_list_length(self, min_length: int = 0) -> "APIResponse":
+        """Assert JSON response is a list with minimum length."""
+        data = self.json()
+        assert isinstance(data, list), f"Expected list, got {type(data).__name__}"
+        assert len(data) >= min_length, (
+            f"Expected at least {min_length} items, got {len(data)}"
+        )
+        return self
+
+    def assert_schema(self, model_class: Any) -> "APIResponse":
+        """Validate response JSON against a Pydantic v2 model.
+
+        Args:
+            model_class: Pydantic BaseModel subclass.
+
+        Returns:
+            self for chaining.
+
+        Raises:
+            AssertionError: If validation fails.
+        """
+        data = self.json()
+        try:
+            model_class.model_validate(data)
+        except Exception as e:
+            raise AssertionError(
+                f"Schema validation failed for {model_class.__name__}: {e}"
+            ) from e
+        return self
+
+    def assert_json_schema(self, schema: dict) -> "APIResponse":
+        """Validate response JSON against a JSON Schema dict.
+
+        Args:
+            schema: JSON Schema dictionary.
+
+        Returns:
+            self for chaining.
+        """
+        import jsonschema
+
+        data = self.json()
+        try:
+            jsonschema.validate(instance=data, schema=schema)
+        except jsonschema.ValidationError as e:
+            raise AssertionError(
+                f"JSON Schema validation failed: {e.message}"
+            ) from e
+        return self
+
+    def assert_matches_openapi(self, spec_path: str, operation_id: str) -> "APIResponse":
+        """Validate response against an OpenAPI specification.
+
+        Loads the OpenAPI spec, finds the operation by ID, extracts the
+        response schema for the current status code, and validates.
+
+        Args:
+            spec_path: Path to OpenAPI spec file (YAML or JSON).
+            operation_id: Operation ID to match.
+
+        Returns:
+            self for chaining.
+        """
+        import json as json_mod
+        import yaml
+        import jsonschema
+
+        with open(spec_path, "r") as f:
+            if spec_path.endswith(".json"):
+                spec = json_mod.load(f)
+            else:
+                spec = yaml.safe_load(f)
+
+        # Find operation by operationId
+        response_schema = None
+        for path_obj in spec.get("paths", {}).values():
+            for method_obj in path_obj.values():
+                if isinstance(method_obj, dict) and method_obj.get("operationId") == operation_id:
+                    status_str = str(self.status_code)
+                    resp_def = method_obj.get("responses", {}).get(status_str, {})
+                    content = resp_def.get("content", {})
+                    json_content = content.get("application/json", {})
+                    response_schema = json_content.get("schema")
+                    break
+            if response_schema:
+                break
+
+        if response_schema is None:
+            raise AssertionError(
+                f"No schema found for operation '{operation_id}' "
+                f"with status {self.status_code} in {spec_path}"
+            )
+
+        try:
+            jsonschema.validate(instance=self.json(), schema=response_schema)
+        except jsonschema.ValidationError as e:
+            raise AssertionError(
+                f"OpenAPI validation failed for '{operation_id}': {e.message}"
+            ) from e
+        return self
+
+
+class APIDriver:
+    """HTTP client wrapper with JWT token management.
+
+    Supports context manager protocol for automatic cleanup.
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8000",
+        timeout: float = 30.0,
+        token_endpoint: str = "/api/auth/login",
+        token_field: str = "access_token",
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.token_endpoint = token_endpoint
+        self.token_field = token_field
+
+        self._client = None
+        self._token: str | None = None
+
+    def start(self) -> "APIDriver":
+        """Create httpx client."""
+        import httpx
+
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=self.timeout,
+        )
+        logger.info(f"APIDriver started: {self.base_url}")
+        return self
+
+    def close(self) -> None:
+        """Close httpx client."""
+        if self._client:
+            self._client.close()
+        self._token = None
+        logger.info("APIDriver closed")
+
+    def __enter__(self) -> "APIDriver":
+        return self.start()
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+    # -- Auth -----------------------------------------------------------------
+
+    def login(self, username: str, password: str) -> APIResponse:
+        """Authenticate and store JWT token."""
+        resp = self.post(
+            self.token_endpoint,
+            json={"username": username, "password": password},
+        )
+        if resp.status_code == 200:
+            data = resp.json()
+            self._token = data.get(self.token_field)
+            logger.info(f"Logged in as: {username}")
+        return resp
+
+    def logout(self) -> None:
+        """Clear stored token."""
+        self._token = None
+        logger.info("Logged out (token cleared)")
+
+    @property
+    def is_authenticated(self) -> bool:
+        """Check if a token is stored."""
+        return self._token is not None
+
+    # -- HTTP methods ---------------------------------------------------------
+
+    def _headers(self) -> dict:
+        """Build request headers with auth token if available."""
+        headers = {"Content-Type": "application/json"}
+        if self._token:
+            headers["Authorization"] = f"Bearer {self._token}"
+        return headers
+
+    def _wrap_response(self, resp) -> APIResponse:
+        """Convert httpx.Response to APIResponse."""
+        try:
+            json_data = resp.json()
+        except Exception:
+            json_data = None
+        return APIResponse(
+            status_code=resp.status_code,
+            headers=dict(resp.headers),
+            _json=json_data,
+            _text=resp.text,
+        )
+
+    def get(self, path: str, **kwargs) -> APIResponse:
+        """Send GET request."""
+        kwargs.setdefault("headers", self._headers())
+        resp = self._client.get(path, **kwargs)
+        logger.debug(f"GET {path} -> {resp.status_code}")
+        return self._wrap_response(resp)
+
+    def post(self, path: str, **kwargs) -> APIResponse:
+        """Send POST request."""
+        kwargs.setdefault("headers", self._headers())
+        resp = self._client.post(path, **kwargs)
+        logger.debug(f"POST {path} -> {resp.status_code}")
+        return self._wrap_response(resp)
+
+    def put(self, path: str, **kwargs) -> APIResponse:
+        """Send PUT request."""
+        kwargs.setdefault("headers", self._headers())
+        resp = self._client.put(path, **kwargs)
+        logger.debug(f"PUT {path} -> {resp.status_code}")
+        return self._wrap_response(resp)
+
+    def patch(self, path: str, **kwargs) -> APIResponse:
+        """Send PATCH request."""
+        kwargs.setdefault("headers", self._headers())
+        resp = self._client.patch(path, **kwargs)
+        logger.debug(f"PATCH {path} -> {resp.status_code}")
+        return self._wrap_response(resp)
+
+    def delete(self, path: str, **kwargs) -> APIResponse:
+        """Send DELETE request."""
+        kwargs.setdefault("headers", self._headers())
+        resp = self._client.delete(path, **kwargs)
+        logger.debug(f"DELETE {path} -> {resp.status_code}")
+        return self._wrap_response(resp)