godot-e2e 1.0.0__py3-none-any.whl

godot_e2e/__init__.py

@@ -0,0 +1,47 @@
+"""godot-e2e: Out-of-process E2E testing tool for Godot."""
+
+from .commands import GodotE2E
+from .types import (
+    Vector2,
+    Vector2i,
+    Vector3,
+    Vector3i,
+    Rect2,
+    Rect2i,
+    Color,
+    Transform2D,
+    NodePath,
+    deserialize,
+    serialize,
+    GodotE2EError,
+    NodeNotFoundError,
+    TimeoutError,
+    ConnectionLostError,
+    CommandError,
+)
+from .client import GodotClient
+from .launcher import GodotLauncher
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "GodotE2E",
+    "Vector2",
+    "Vector2i",
+    "Vector3",
+    "Vector3i",
+    "Rect2",
+    "Rect2i",
+    "Color",
+    "Transform2D",
+    "NodePath",
+    "deserialize",
+    "serialize",
+    "GodotE2EError",
+    "NodeNotFoundError",
+    "TimeoutError",
+    "ConnectionLostError",
+    "CommandError",
+    "GodotClient",
+    "GodotLauncher",
+]

godot_e2e/cli.py

@@ -0,0 +1,10 @@
+"""CLI entry point for godot-e2e (P2 scope -- minimal stub)."""
+
+
+def main():
+    print("godot-e2e REPL is not yet implemented (P2 scope).")
+    print("Use pytest to run E2E tests instead.")
+
+
+if __name__ == "__main__":
+    main()

godot_e2e/client.py

@@ -0,0 +1,128 @@
+"""TCP client with length-prefix framing for communicating with Godot."""
+
+from __future__ import annotations
+
+import json
+import socket
+import struct
+import threading
+from typing import Any, Dict
+
+from .types import (
+    CommandError,
+    ConnectionLostError,
+    NodeNotFoundError,
+)
+
+
+class GodotClient:
+    """Blocking TCP client that speaks the godot-e2e wire protocol.
+
+    The wire format is simple length-prefixed JSON:
+        [4-byte big-endian uint32 payload length][UTF-8 JSON payload]
+    """
+
+    def __init__(self, host: str = "127.0.0.1", port: int = 6008) -> None:
+        self.host = host
+        self.port = port
+        self._sock: socket.socket | None = None
+        self._recv_buffer: bytes = b""
+        self._next_id: int = 1
+        self._lock = threading.Lock()
+
+    # ------------------------------------------------------------------
+    # Connection lifecycle
+    # ------------------------------------------------------------------
+
+    def connect(self, timeout: float = 10.0) -> None:
+        """Connect to Godot's AutomationServer."""
+        # Close any previous socket to avoid leaking on retry.
+        if self._sock is not None:
+            try:
+                self._sock.close()
+            except Exception:
+                pass
+        self._recv_buffer = b""
+        self._sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self._sock.settimeout(timeout)
+        self._sock.connect((self.host, self.port))
+
+    def close(self) -> None:
+        """Close the TCP connection."""
+        if self._sock is not None:
+            try:
+                self._sock.close()
+            except Exception:
+                pass
+            self._sock = None
+        self._recv_buffer = b""
+
+    # ------------------------------------------------------------------
+    # Command API
+    # ------------------------------------------------------------------
+
+    def send_command(self, action: str, **params: Any) -> Dict[str, Any]:
+        """Send a command and block until the matching response arrives.
+
+        Returns the parsed response dict with values deserialized into
+        Python types (Vector2, Color, etc.) where applicable.
+
+        Raises:
+            NodeNotFoundError: if the server reports a missing node.
+            CommandError: for any other server-side error.
+            ConnectionLostError: if the connection drops.
+        """
+        with self._lock:
+            cmd_id = self._next_id
+            self._next_id += 1
+
+            msg: Dict[str, Any] = {"id": cmd_id, "action": action, **params}
+            payload = json.dumps(msg).encode("utf-8")
+            header = struct.pack(">I", len(payload))
+
+            try:
+                self._sock.sendall(header + payload)
+            except (OSError, AttributeError) as exc:
+                raise ConnectionLostError(f"Failed to send command: {exc}") from exc
+
+            response = self._read_response()
+
+            if "error" in response:
+                error_code = response["error"]
+                error_msg = response.get("message", error_code)
+                if "not found" in error_msg.lower() or "not found" in error_code.lower():
+                    raise NodeNotFoundError(error_msg)
+                raise CommandError(error_msg)
+
+            return response
+
+    def hello(self, token: str) -> Dict[str, Any]:
+        """Send the handshake. Must be the first command after connecting."""
+        return self.send_command("hello", token=token, protocol_version=1)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _read_response(self) -> Dict[str, Any]:
+        """Read one length-prefixed JSON message from the socket."""
+        while True:
+            # Try to extract a complete message from the buffer.
+            if len(self._recv_buffer) >= 4:
+                payload_len = struct.unpack(">I", self._recv_buffer[:4])[0]
+                total = 4 + payload_len
+                if len(self._recv_buffer) >= total:
+                    payload = self._recv_buffer[4:total]
+                    self._recv_buffer = self._recv_buffer[total:]
+                    return json.loads(payload.decode("utf-8"))
+
+            # Need more data from the network.
+            try:
+                chunk = self._sock.recv(4096)
+                if not chunk:
+                    raise ConnectionLostError("Connection closed by Godot")
+                self._recv_buffer += chunk
+            except socket.timeout as exc:
+                raise ConnectionLostError(f"Connection timed out: {exc}") from exc
+            except OSError as exc:
+                raise ConnectionLostError(f"Connection lost: {exc}") from exc

godot_e2e/commands.py

@@ -0,0 +1,234 @@
+"""High-level E2E command API for Godot."""
+
+from .client import GodotClient
+from .types import (
+    serialize, deserialize, TimeoutError, NodeNotFoundError,
+    ConnectionLostError, CommandError
+)
+import time
+
+
+class GodotE2E:
+    """High-level E2E testing interface for Godot.
+
+    Usage:
+        with GodotE2E.launch("./my_project") as game:
+            game.wait_for_node("/root/Main")
+            pos = game.get_property("/root/Main/Player", "position")
+    """
+
+    def __init__(self, client: GodotClient, launcher=None):
+        self._client = client
+        self._launcher = launcher
+
+    @classmethod
+    def launch(cls, project_path: str, godot_path: str = None,
+               port: int = 0, timeout: float = 10.0, extra_args: list = None):
+        """Launch Godot and return a connected GodotE2E instance.
+        Returns a context manager."""
+        from .launcher import GodotLauncher
+        launcher = GodotLauncher()
+        client = launcher.launch(project_path, godot_path, port, timeout, extra_args)
+        return cls(client, launcher)
+
+    @classmethod
+    def connect(cls, host: str = "127.0.0.1", port: int = 6008, token: str = ""):
+        """Connect to an already-running Godot instance."""
+        client = GodotClient(host, port)
+        client.connect()
+        client.hello(token)
+        return cls(client)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def close(self):
+        if self._launcher:
+            self._launcher.kill()
+        elif self._client:
+            self._client.close()
+
+    # --- Node Operations (F2) ---
+
+    def node_exists(self, path: str) -> bool:
+        resp = self._client.send_command("node_exists", path=path)
+        return resp.get("exists", False)
+
+    def get_property(self, path: str, property: str):
+        resp = self._client.send_command("get_property", path=path, property=property)
+        return deserialize(resp["result"])
+
+    def set_property(self, path: str, property: str, value):
+        self._client.send_command(
+            "set_property", path=path, property=property, value=serialize(value)
+        )
+
+    def call(self, path: str, method: str, args: list = None):
+        resp = self._client.send_command(
+            "call_method", path=path, method=method,
+            args=[serialize(a) for a in (args or [])]
+        )
+        return deserialize(resp.get("result"))
+
+    def find_by_group(self, group: str) -> list:
+        resp = self._client.send_command("find_by_group", group=group)
+        return resp.get("nodes", [])
+
+    def query_nodes(self, pattern: str = "", group: str = "") -> list:
+        resp = self._client.send_command("query_nodes", pattern=pattern, group=group)
+        return resp.get("nodes", [])
+
+    def get_tree(self, path: str = "/root", depth: int = 4) -> dict:
+        resp = self._client.send_command("get_tree", path=path, depth=depth)
+        return resp.get("tree", {})
+
+    def batch(self, commands: list) -> list:
+        """Execute multiple commands in one round-trip.
+
+        Each command is either a dict with an "action" key, or a tuple/list of
+        (action, params_dict).
+
+        Example::
+
+            results = game.batch([
+                ("get_property", {"path": "/root/Player", "property": "health"}),
+                {"action": "node_exists", "path": "/root/Enemy"},
+            ])
+        """
+        cmd_list = []
+        for cmd in commands:
+            if isinstance(cmd, dict):
+                cmd_list.append(cmd)
+            elif isinstance(cmd, (list, tuple)):
+                action = cmd[0]
+                params = cmd[1] if len(cmd) > 1 else {}
+                cmd_list.append({"action": action, **params})
+        resp = self._client.send_command("batch", commands=cmd_list)
+        results = resp.get("results", [])
+        return [
+            deserialize(r.get("result")) if "result" in r else r
+            for r in results
+        ]
+
+    # --- Input Simulation (F3) ---
+
+    def input_key(self, keycode: int, pressed: bool, physical: bool = False):
+        self._client.send_command(
+            "input_key", keycode=keycode, pressed=pressed, physical=physical
+        )
+
+    def input_action(self, action_name: str, pressed: bool, strength: float = 1.0):
+        self._client.send_command(
+            "input_action", action_name=action_name, pressed=pressed, strength=strength
+        )
+
+    def input_mouse_button(
+        self, x: float, y: float, button: int = 1, pressed: bool = True
+    ):
+        self._client.send_command(
+            "input_mouse_button", x=x, y=y, button=button, pressed=pressed
+        )
+
+    def input_mouse_motion(
+        self, x: float, y: float, relative_x: float = 0, relative_y: float = 0
+    ):
+        self._client.send_command(
+            "input_mouse_motion", x=x, y=y,
+            relative_x=relative_x, relative_y=relative_y
+        )
+
+    # --- High-Level Helpers (F6) ---
+
+    def press_key(self, keycode: int):
+        """Press and release a key."""
+        self.input_key(keycode, True)
+        self.input_key(keycode, False)
+
+    def press_action(self, action_name: str, strength: float = 1.0):
+        """Press and release an action."""
+        self.input_action(action_name, True, strength)
+        self.input_action(action_name, False)
+
+    def click(self, x: float, y: float, button: int = 1):
+        """Click at screen position."""
+        self.input_mouse_button(x, y, button, True)
+        self.input_mouse_button(x, y, button, False)
+
+    def click_node(self, path: str):
+        """Click at a node's screen position."""
+        self._client.send_command("click_node", path=path)
+
+    # --- Frame Synchronization (F4) ---
+
+    def wait_process_frames(self, count: int = 1):
+        self._client.send_command("wait_process_frames", count=count)
+
+    def wait_physics_frames(self, count: int = 1):
+        self._client.send_command("wait_physics_frames", count=count)
+
+    def wait_seconds(self, seconds: float):
+        self._client.send_command("wait_seconds", seconds=seconds)
+
+    # --- Synchronization (F6/F9) ---
+
+    def wait_for_node(self, path: str, timeout: float = 5.0):
+        """Wait until a node exists in the scene tree.
+
+        Raises TimeoutError with a scene tree dump if the timeout is exceeded.
+        """
+        try:
+            self._client.send_command("wait_for_node", path=path, timeout=timeout)
+        except CommandError as e:
+            if "timeout" in str(e).lower():
+                tree = None
+                try:
+                    tree = self.get_tree()
+                except Exception:
+                    pass
+                raise TimeoutError(
+                    f"Timed out waiting for node '{path}' after {timeout}s",
+                    scene_tree=tree,
+                ) from e
+            raise
+
+    def wait_for_signal(self, path: str, signal_name: str, timeout: float = 5.0):
+        resp = self._client.send_command(
+            "wait_for_signal", path=path, signal_name=signal_name, timeout=timeout
+        )
+        return resp.get("args", [])
+
+    def wait_for_property(self, path: str, property: str, value, timeout: float = 5.0):
+        self._client.send_command(
+            "wait_for_property", path=path, property=property,
+            value=serialize(value), timeout=timeout,
+        )
+
+    # --- Scene Management (F11) ---
+
+    def get_scene(self) -> str:
+        resp = self._client.send_command("get_scene")
+        return resp.get("scene", "")
+
+    def change_scene(self, scene_path: str):
+        self._client.send_command("change_scene", scene_path=scene_path)
+
+    def reload_scene(self):
+        self._client.send_command("reload_scene")
+
+    # --- Screenshot (F10) ---
+
+    def screenshot(self, save_path: str = "") -> str:
+        """Capture a screenshot. Returns the absolute path to the saved PNG."""
+        resp = self._client.send_command("screenshot", save_path=save_path)
+        return resp.get("path", "")
+
+    # --- Misc ---
+
+    def quit(self, exit_code: int = 0):
+        try:
+            self._client.send_command("quit", exit_code=exit_code)
+        except ConnectionLostError:
+            pass  # Expected — Godot exits

godot_e2e/fixtures.py

@@ -0,0 +1,130 @@
+"""pytest fixtures for godot-e2e."""
+
+import pytest
+import os
+from .commands import GodotE2E
+
+
+def pytest_configure(config):
+    """Register the screenshot-on-failure plugin (idempotent)."""
+    if not config.pluginmanager.has_plugin("godot_e2e_screenshot"):
+        config.pluginmanager.register(ScreenshotOnFailure(), "godot_e2e_screenshot")
+
+
+class ScreenshotOnFailure:
+    """pytest plugin that captures screenshots on test failure."""
+
+    @pytest.hookimpl(tryfirst=True, hookwrapper=True)
+    def pytest_runtest_makereport(self, item, call):
+        outcome = yield
+        report = outcome.get_result()
+        # Stash the call report on the test item so fixtures can access it.
+        setattr(item, f"rep_{report.when}", report)
+
+
+@pytest.fixture(scope="module")
+def _game_instance(request):
+    """Module-scoped: one Godot process per test module."""
+    project_path = _get_project_path(request)
+    godot_path = _get_godot_path(request)
+
+    with GodotE2E.launch(project_path, godot_path=godot_path) as game:
+        yield game
+
+
+@pytest.fixture(scope="function")
+def game(_game_instance, request):
+    """Function-scoped fixture: reload the scene between tests and capture a
+    screenshot on failure.
+
+    Requires a module-scoped ``_game_instance`` to be in scope (one Godot
+    process shared across all tests in the same module).
+    """
+    _game_instance.reload_scene()
+    _game_instance.wait_for_node("/root", timeout=5.0)
+    yield _game_instance
+
+    # Screenshot on failure
+    if hasattr(request.node, "rep_call") and request.node.rep_call.failed:
+        _take_failure_screenshot(_game_instance, request.node.name)
+
+
+@pytest.fixture(scope="function")
+def game_fresh(request):
+    """Function-scoped fixture: fresh Godot process per test (maximum isolation).
+
+    Use this when tests must not share any Godot state at all.
+    """
+    project_path = _get_project_path(request)
+    godot_path = _get_godot_path(request)
+
+    with GodotE2E.launch(project_path, godot_path=godot_path) as game:
+        yield game
+
+        # Screenshot on failure
+        if hasattr(request.node, "rep_call") and request.node.rep_call.failed:
+            _take_failure_screenshot(game, request.node.name)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _take_failure_screenshot(game: GodotE2E, test_name: str):
+    """Capture a screenshot on test failure and save it to ``test_output/``."""
+    try:
+        os.makedirs("test_output", exist_ok=True)
+        safe_name = test_name.replace("/", "_").replace("\\", "_")
+        path = os.path.join("test_output", f"{safe_name}_failure.png")
+        game.screenshot(os.path.abspath(path))
+        print(f"\n[godot-e2e] Failure screenshot saved: {path}")
+    except Exception as e:
+        print(f"\n[godot-e2e] Failed to capture screenshot: {e}")
+
+
+def _get_project_path(request) -> str:
+    """Resolve the Godot project path from multiple sources (in priority order):
+
+    1. ``@pytest.mark.godot_project("path")`` marker on the test/module.
+    2. ``godot_e2e_project_path`` key in ``pytest.ini`` / ``pyproject.toml``.
+    3. ``GODOT_E2E_PROJECT_PATH`` environment variable.
+    4. Auto-detection: searches ``./godot_project``, ``../godot_project``, and
+       ``.`` for a ``project.godot`` file.
+    """
+    # 1. Marker
+    marker = request.node.get_closest_marker("godot_project")
+    if marker:
+        return marker.args[0]
+
+    # 2. pytest config key
+    try:
+        config_path = request.config.getini("godot_e2e_project_path")
+        if config_path:
+            return config_path
+    except (ValueError, KeyError):
+        pass
+
+    # 3. Environment variable
+    env_path = os.environ.get("GODOT_E2E_PROJECT_PATH", "")
+    if env_path:
+        return env_path
+
+    # 4. Auto-detection
+    for candidate in ["./godot_project", "../godot_project", "."]:
+        if os.path.isfile(os.path.join(candidate, "project.godot")):
+            return candidate
+
+    raise FileNotFoundError(
+        "Could not find a Godot project. Set the GODOT_E2E_PROJECT_PATH "
+        "environment variable, add 'godot_e2e_project_path' to your pytest "
+        "configuration, or use @pytest.mark.godot_project('path/to/project') "
+        "on your test class or module."
+    )
+
+
+def _get_godot_path(request) -> str | None:
+    """Return the path to the Godot executable, or None to use PATH lookup.
+
+    Reads from the ``GODOT_PATH`` environment variable.
+    """
+    return os.environ.get("GODOT_PATH") or None