robotframework-okw-env 0.1.0__py3-none-any.whl

okw_env/__init__.py

@@ -0,0 +1,12 @@
+from .provider_base import OkwEnvProviderBase
+from .provider_registry import get_provider, discover_providers
+from .environment_manager import EnvironmentManager
+from .library import OkwEnvLibrary
+
+__all__ = [
+    "OkwEnvProviderBase",
+    "EnvironmentManager",
+    "OkwEnvLibrary",
+    "get_provider",
+    "discover_providers",
+]

okw_env/environment_manager.py

@@ -0,0 +1,133 @@
+"""Manages registered environment components and delegates to providers."""
+
+import time
+
+from okw_env.provider_base import OkwEnvProviderBase
+from okw_env.provider_registry import get_provider
+
+
+class EnvironmentManager:
+    """Tracks all registered components and orchestrates provider calls.
+
+    Each component can use a different provider (determined by the
+    ``provider`` key in the component YAML). Providers are resolved
+    automatically via the entry point registry.
+    """
+
+    def __init__(self):
+        self._components: dict[str, dict] = {}
+        self._component_ids: dict[str, str] = {}
+        self._providers: dict[str, OkwEnvProviderBase] = {}
+        self._default_provider: OkwEnvProviderBase | None = None
+
+    def set_provider(self, provider: OkwEnvProviderBase) -> None:
+        """Set a default provider (used when YAML has no 'provider' key)."""
+        self._default_provider = provider
+
+    def register(self, name: str, component: dict, **overrides) -> None:
+        """Register a component for later provisioning."""
+        merged = {**component, **overrides}
+        self._components[name] = merged
+
+    def build_and_run(self) -> None:
+        """Create and start all registered components."""
+        for name, component in self._components.items():
+            provider = self._resolve_provider(name, component)
+            component_id = provider.create(component)
+            self._component_ids[name] = component_id
+            self._providers[name] = provider
+            provider.start(component_id)
+            runtime_info = provider.get_runtime_info(component_id)
+            if runtime_info:
+                component.update(runtime_info)
+
+    def wait_for_ready(self, name: str, timeout: float = 30.0, interval: float = 1.0) -> None:
+        """Poll until the component is ready or timeout is reached."""
+        provider = self._require_provider(name)
+        component_id = self._require_component_id(name)
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if provider.is_ready(component_id):
+                return
+            time.sleep(interval)
+        raise TimeoutError(f"Component '{name}' not ready after {timeout}s.")
+
+    def get_logs(self, name: str) -> str:
+        """Retrieve logs from a component."""
+        provider = self._require_provider(name)
+        component_id = self._require_component_id(name)
+        return provider.get_logs(component_id)
+
+    def snapshot(self, name: str) -> str:
+        """Snapshot a component's current state."""
+        provider = self._require_provider(name)
+        component_id = self._require_component_id(name)
+        return provider.snapshot(component_id)
+
+    def snapshot_all(self) -> dict[str, str]:
+        """Snapshot all running components. Returns {name: snapshot_id}."""
+        results = {}
+        for name, component_id in self._component_ids.items():
+            provider = self._require_provider(name)
+            results[name] = provider.snapshot(component_id)
+        return results
+
+    def stop_all(self) -> None:
+        """Stop and destroy all components."""
+        for name, component_id in list(self._component_ids.items()):
+            provider = self._providers[name]
+            provider.stop(component_id)
+            provider.destroy(component_id)
+        self._component_ids.clear()
+        self._components.clear()
+        self._providers.clear()
+
+    def get_component_config(self, name: str) -> dict:
+        """Return the registered component definition."""
+        if name not in self._components:
+            raise KeyError(f"Component '{name}' not registered. Registered: {list(self._components.keys())}")
+        return self._components[name]
+
+    def get_mem_entries(self) -> dict[str, str]:
+        """Flatten all component configs into dot-notation for $MEM{} expansion.
+
+        Returns a dict like:
+            {"PostgresDB.image": "postgres", "PostgresDB.env.POSTGRES_DB": "shop", ...}
+        """
+        entries = {}
+        for name, config in self._components.items():
+            if name in self._component_ids:
+                entries[f"{name}.ID"] = self._component_ids[name]
+            self._flatten(name, config, entries)
+        return entries
+
+    @staticmethod
+    def _flatten(prefix: str, data: dict, result: dict) -> None:
+        for key, value in data.items():
+            full_key = f"{prefix}.{key}"
+            if isinstance(value, dict):
+                EnvironmentManager._flatten(full_key, value, result)
+            else:
+                result[full_key] = str(value)
+
+    def _resolve_provider(self, name: str, component: dict) -> OkwEnvProviderBase:
+        """Resolve provider from component YAML or fall back to default."""
+        provider_name = component.get("provider")
+        if provider_name:
+            return get_provider(provider_name, component=component)
+        if self._default_provider:
+            return self._default_provider
+        raise RuntimeError(
+            f"Component '{name}' has no 'provider' key and no default provider is set. "
+            f"Add 'provider: docker' to the YAML or call set_provider()."
+        )
+
+    def _require_provider(self, name: str) -> OkwEnvProviderBase:
+        if name not in self._providers:
+            raise KeyError(f"No provider for '{name}'. Was build_and_run() called?")
+        return self._providers[name]
+
+    def _require_component_id(self, name: str) -> str:
+        if name not in self._component_ids:
+            raise KeyError(f"Component '{name}' not found. Registered: {list(self._component_ids.keys())}")
+        return self._component_ids[name]

okw_env/library.py

@@ -0,0 +1,175 @@
+"""OKW Environment Library – Robot Framework keywords for environment provisioning."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from robot.api import logger
+from robot.api.deco import keyword, library
+
+from .environment_manager import EnvironmentManager
+from .yaml_loader import load_component
+
+
+@library(scope="GLOBAL")
+class OkwEnvLibrary:
+    """Driver-agnostic Robot Framework library for ephemeral test environments.
+
+    Provides keywords to build, run, and tear down isolated environments
+    per test case. Provider plugins (Docker, Proxmox, ...) implement the
+    actual infrastructure.
+
+    = Keywords =
+
+    | ``ENV_Start``          | Register a component                    |
+    | ``ENV_BuildAndRun``    | Create and start all components         |
+    | ``ENV_WaitForReady``   | Wait until a component passes its health check |
+    | ``ENV_Stop``           | Stop and destroy all components         |
+    | ``ENV_CreateImage``    | Snapshot current state for reuse        |
+    | ``ENV_StartFromImage`` | Start from snapshot or run fallback     |
+    | ``ENV_SnapshotOnFail`` | Freeze state on test failure            |
+    """
+
+    ROBOT_LIBRARY_SCOPE = "GLOBAL"
+
+    def __init__(self, components_dir: str | None = None):
+        self._manager = EnvironmentManager()
+        self._components_dir = Path(components_dir) if components_dir else None
+
+    @keyword("ENV_Start")
+    def env_start(self, name: str, **overrides):
+        """Register an environment component for provisioning.
+
+        Loads the component definition from YAML and applies any overrides.
+
+        Example:
+        | ENV_Start | PostgresDB | version=17 |
+        """
+        component = self._load_component(name)
+        self._manager.register(name, component, **overrides)
+        logger.info(f"ENV_Start: Registered '{name}'")
+
+    @keyword("ENV_BuildAndRun")
+    def env_build_and_run(self):
+        """Create and start all registered environment components.
+
+        After starting, all component YAML keys are published as
+        ``$MEM{ComponentName.key}`` variables for use in subsequent
+        keywords (e.g. ``$MEM{PostgresDB.env.POSTGRES_DB}``).
+
+        Example:
+        | ENV_Start      | WebShop    |
+        | ENV_Start      | PostgresDB |
+        | ENV_BuildAndRun |            |
+        """
+        self._manager.build_and_run()
+        self._publish_mem_entries()
+        logger.info("ENV_BuildAndRun: All components started.")
+
+    @keyword("ENV_WaitForReady")
+    def env_wait_for_ready(self, name: str, timeout: str | None = None):
+        """Wait until a component passes its health check.
+
+        Timeout is read from the component YAML (``timeout`` key).
+        An explicit parameter overrides the YAML value.
+
+        Example:
+        | ENV_WaitForReady | WebShop |             |
+        | ENV_WaitForReady | WebShop | timeout=60s |
+        """
+        if timeout is None:
+            timeout = self._manager.get_component_config(name).get("timeout", "30s")
+        timeout_seconds = self._parse_timeout(timeout)
+        self._manager.wait_for_ready(name, timeout=timeout_seconds)
+        logger.info(f"ENV_WaitForReady: '{name}' is ready.")
+
+    @keyword("ENV_Stop")
+    def env_stop(self):
+        """Stop and destroy all environment components.
+
+        Example:
+        | ENV_Stop |
+        """
+        self._log_all_components()
+        self._manager.stop_all()
+        logger.info("ENV_Stop: All components stopped and destroyed.")
+
+    @keyword("ENV_CreateImage")
+    def env_create_image(self, name: str):
+        """Snapshot the current state of all components for reuse.
+
+        Example:
+        | ENV_CreateImage | ShopWithTestData |
+        """
+        snapshots = self._manager.snapshot_all()
+        logger.info(f"ENV_CreateImage: Created image '{name}' with snapshots: {snapshots}")
+
+    @keyword("ENV_StartFromImage")
+    def env_start_from_image(self, image_name: str, fallback_keyword: str):
+        """Start from a cached image if it exists, otherwise run the fallback keyword.
+
+        Example:
+        | ENV_StartFromImage | ShopWithTestData | Setup Shop Environment |
+        """
+        # TODO: Implement image cache lookup
+        # For now, always run the fallback
+        from robot.libraries.BuiltIn import BuiltIn
+        logger.info(f"ENV_StartFromImage: Image '{image_name}' not found, running fallback '{fallback_keyword}'.")
+        BuiltIn().run_keyword(fallback_keyword)
+
+    @keyword("ENV_SnapshotOnFail")
+    def env_snapshot_on_fail(self):
+        """Snapshot all components if the current test has failed.
+
+        Use in [Teardown] to preserve the failure state for analysis.
+
+        Example:
+        | [Teardown] | Run Keywords | ENV_SnapshotOnFail | ENV_Stop |
+        """
+        from robot.libraries.BuiltIn import BuiltIn
+        status = BuiltIn().get_variable_value("${TEST STATUS}", "PASS")
+        if status == "FAIL":
+            snapshots = self._manager.snapshot_all()
+            logger.warn(f"ENV_SnapshotOnFail: Test failed. Snapshots: {snapshots}")
+        else:
+            logger.info("ENV_SnapshotOnFail: Test passed, no snapshot needed.")
+
+    def _load_component(self, name: str) -> dict:
+        """Load component definition from YAML."""
+        if self._components_dir is None:
+            raise RuntimeError(f"No components_dir configured. Cannot load '{name}'.")
+        yaml_path = self._components_dir / f"{name}.yaml"
+        if not yaml_path.exists():
+            raise FileNotFoundError(f"Component YAML not found: {yaml_path}")
+        data = load_component(yaml_path)
+        if name not in data:
+            raise KeyError(f"Component '{name}' not found in {yaml_path}. Keys: {list(data.keys())}")
+        return data[name]
+
+    def _log_all_components(self):
+        """Log output of all components into the Robot report."""
+        for name in list(self._manager._component_ids.keys()):
+            try:
+                logs = self._manager.get_logs(name)
+                if logs:
+                    logger.info(f"--- Logs: {name} ---\n{logs}", html=False)
+            except Exception as e:
+                logger.warn(f"Could not retrieve logs for '{name}': {e}")
+
+    def _publish_mem_entries(self):
+        """Publish all component config values as Robot Framework test variables."""
+        from robot.libraries.BuiltIn import BuiltIn
+        entries = self._manager.get_mem_entries()
+        for key, value in entries.items():
+            BuiltIn().set_test_variable(f"${{{key}}}", value)
+            logger.info(f"  $MEM{{{key}}} = {value}")
+
+    @staticmethod
+    def _parse_timeout(timeout: str) -> float:
+        """Parse timeout string like '30s', '2m', '120' to seconds."""
+        timeout = timeout.strip().lower()
+        if timeout.endswith("s"):
+            return float(timeout[:-1])
+        if timeout.endswith("m"):
+            return float(timeout[:-1]) * 60
+        return float(timeout)

okw_env/provider_base.py

@@ -0,0 +1,51 @@
+"""Base class for all OKW environment providers."""
+
+from abc import ABC, abstractmethod
+
+
+class OkwEnvProviderBase(ABC):
+    """Every environment provider (Docker, Proxmox, K8s, ...) implements this contract.
+
+    The constructor receives the component dict from YAML so that
+    provider-specific connection parameters (e.g. ``docker_host``,
+    ``proxmox_url``) can be read directly from the component definition.
+    """
+
+    def __init__(self, component: dict | None = None):
+        pass
+
+    @abstractmethod
+    def create(self, component: dict) -> str:
+        """Create the environment component. Returns a provider-specific ID."""
+
+    @abstractmethod
+    def start(self, component_id: str) -> None:
+        """Start the component."""
+
+    @abstractmethod
+    def is_ready(self, component_id: str) -> bool:
+        """Check if the component is ready (health check passed)."""
+
+    @abstractmethod
+    def get_logs(self, component_id: str) -> str:
+        """Retrieve logs from the component."""
+
+    @abstractmethod
+    def snapshot(self, component_id: str) -> str:
+        """Freeze the current state for later analysis. Returns a snapshot ID."""
+
+    def get_runtime_info(self, component_id: str) -> dict:
+        """Return runtime values that override YAML config (e.g. assigned port).
+
+        Default returns empty dict. Providers override as needed.
+        Called after start() to update component config with actual values.
+        """
+        return {}
+
+    @abstractmethod
+    def stop(self, component_id: str) -> None:
+        """Stop the component."""
+
+    @abstractmethod
+    def destroy(self, component_id: str) -> None:
+        """Remove the component and all associated resources."""

okw_env/provider_registry.py

@@ -0,0 +1,49 @@
+"""Auto-discovery of installed OKW environment providers via entry points."""
+
+from __future__ import annotations
+
+import sys
+
+from okw_env.provider_base import OkwEnvProviderBase
+
+_ENTRY_POINT_GROUP = "okw_env.providers"
+
+_cache: dict[str, type[OkwEnvProviderBase]] = {}
+
+
+def discover_providers() -> dict[str, type[OkwEnvProviderBase]]:
+    """Scan installed packages for OKW environment providers."""
+    if _cache:
+        return _cache
+
+    from importlib.metadata import entry_points
+    if sys.version_info >= (3, 12):
+        eps = entry_points(group=_ENTRY_POINT_GROUP)
+    elif sys.version_info >= (3, 10):
+        eps = entry_points().select(group=_ENTRY_POINT_GROUP)
+    else:
+        eps = entry_points().get(_ENTRY_POINT_GROUP, [])
+
+    for ep in eps:
+        _cache[ep.name] = ep.load()
+
+    return _cache
+
+
+def get_provider(name: str, component: dict | None = None) -> OkwEnvProviderBase:
+    """Get a provider instance by name, passing component config for connection details.
+
+    The component dict is forwarded to the provider constructor so that
+    provider-specific keys (e.g. ``docker_host``) are available without
+    a separate configuration mechanism.
+    """
+    providers = discover_providers()
+    if name not in providers:
+        available = list(providers.keys())
+        raise KeyError(
+            f"Provider '{name}' not found. "
+            f"Installed providers: {available}. "
+            f"Install a provider package (e.g. pip install robotframework-okw-env-docker)."
+        )
+    provider_class = providers[name]
+    return provider_class(component=component or {})

okw_env/yaml_loader.py

@@ -0,0 +1,78 @@
+"""YAML loader for environment component definitions with inheritance."""
+
+from pathlib import Path
+
+import yaml
+
+
+def load_component(yaml_path: str | Path) -> dict:
+    """Load a single environment component definition from YAML.
+
+    Supports ``extends`` for inheritance: the base component is loaded
+    first, then the child keys are merged on top (child wins).
+    Paths in ``extends`` are resolved relative to the YAML file.
+    """
+    path = Path(yaml_path)
+    if not path.exists():
+        raise FileNotFoundError(f"Component YAML not found: {path}")
+
+    with path.open("r", encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+
+    if not isinstance(data, dict):
+        return data
+
+    for component_name, component_def in data.items():
+        if isinstance(component_def, dict) and "extends" in component_def:
+            data[component_name] = _resolve_extends(component_def, path.parent)
+
+    return data
+
+
+def _resolve_extends(component: dict, base_dir: Path) -> dict:
+    """Resolve extends by loading the base and merging child on top."""
+    extends_ref = component.pop("extends")
+
+    base_name, base_def = _load_base(extends_ref, base_dir)
+
+    merged = {**base_def, **component}
+
+    for key in base_def:
+        if key in component and isinstance(base_def[key], dict) and isinstance(component[key], dict):
+            merged[key] = {**base_def[key], **component[key]}
+
+    if "extends" in merged:
+        merged = _resolve_extends(merged, base_dir)
+
+    return merged
+
+
+def _load_base(extends_ref: str, base_dir: Path) -> tuple[str, dict]:
+    """Load the base component. extends_ref can be 'ComponentName' or 'file.yaml:ComponentName'."""
+    if ":" in extends_ref:
+        file_part, component_name = extends_ref.rsplit(":", 1)
+        base_path = base_dir / file_part
+    else:
+        component_name = extends_ref
+        base_path = base_dir / f"{component_name}.yaml"
+
+    if not base_path.exists():
+        raise FileNotFoundError(
+            f"Base component file not found: {base_path} (extends: '{extends_ref}')"
+        )
+
+    with base_path.open("r", encoding="utf-8") as f:
+        base_data = yaml.safe_load(f)
+
+    if component_name not in base_data:
+        raise KeyError(
+            f"Base component '{component_name}' not found in {base_path}. "
+            f"Available: {list(base_data.keys())}"
+        )
+
+    base_def = base_data[component_name]
+
+    if isinstance(base_def, dict) and "extends" in base_def:
+        base_def = _resolve_extends(base_def, base_path.parent)
+
+    return component_name, base_def

robotframework_okw_env-0.1.0.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: robotframework-okw-env
+Version: 0.1.0
+Summary: Driver-agnostic environment abstraction for OKW4Robot. Defines keywords and YAML-based component definitions to build, run, and tear down ephemeral test environments.
+Project-URL: Repository, http://192.168.1.130:3000/Hrabovszki1023/robotframework-okw-env
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: robotframework>=6.0
+Requires-Dist: pyyaml>=6.0
+
+# robotframework-okw-env
+
+Driver-agnostic environment abstraction for [OKW4Robot](http://192.168.1.130:3000/Hrabovszki1023/robotframework-okw4robot).
+
+> Deutsche Version: [README_de.md](README_de.md)
+
+## What
+
+One set of keywords (`StartEnvironment`, `StopEnvironment`, `WaitForReady`, ...)
+to build, run, and tear down ephemeral test environments — regardless of the
+underlying provider (Docker, Proxmox, Kubernetes, ...).
+
+## Why — Signal vs. NOISE
+
+Test code should describe **what** the test needs, not **how** infrastructure
+is provisioned. Docker Compose syntax, Proxmox API calls, and Kubernetes
+manifests are NOISE — the test only needs:
+
+```robot
+ENV_Start        WebShop
+ENV_Start        PostgresDB    version=17
+ENV_BuildAndRun
+ENV_WaitForReady WebShop
+```
+
+## Architecture
+
+```
+┌──────────────────────────────┐
+│  Robot Framework Test        │  ENV_Start, ENV_Stop, ...
+├──────────────────────────────┤
+│  okw-env (this library)      │  Keywords, YAML loader, provider contract
+├──────────────┬───────────────┤
+│  okw-env-    │  okw-env-     │  Provider plugins
+│  docker      │  proxmox      │
+├──────────────┼───────────────┤
+│  Docker      │  Proxmox      │  Underlying APIs
+│  Compose     │  VE API       │
+└──────────────┴───────────────┘
+```
+
+## Install
+
+```bash
+pip install robotframework-okw-env
+```
+
+Plus one or more provider plugins:
+
+```bash
+pip install robotframework-okw-env-docker
+pip install robotframework-okw-env-proxmox
+```
+
+## Component YAML
+
+Environment components are defined in YAML — no infrastructure code in tests:
+
+```yaml
+PostgresDB:
+  provider: docker
+  image: postgres
+  version: "17"
+  port: 5432
+  env:
+    POSTGRES_DB: testdb
+    POSTGRES_PASSWORD: test123
+  healthcheck: "pg_isready -U postgres"
+```
+
+## Minimal Example
+
+```robot
+*** Settings ***
+Library    okw4robot.library.OKW4RobotLibrary    WITH NAME    OKW
+
+*** Test Cases ***
+Order With Payment Gateway
+    # Phase 0 — Environment
+    ENV_Start        WebShop
+    ENV_Start        PostgresDB
+    ENV_Start        PaymentGW
+    ENV_BuildAndRun
+    ENV_WaitForReady WebShop
+
+    # Phase 1-4 — Test
+    StartApp         MyShop
+    SetValue         Article      Laptop
+    ClickOn          Order
+    VerifyValue      Status       Paid
+    StopApp
+
+    # Phase 5 — Teardown
+    ENV_Stop
+```
+
+## Key Benefits
+
+- **Isolation** — Each test gets its own environment, enabling parallel execution
+- **Ephemeral** — Environments exist only during test execution, no security concerns
+- **Combinable** — Version matrix testing via templates
+- **Provider-agnostic** — Same test, different infrastructure
+
+## Provider Plugins
+
+| Plugin | Repository |
+|---|---|
+| [okw-env-docker](http://192.168.1.130:3000/Hrabovszki1023/robotframework-okw-env-docker) | Docker Compose |
+| [okw-env-proxmox](http://192.168.1.130:3000/Hrabovszki1023/robotframework-okw-env-proxmox) | Proxmox VE |

robotframework_okw_env-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+okw_env/__init__.py,sha256=0diLXgSJvGtXlFxtkm1xWniU_AwWFE8FNHRJ-8cKuGs,331
+okw_env/environment_manager.py,sha256=AqlK4fVNqHLNHJHZnu_t58dK0SSP77eWZiAdS0bwOrU,5655
+okw_env/library.py,sha256=ye8LLZz8tbCN76RHHnmt6rlUpCthLINy5qcT0mPCEg8,6929
+okw_env/provider_base.py,sha256=CQT30tS59rDGXG2TLuEwsb94Odg9ABZ6BJ30MIzlT1o,1710
+okw_env/provider_registry.py,sha256=vLw8879a59H1rLbHyGl3_XfOAaYzt3Wn-tZMeVxGDyc,1608
+okw_env/yaml_loader.py,sha256=P9B1NcRCBYobw_SzxGZjoVC7B8QHtoTOLADQMI3sidc,2563
+robotframework_okw_env-0.1.0.dist-info/METADATA,sha256=fg02Pdfz1lVEz43duwES1cYpN6QYSUj8L4Z6fdFBKUA,3698
+robotframework_okw_env-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+robotframework_okw_env-0.1.0.dist-info/top_level.txt,sha256=f88FRNRHcONjMLQMpRZ74_ZfcwQ9wA8PvpesucCQFok,8
+robotframework_okw_env-0.1.0.dist-info/RECORD,,

robotframework_okw_env-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

robotframework_okw_env-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+okw_env