mcp-virtual-computer 0.2.3__py3-none-any.whl

kilntainers/backends/test_docker_integration.py

@@ -0,0 +1,310 @@
+"""Integration tests for Docker backend.
+
+These tests require a running Docker or Podman daemon and are marked with
+@pytest.mark.integration. They execute real containers and verify
+the full integration. They are parameterized by engine ("docker", "podman").
+
+Run with: pytest -m integration
+Skip with: pytest -m "not integration"
+"""
+
+import asyncio
+import shutil
+import subprocess
+
+import pytest
+
+from kilntainers.backends.base import ExecRequest
+from kilntainers.backends.docker import (
+    DockerBackend,
+    DockerBackendConfig,
+    DockerSandbox,
+)
+from kilntainers.errors import BackendError, SandboxDiedError
+
+# Cache to track if a docker-like CLI is available and the daemon is running.
+_engine_available_cache: dict[str, bool] = {}
+
+
+def validate_engine_available(engine: str) -> None:
+    """Validate that the engine CLI is installed and the daemon is running, skipping the test if not."""
+    available = _engine_available_cache.get(engine, None)
+
+    if available is None:
+        available = _check_engine_available(engine)
+        _engine_available_cache[engine] = available
+
+    if not available:
+        pytest.skip(f"{engine} CLI not installed")
+
+
+def _check_engine_available(engine: str) -> bool:
+    """Check if the engine CLI is installed and the daemon is running."""
+    command_available = shutil.which(engine) is not None
+    if not command_available:
+        return False
+    try:
+        result = subprocess.run([engine, "info"], capture_output=True, text=True)
+        return result.returncode == 0
+    except subprocess.CalledProcessError:
+        return False
+
+
+async def get_docker_backend(engine: str) -> DockerBackend:
+    """Create and validate a Docker/Podman backend.
+
+    Skips the test if the engine CLI is not installed or the daemon is not running.
+    """
+    validate_engine_available(engine)
+
+    config = DockerBackendConfig(engine=engine)
+    backend = DockerBackend(config)
+    try:
+        await backend.validate()
+    except BackendError as e:
+        if f"Is the {engine} daemon running?" in str(e):
+            pytest.skip(f"{engine} daemon not running")
+        raise
+    return backend
+
+
+@pytest.fixture(params=["docker", "podman"])
+async def engine(request):
+    """Parameterize tests over container engine (docker, podman).
+
+    Automatically skips if the engine CLI is not installed on the system.
+    """
+    engine = request.param
+    validate_engine_available(engine)
+    return engine
+
+
+@pytest.fixture
+async def docker_backend(engine):
+    """Create a real Docker/Podman backend instance for the given engine.
+
+    Automatically skips if the engine daemon is not running.
+    """
+    return await get_docker_backend(engine)
+
+
+@pytest.fixture
+async def sandbox(docker_backend):
+    """Create a real Docker sandbox for testing.
+
+    The sandbox is automatically stopped after the test.
+    """
+    sb = await docker_backend.create_sandbox()
+    yield sb
+    # Cleanup: stop the sandbox
+    await sb.stop()
+
+
+# --- Connection Tests ---
+
+
+@pytest.mark.integration
+class TestConnection:
+    """Tests for Docker host connection configuration."""
+
+    @pytest.mark.asyncio
+    async def test_bad_host_fails_validation(self, engine):
+        """A bad --docker-host value causes validation to fail with BackendError."""
+        config = DockerBackendConfig(
+            engine=engine,
+            host="tcp://127.0.0.1:1",  # Connection refused is faster than timeout
+        )
+        backend = DockerBackend(config)
+
+        with pytest.raises(BackendError) as exc_info:
+            await asyncio.wait_for(backend.validate(), timeout=15)
+
+        assert "Cannot connect to" in str(exc_info.value)
+
+
+# --- Docker Specific Lifecycle Tests ---
+
+
+@pytest.mark.integration
+class TestDockerLifecycle:
+    """Tests for Docker-specific sandbox lifecycle operations."""
+
+    @pytest.mark.asyncio
+    async def test_create_sandbox_type(self, docker_backend):
+        """Sandbox creation returns correct type and ID format."""
+        sb = await docker_backend.create_sandbox()
+        assert isinstance(sb, DockerSandbox)
+        assert len(sb.sandbox_id) == 12
+        await sb.stop()
+
+
+# --- Timeout Tests ---
+
+
+@pytest.mark.integration
+class TestTimeout:
+    """Tests for timeout enforcement."""
+
+    @pytest.mark.asyncio
+    async def test_timeout_exceeded(self, sandbox):
+        """Long-running command is terminated after timeout."""
+        request = ExecRequest(command="sleep 60", timeout=1, output_limit=1024)
+        result = await sandbox.exec(request)
+        assert result.exit_code == 124
+        assert "timed out" in result.stderr
+
+
+# --- Network Isolation Tests ---
+
+
+@pytest.mark.integration
+class TestNetworkIsolation:
+    """Tests for network isolation behavior."""
+
+    @pytest.mark.asyncio
+    async def test_network_disabled_by_default(self, sandbox):
+        """Network access is blocked by default."""
+        request = ExecRequest(
+            command="curl -s --connect-timeout 2 http://example.com",
+            timeout=5,
+            output_limit=1024,
+        )
+        result = await sandbox.exec(request)
+        # Should fail because network is disabled
+        assert result.exit_code != 0
+
+    @pytest.mark.asyncio
+    async def test_network_enabled_works(self, docker_backend):
+        """Network access works when enabled."""
+        config = DockerBackendConfig(network_enabled=True)
+        backend = DockerBackend(config)
+        sb = await backend.create_sandbox()
+        try:
+            request = ExecRequest(
+                command="curl -s --connect-timeout 2 http://example.com",
+                timeout=5,
+                output_limit=1024,
+            )
+            result = await sb.exec(request)
+            # Should succeed (or at least reach the server)
+            # We just check it doesn't fail immediately
+            assert result.exit_code == 0 or "curl" in result.stderr
+        finally:
+            await sb.stop()
+
+
+# --- Death Detection Tests ---
+
+
+@pytest.mark.integration
+class TestDeathDetection:
+    """Tests for unexpected sandbox death detection."""
+
+    @pytest.mark.asyncio
+    async def test_wait_for_death_on_kill(self, sandbox, engine):
+        """wait_for_death returns when container is killed externally."""
+        # Start the death detection task
+        death_task = asyncio.create_task(sandbox.wait_for_death())
+
+        # Give it a moment to start
+        await asyncio.sleep(0.1)
+
+        # Kill the container externally
+        subprocess.run(
+            [engine, "kill", sandbox._container_id],
+            capture_output=True,
+        )
+
+        # wait_for_death should complete
+        await asyncio.wait_for(death_task, timeout=5)
+
+    @pytest.mark.asyncio
+    async def test_exec_after_container_dies(self, sandbox, engine):
+        """Exec raises SandboxDiedError when container dies during exec."""
+        # Kill the container externally
+        subprocess.run(
+            [engine, "kill", sandbox._container_id],
+            capture_output=True,
+        )
+        await asyncio.sleep(0.1)  # Give it time to die
+
+        # Next exec should detect the death
+        request = ExecRequest(command="echo test", timeout=5, output_limit=1024)
+
+        with pytest.raises(SandboxDiedError) as exc_info:
+            await sandbox.exec(request)
+        assert "died during command execution" in str(exc_info.value)
+
+
+# --- Cleanup Tests ---
+
+
+@pytest.mark.integration
+class TestCleanup:
+    """Tests for proper resource cleanup."""
+
+    @pytest.mark.asyncio
+    async def test_container_removed_on_stop(self, sandbox, engine):
+        """Container is removed (--rm flag) when stopped."""
+        container_id = sandbox._container_id
+
+        # Verify container exists
+        result = subprocess.run(
+            [engine, "inspect", "--format", "{{.State.Running}}", container_id],
+            capture_output=True,
+            text=True,
+        )
+        assert result.returncode == 0
+
+        # Stop the sandbox
+        await sandbox.stop()
+
+        # Container should be removed (not just stopped)
+        result = subprocess.run(
+            [engine, "inspect", container_id],
+            capture_output=True,
+        )
+        assert result.returncode != 0  # Container not found
+
+    @pytest.mark.asyncio
+    async def test_kilntainers_label_present(self, sandbox, engine):
+        """Container has kilntainers=true label."""
+        result = subprocess.run(
+            [
+                engine,
+                "inspect",
+                "--format",
+                '{{index .Config.Labels "kilntainers"}}',
+                sandbox._container_id,
+            ],
+            capture_output=True,
+            text=True,
+        )
+        assert result.returncode == 0
+        assert "true" in result.stdout
+
+
+# --- Tool Instructions Tests ---
+
+
+@pytest.mark.integration
+class TestToolInstructions:
+    """Tests for tool_instructions method."""
+
+    @pytest.mark.asyncio
+    async def test_tool_instructions_default_image(self, docker_backend):
+        """Default image returns tool instructions."""
+        instructions = docker_backend.tool_instructions()
+        assert instructions is not None
+        assert "Debian" in instructions
+        assert "bash" in instructions
+        assert "120" in instructions  # default timeout
+
+    @pytest.mark.asyncio
+    async def test_tool_instructions_custom_image(self, engine, docker_backend):
+        """Custom image returns None for tool instructions."""
+        config = DockerBackendConfig(engine=engine, image="alpine:latest")
+        backend = DockerBackend(config)
+        await backend.validate()
+        instructions = backend.tool_instructions()
+        assert instructions is None

kilntainers/backends/test_docker_management.py

@@ -0,0 +1,122 @@
+"""Docker named-computer management tests."""
+
+import json
+
+import pytest
+
+from kilntainers.backends.docker import (
+    COMPUTER_ID_LABEL,
+    IMAGE_LABEL,
+    TEMPORARY_LABEL,
+    DockerBackend,
+    DockerBackendConfig,
+    DockerSandbox,
+)
+
+
+def inspect_row(
+    computer_id: str = "dev-box",
+    *,
+    temporary: bool = False,
+    running: bool = True,
+) -> dict[str, object]:
+    return {
+        "Id": "a" * 64,
+        "Created": "2026-08-12T12:00:00Z",
+        "Config": {
+            "Labels": {
+                COMPUTER_ID_LABEL: computer_id,
+                TEMPORARY_LABEL: str(temporary).lower(),
+                IMAGE_LABEL: "debian:bookworm-slim",
+            }
+        },
+        "State": {"Running": running, "Status": "running" if running else "exited"},
+    }
+
+
+def test_permanent_run_command_has_name_labels_and_no_auto_remove() -> None:
+    backend = DockerBackend(DockerBackendConfig())
+    command = backend._build_run_command(computer_id="dev-box", temporary=False)
+
+    assert "--rm" not in command
+    assert "kilntainer-dev-box" in command
+    assert f"{COMPUTER_ID_LABEL}=dev-box" in command
+    assert f"{TEMPORARY_LABEL}=false" in command
+
+
+def test_temporary_run_command_uses_auto_remove() -> None:
+    backend = DockerBackend(DockerBackendConfig())
+    command = backend._build_run_command(computer_id="scratch", temporary=True)
+    assert "--rm" in command
+    assert f"{TEMPORARY_LABEL}=true" in command
+
+
+@pytest.mark.asyncio
+async def test_list_computers_reads_provider_labels(monkeypatch) -> None:
+    backend = DockerBackend(DockerBackendConfig())
+    backend._validated = True
+
+    async def fake_run(*args, **kwargs):
+        if args[:2] == ("ps", "-aq"):
+            return 0, b"aaaaaaaaaaaa\n", b""
+        if args[:2] == ("container", "inspect"):
+            return 0, json.dumps([inspect_row()]).encode(), b""
+        raise AssertionError(args)
+
+    monkeypatch.setattr(backend, "_run_docker", fake_run)
+    computers = await backend.list_computers()
+
+    assert len(computers) == 1
+    assert computers[0].computer_id == "dev-box"
+    assert computers[0].sandbox_id == "a" * 12
+    assert computers[0].temporary is False
+    assert computers[0].state == "running"
+
+
+@pytest.mark.asyncio
+async def test_attach_starts_stopped_permanent_container(monkeypatch) -> None:
+    backend = DockerBackend(DockerBackendConfig())
+    backend._validated = True
+    running = False
+    calls: list[tuple[str, ...]] = []
+
+    async def fake_run(*args, **kwargs):
+        nonlocal running
+        calls.append(args)
+        if args[:2] == ("container", "inspect"):
+            return 0, json.dumps([inspect_row(running=running)]).encode(), b""
+        if args[0] == "start":
+            running = True
+            return 0, b"", b""
+        raise AssertionError(args)
+
+    async def ready(self):
+        return None
+
+    monkeypatch.setattr(backend, "_run_docker", fake_run)
+    monkeypatch.setattr(DockerSandbox, "_verify_readiness", ready)
+    sandbox = await backend.attach_sandbox("dev-box")
+
+    assert sandbox is not None
+    assert sandbox.computer_id == "dev-box"
+    assert sandbox.temporary is False
+    assert any(call[0] == "start" for call in calls)
+
+
+@pytest.mark.asyncio
+async def test_delete_uses_force_remove(monkeypatch) -> None:
+    backend = DockerBackend(DockerBackendConfig())
+    backend._validated = True
+    calls: list[tuple[str, ...]] = []
+
+    async def fake_run(*args, **kwargs):
+        calls.append(args)
+        if args[:2] == ("container", "inspect"):
+            return 0, json.dumps([inspect_row()]).encode(), b""
+        if args[:2] == ("rm", "-f"):
+            return 0, b"", b""
+        raise AssertionError(args)
+
+    monkeypatch.setattr(backend, "_run_docker", fake_run)
+    assert await backend.delete_computer("dev-box") is True
+    assert any(call[:2] == ("rm", "-f") for call in calls)

kilntainers/backends/test_utils.py

@@ -0,0 +1,152 @@
+"""Mock sandbox and backend for testing higher-level code.
+
+These mocks are designed for Phase 4 (MCP server) tests, allowing
+testing of the server layer without requiring a real backend like Docker.
+"""
+
+import argparse
+import asyncio
+
+from kilntainers.backends.base import Backend, ExecRequest, ExecResult, Sandbox
+from kilntainers.config import BackendConfig
+from kilntainers.errors import BackendError, SandboxDiedError
+
+
+class MockSandbox(Sandbox):
+    """Sandbox that returns preconfigured ExecResults.
+
+    Designed for testing the MCP server layer without requiring a real
+    backend like Docker.
+    """
+
+    def __init__(
+        self,
+        *,
+        sandbox_id: str = "mock-sandbox-001",
+        exec_results: list[ExecResult] | None = None,
+    ) -> None:
+        """Initialize a mock sandbox.
+
+        Args:
+            sandbox_id: The sandbox ID to return.
+            exec_results: A queue of results to return from exec(). If None,
+                returns a default success result.
+        """
+        self._sandbox_id = sandbox_id
+        self._stopped = False
+        self._death_event = asyncio.Event()
+        self._stop_requested = False
+        self.exec_results: list[ExecResult] = exec_results or []
+        self.exec_calls: list[ExecRequest] = []
+
+    @property
+    def sandbox_id(self) -> str:
+        """Return the sandbox ID."""
+        return self._sandbox_id
+
+    async def exec(self, request: ExecRequest) -> ExecResult:
+        """Record the call and return a queued result or default."""
+        if self._death_event.is_set():
+            raise SandboxDiedError(f"mock sandbox {self._sandbox_id} died")
+        self.exec_calls.append(request)
+        if self.exec_results:
+            return self.exec_results.pop(0)
+        return ExecResult(
+            stdout="",
+            stderr="",
+            exit_code=0,
+            exec_duration_ms=1,
+        )
+
+    async def stop(self) -> None:
+        """Mark the sandbox as stopped."""
+        self._stopped = True
+        self._stop_requested = True
+        self._death_event.set()
+
+    async def wait_for_death(self) -> None:
+        """Block until the sandbox dies."""
+        await self._death_event.wait()
+
+    def simulate_death(self) -> None:
+        """Test helper: trigger sandbox death."""
+        self._death_event.set()
+
+    def is_stopped(self) -> bool:
+        """Test helper: check if stopped."""
+        return self._stopped
+
+
+class MockBackend(Backend):
+    """Backend that returns MockSandbox instances.
+
+    Designed for testing the MCP server layer without requiring a real
+    backend like Docker.
+    """
+
+    @classmethod
+    def add_cli_arguments(cls, group: argparse._ArgumentGroup) -> None:
+        """Mock implementation - does nothing."""
+
+    @classmethod
+    def config_from_args(cls, args: argparse.Namespace) -> BackendConfig:
+        """Mock implementation - returns default config."""
+        return BackendConfig()
+
+    def __init__(
+        self,
+        config: BackendConfig,
+        *,
+        tool_instructions: str | None = "mock instructions",
+        sandbox_id: str = "mock-sandbox-001",
+        exec_results: list[ExecResult] | None = None,
+    ) -> None:
+        """Initialize a mock backend.
+
+        Args:
+            config: The backend configuration.
+            tool_instructions: The tool instructions to return.
+            sandbox_id: The sandbox ID to use for created sandboxes.
+            exec_results: Results queue for created sandboxes.
+        """
+        super().__init__(config)
+        self._tool_instructions = tool_instructions
+        self._sandbox_id = sandbox_id
+        self._exec_results = exec_results
+        self._validated = False
+        # Test helpers for lazy creation testing
+        self.create_count = 0
+        self.fail_next_create = False
+
+    async def _validate(self) -> None:
+        """Mark as validated (no-op for mock)."""
+        self._validated = True
+
+    async def _create_sandbox(
+        self,
+        *,
+        computer_id: str | None = None,
+        temporary: bool = True,
+    ) -> Sandbox:
+        """Return a MockSandbox.
+
+        Supports test helpers:
+        - create_count: incremented on each sandbox creation
+        - fail_next_create: if True, raises BackendError and resets flag
+        """
+        if self.fail_next_create:
+            self.fail_next_create = False
+            raise BackendError("mock creation failure")
+        self.create_count += 1
+        return MockSandbox(
+            sandbox_id=self._sandbox_id,
+            exec_results=self._exec_results,
+        )
+
+    def tool_instructions(self) -> str | None:
+        """Return the configured tool instructions."""
+        return self._tool_instructions
+
+    def is_validated(self) -> bool:
+        """Test helper: check if validate was called."""
+        return self._validated