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

okw_env_docker/__init__.py

@@ -0,0 +1,4 @@
+from .docker_provider import DockerProvider
+from .library import OkwEnvDockerLibrary
+
+__all__ = ["DockerProvider", "OkwEnvDockerLibrary"]

okw_env_docker/docker_provider.py

@@ -0,0 +1,117 @@
+"""Docker provider for OKW environments.
+
+Uses the Docker Python SDK (docker-py) to communicate directly with the
+Docker Engine API. No local Docker CLI installation required.
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+
+import docker
+
+from okw_env.provider_base import OkwEnvProviderBase
+
+
+class DockerProvider(OkwEnvProviderBase):
+    """Provisions environment components as Docker containers via the Engine API."""
+
+    def __init__(self, base_url: str | None = None, component: dict | None = None):
+        component = component or {}
+        self._base_url = (
+            base_url
+            or component.get("docker_host")
+            or os.environ.get("DOCKER_HOST", "unix:///var/run/docker.sock")
+        )
+        self._client: docker.DockerClient | None = None
+        self._containers: dict[str, docker.models.containers.Container] = {}
+
+    def _get_client(self) -> docker.DockerClient:
+        if self._client is None:
+            self._client = docker.DockerClient(base_url=self._base_url)
+        return self._client
+
+    def create(self, component: dict) -> str:
+        """Pull image and create a container (without starting)."""
+        image = component.get("image", "")
+        version = component.get("version", "latest")
+        full_image = f"{image}:{version}"
+        port = component.get("port")
+        env = component.get("env", {})
+        healthcheck_cmd = component.get("healthcheck")
+        name = f"okw-{uuid.uuid4().hex[:8]}"
+
+        self._get_client().images.pull(image, tag=version)
+
+        ports = {f"{port}/tcp": None} if port else {}
+        env_list = [f"{k}={v}" for k, v in env.items()]
+
+        healthcheck = None
+        if healthcheck_cmd:
+            healthcheck = docker.types.Healthcheck(
+                test=["CMD-SHELL", healthcheck_cmd],
+                interval=5_000_000_000,
+                timeout=3_000_000_000,
+                retries=10,
+            )
+
+        container = self._get_client().containers.create(
+            full_image,
+            name=name,
+            ports=ports,
+            environment=env_list,
+            healthcheck=healthcheck,
+            detach=True,
+        )
+        self._containers[name] = container
+        return name
+
+    def start(self, component_id: str) -> None:
+        container = self._require_container(component_id)
+        container.start()
+
+    def get_runtime_info(self, component_id: str) -> dict:
+        """Read the actual host port assigned by Docker after start."""
+        container = self._require_container(component_id)
+        container.reload()
+        ports = container.attrs.get("NetworkSettings", {}).get("Ports", {})
+        for container_port, bindings in ports.items():
+            if bindings:
+                return {"port": int(bindings[0]["HostPort"])}
+        return {}
+
+    def is_ready(self, component_id: str) -> bool:
+        container = self._require_container(component_id)
+        container.reload()
+        state = container.attrs.get("State", {})
+
+        health = state.get("Health", {})
+        if health:
+            return health.get("Status") == "healthy"
+
+        return state.get("Status") == "running"
+
+    def get_logs(self, component_id: str) -> str:
+        container = self._require_container(component_id)
+        return container.logs().decode("utf-8", errors="replace")
+
+    def snapshot(self, component_id: str) -> str:
+        container = self._require_container(component_id)
+        snapshot_tag = f"{component_id}-snapshot"
+        container.commit(repository=snapshot_tag)
+        return snapshot_tag
+
+    def stop(self, component_id: str) -> None:
+        container = self._require_container(component_id)
+        container.stop(timeout=10)
+
+    def destroy(self, component_id: str) -> None:
+        container = self._require_container(component_id)
+        container.remove(v=True, force=True)
+        del self._containers[component_id]
+
+    def _require_container(self, component_id: str):
+        if component_id not in self._containers:
+            raise KeyError(f"Unknown container '{component_id}'. Active: {list(self._containers.keys())}")
+        return self._containers[component_id]

okw_env_docker/library.py

@@ -0,0 +1,139 @@
+"""OKW Environment Docker Library – Robot Framework keywords for Docker-based environments."""
+
+from __future__ import annotations
+
+from robot.api.deco import library
+
+from okw_env.library import OkwEnvLibrary
+
+from .docker_provider import DockerProvider
+
+
+@library(scope="GLOBAL")
+class OkwEnvDockerLibrary(OkwEnvLibrary):
+    """OKW Environment provisioning for Docker.
+
+    = Zero-Install Architecture =
+
+    This library communicates with the Docker Engine API directly via
+    the [https://docker-py.readthedocs.io/|Docker SDK for Python].
+    **No Docker CLI, no Docker Desktop, no docker-compose installation
+    required** — only ``pip install robotframework-okw-env-docker``
+    and a reachable Docker host.
+
+    This dramatically reduces installation NOISE: every machine that can
+    run Python and reach a Docker host over the network can provision
+    test environments — no admin rights, no platform-specific installers.
+
+    = Connection =
+
+    The Docker host is configured **per component in the YAML file** via
+    the ``docker_host`` key. This is intentional: the connection target is
+    a property of the test environment, not of the test machine. A test
+    suite can mix components on different Docker hosts — or even different
+    providers (Docker + Proxmox) — without any local configuration.
+
+    Resolution order for ``docker_host``:
+
+    | 1. | ``docker_host`` key in component YAML (recommended) |
+    | 2. | ``docker_host`` parameter on the Library constructor (fallback) |
+    | 3. | Environment variable ``DOCKER_HOST`` |
+    | 4. | Default: ``unix:///var/run/docker.sock`` (Linux only) |
+
+    *Why YAML and not a Library parameter?*
+
+    The test machine (Windows laptop, Linux CI runner) should not determine
+    where Docker runs. A developer on Windows and a CI runner on Linux use
+    the same YAML — the connection target stays the same. No ``DOCKER_HOST``
+    environment variable, no platform-specific config, no surprises.
+
+    = Installation =
+
+    | ``pip install robotframework-okw-env-docker`` |
+
+    That's it. One ``pip install``, one IP address in the YAML, test environments ready.
+
+    = Usage =
+
+    | **Settings** |
+    | Library | OkwEnvDockerLibrary | components_dir=components |
+
+    | **Test Cases** |
+    | Webshop mit Datenbank |
+    |     | ENV_Start       | PostgresDB |
+    |     | ENV_BuildAndRun |            |
+    |     | ENV_WaitForReady | PostgresDB |
+    |     | # ... test steps ... |        |
+    |     | [Teardown] | Run Keywords | ENV_SnapshotOnFail | ENV_Stop |
+
+    = Component YAML =
+
+    Each environment component is defined in a YAML file.
+    The ``docker_host`` tells the provider where to connect:
+
+    | ``PostgresDB.yaml`` |
+    | provider: docker |
+    | docker_host: tcp://192.168.1.123:2375 |
+    | image: postgres |
+    | version: "17" |
+    | port: 5432 |
+    | env: |
+    |     POSTGRES_DB: testdb |
+    | healthcheck: "pg_isready -U postgres" |
+    | timeout: 30s |
+
+    = Environment Variables via $MEM{} =
+
+    After ``ENV_BuildAndRun``, **all YAML keys** are published as Robot
+    Framework test variables using dot-notation. This bridges environment
+    provisioning with test keywords — the test knows where to connect
+    without hardcoding anything.
+
+    | *Variable* | *Source* | *Example value* |
+    | ``${PostgresDB.image}`` | YAML key | ``postgres`` |
+    | ``${PostgresDB.version}`` | YAML key | ``17`` |
+    | ``${PostgresDB.port}`` | YAML key | ``5432`` |
+    | ``${PostgresDB.env.POSTGRES_DB}`` | YAML nested key | ``testdb`` |
+    | ``${PostgresDB.env.POSTGRES_PASSWORD}`` | YAML nested key | ``secret`` |
+    | ``${PostgresDB.docker_host}`` | YAML key | ``tcp://192.168.1.123:2375`` |
+    | ``${PostgresDB.ID}`` | Runtime (container ID) | ``okw-3df2dcc8`` |
+
+    Usage in test:
+
+    | ENV_Start       | PostgresDB |
+    | ENV_BuildAndRun |            |
+    | ENV_WaitForReady | PostgresDB |
+    | Log | DB name: ${PostgresDB.env.POSTGRES_DB} |
+    | Log | Port: ${PostgresDB.port} |
+
+    In OKW GUI/API keywords, use ``$MEM{}`` syntax:
+
+    | SetValue | DB_Host | $MEM{PostgresDB.docker_host} |
+    | SetValue | DB_Name | $MEM{PostgresDB.env.POSTGRES_DB} |
+
+    *Design rationale:* The connection data lives in the YAML — not in
+    environment variables, not in CI config, not hardcoded in the test.
+    The same test runs against any Docker host by changing one YAML file.
+
+    = Signal vs. NOISE =
+
+    | *Signal* | *NOISE (hidden)* |
+    | ``ENV_Start PostgresDB`` | Docker API calls, image pull, container config |
+    | ``ENV_WaitForReady PostgresDB`` | Health check polling, timeout logic |
+    | ``${PostgresDB.env.POSTGRES_DB}`` | YAML parsing, variable publishing |
+    | ``ENV_Stop`` | Container stop, remove, volume cleanup |
+
+    The test case reads like a specification. The infrastructure is invisible.
+
+    = Runnable Examples =
+
+    See [https://github.com/Hrabovszki1023/okw-examples|okw-examples]
+    for complete working test suites.
+    """
+
+    ROBOT_LIBRARY_SCOPE = "GLOBAL"
+
+    def __init__(self, components_dir: str | None = None, docker_host: str | None = None):
+        super().__init__(components_dir=components_dir)
+        provider = DockerProvider(base_url=docker_host)
+        self._manager.set_provider(provider)

robotframework_okw_env_docker-0.1.0.dist-info/METADATA

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: robotframework-okw-env-docker
+Version: 0.1.0
+Summary: Robot Framework library providing OKW environment provisioning with Docker.
+Project-URL: Repository, http://192.168.1.130:3000/Hrabovszki1023/robotframework-okw-env-docker
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: robotframework>=6.0
+Requires-Dist: robotframework-okw-env>=0.1.0
+Requires-Dist: docker>=7.0.0
+Requires-Dist: pyyaml>=6.0
+
+# robotframework-okw-env-docker
+
+Docker Compose provider for [okw-env](http://192.168.1.130:3000/Hrabovszki1023/robotframework-okw-env).
+
+> Deutsche Version: [README_de.md](README_de.md)
+
+## What
+
+Implements the OKW Environment Provider Contract using Docker Compose.
+Generates `docker-compose.yml` from YAML component definitions and
+manages the full container lifecycle (create, start, health check,
+logs, snapshot, stop, destroy).
+
+## Why — Signal vs. NOISE
+
+Docker Compose syntax is NOISE. The tester only writes:
+
+```robot
+ENV_Start        PostgresDB
+ENV_BuildAndRun
+ENV_WaitForReady PostgresDB
+```
+
+The framework generates the Compose file, starts the container,
+and polls the health check. No Docker knowledge required in test code.
+
+## Install
+
+```bash
+pip install robotframework-okw-env-docker
+```
+
+This automatically installs `robotframework-okw-env` (core) and
+`robotframework-docker` (Docker Compose engine).
+
+## Component YAML
+
+```yaml
+PostgresDB:
+  provider: docker
+  image: postgres
+  version: "17"
+  port: 5432
+  env:
+    POSTGRES_DB: testdb
+    POSTGRES_PASSWORD: testpass
+  healthcheck: "pg_isready -U postgres"
+  timeout: 30s
+```
+
+## Minimal Example
+
+```robot
+*** Settings ***
+Library    okw_env.library.OkwEnvLibrary    components_dir=components    WITH NAME    ENV
+
+*** Test Cases ***
+Database Is Reachable
+    ENV_Start        PostgresDB
+    ENV_BuildAndRun
+    ENV_WaitForReady    PostgresDB
+    Log    PostgresDB is ready for testing.
+    [Teardown]    ENV_Stop
+```
+
+## Architecture
+
+```
+okw-env (keywords, YAML loader, registry)
+    │
+    ▼
+okw-env-docker (this library)
+    │
+    ▼
+DockerComposeLibrary (robotframework-docker)
+    │
+    ▼
+Docker Compose CLI → Docker Engine
+```
+
+## Documentation
+
+- [CONTRACT.md](docs/CONTRACT.md) — How this provider implements the contract
+- [SPECIFICATION.md](docs/SPECIFICATION.md) — Lifecycle, isolation, snapshot model
+- [KEYWORDS.md](docs/KEYWORDS.md) — Keyword reference with examples

robotframework_okw_env_docker-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+okw_env_docker/__init__.py,sha256=o3N2xY3xSyxuqW9vhr9aK9ae_6OiUYHSGgTRiVEcu3w,138
+okw_env_docker/docker_provider.py,sha256=6KmtQQFH0daQlkmVFGQT2Y6ldeNANAUHKPbSOJJz7D8,4176
+okw_env_docker/library.py,sha256=wugiKI877qsirMJV45VPXkPG0UG-zBMc88Y-B91QAhk,5272
+robotframework_okw_env_docker-0.1.0.dist-info/METADATA,sha256=R1rO0HybgIg_U9Ta31inU2-PtYvGHzG-tzmqCrxHIus,2429
+robotframework_okw_env_docker-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+robotframework_okw_env_docker-0.1.0.dist-info/entry_points.txt,sha256=86OgurZYTD01naWHeROqyDHEcdGhn7tDmcz8RR-QFcI,59
+robotframework_okw_env_docker-0.1.0.dist-info/top_level.txt,sha256=wESfcmQix8F2A2lBj8at_1yH07xXbnzvMpimNKykMXE,15
+robotframework_okw_env_docker-0.1.0.dist-info/RECORD,,

robotframework_okw_env_docker-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_docker-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[okw_env.providers]
+docker = okw_env_docker:DockerProvider

robotframework_okw_env_docker-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+okw_env_docker