RandallLiuXin/GodotMaker / skills/core/godot-e2e
godot-e2e
VerifiedWrite and run E2E (end-to-end) game tests using the godot-e2e framework. Python controls a live Godot game over TCP — Locator-based semantic queries, expect() auto-retry assertions, and engine log capture make failures self-diagnosing. Use this skill whenever you need to: - Test actual gameplay: player movement, collisions, scoring, scene transitions - Verify UI interactions: button clicks, label text, menu navigation - Write integration tests that run the real game (not mocked unit tests) - Debug E2E test failures or set up E2E test infrastructure Triggers: "E2E test", "end-to-end test", "gameplay test", "test the game running", "simulate input", "test player movement", "test UI clicks", "godot-e2e", "integration test for game", "test scene transitions".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.3 KB |
| references/api-reference.md | markdown | 34.7 KB |
| references/testing-patterns.md | markdown | 25.9 KB |
references/api-reference.md
View on GitHub# godot-e2e API Reference
Complete reference for all classes, methods, types, and exceptions.
## Table of Contents
1. [GodotE2E (main class)](#godote2e)
2. [Locator API](#locator-api)
3. [expect() — Auto-Retry Assertions](#expect--auto-retry-assertions)
4. [Engine Log Capture](#engine-log-capture)
5. [Node Operations](#node-operations)
6. [Input Simulation](#input-simulation)
7. [High-Level Input Helpers](#high-level-input-helpers)
8. [Frame Synchronization](#frame-synchronization)
9. [Synchronization (wait_for_*)](#synchronization)
10. [Scene Management](#scene-management)
11. [Screenshot](#screenshot)
12. [Batch Operations](#batch-operations)
13. [Types](#types)
14. [Exceptions](#exceptions)
15. [GodotClient (low-level)](#godotclient)
16. [GodotLauncher](#godotlauncher)
17. [pytest Fixtures](#pytest-fixtures)
18. [Godot Addon Setup](#godot-addon-setup)
19. [Wire Protocol Summary](#wire-protocol-summary)
---
## GodotE2E
`from godot_e2e import GodotE2E`
### GodotE2E.launch()
```python
GodotE2E.launch(
project_path: str, # Path to dir containing project.godot
godot_path: str = None, # Godot executable path (auto-discovered if None)
port: int = 0, # TCP port (0 = auto-allocate free port)
timeout: float = 10.0, # Seconds to wait for connection
extra_args: list = None, # Extra args forwarded to Godot process
log_verbosity: str = None, # "error" / "warning" / "info"; None uses addon default ("warning")
) -> GodotE2E # context manager
```
Launches Godot with `--e2e` flag, connects over TCP, completes handshake.
Use as context manager for automatic cleanup.
**Godot discovery order**: `godot_path` param > `GODOT_PATH` env var > PATH search
(`godot`, `godot4`, `Godot_v4`).
**Raises**: `FileNotFoundError` (no Godot), `RuntimeError` (Godot exits early),
`ConnectionError` (timeout), `ValueError` (invalid `log_verbosity`).
```python
with GodotE2E.launch("./my_project", timeout=15.0, log_verbosity="info") as game:
game.wait_for_node("/root/Main", timeout=10.0)
# ... tests ...
# Godot process killed automatically
```
### GodotE2E.connect()
```python
GodotE2E.connect(
host: str = "127.0.0.1",
port: int = 6008,
token: str = ""
) -> GodotE2E
```
Connect to an already-running Godot instance (started manually with `--e2e`).
If token was set via `--e2e-token`, it must match.
```python
# Start Godot manually: godot --path ./project -- --e2e --e2e-port=6008
game = GodotE2E.connect(port=6008)
```
### close()
Terminate the Godot process (if launched) and close TCP connection.
Called automatically by context manager.
---
## Locator API
A `Locator` is a lazy reference to one or more nodes. Queries
re-resolve on every action, so a Locator created before
`reload_scene()` keeps working after.
### Construction
| Method | Signature | Returns |
|--------|-----------|---------|
| `game.locator(**kwargs)` | At least one of `path`, `name`, `group`, `text`, `type`, `script`. AND-composed. | `Locator` |
| `game.get_by_text(text)` | Sugar for `locator(text=text)`. | `Locator` |
| `game.get_by_button(text)` | Sugar for `locator(type="BaseButton", text=text)`. Covers `Button`, `CheckBox`, `OptionButton`, `MenuButton`, `LinkButton`. | `Locator` |
### Constructor Kwargs
| Kwarg | Type | Behavior |
|---|---|---|
| `path` | `str` | Absolute scene path (e.g., `"/root/Main/Player"`); resolves 0 or 1 match. |
| `name` | `str` | Node name. Glob (`*`, `?`) if value contains wildcards, else exact. |
| `group` | `str` | Godot group name; exact match. |
| `text` | `str` | Matched against `node.text` property. Same glob/exact rule as `name`. |
| `script` | `str` | Script resource path (e.g., `"res://player.gd"`); exact. |
| `type` | `str` | Class name; matched via `is X` (instanceof) — descendants included. |
### Refinement (returns new Locator; never mutates self)
| Method | Returns | Notes |
|---|---|---|
| `loc.filter(**kwargs)` | `Locator` | Add AND-composed predicates (same kwargs as `locator()`). |
| `loc.first()` | `Locator` | Always pick first match in tree-walk order. |
| `loc.nth(i: int)` | `Locator` | Pick i-th match (zero-indexed). Raises `ValueError` if `i < 0`. |
| `loc.all()` | `list[Locator]` | Resolve immediately; returns path-pinned Locator per match. `[]` if no match (no raise). Snapshot at call time. |
| `loc.locator(**kwargs)` | `Locator` | Sub-query scoped under this Locator's resolved node. Parent is re-resolved on every action of the chained Locator. Parent must resolve to exactly one node at action time; `MultipleMatchesError` / `NodeNotFoundError` raised when action runs (not on method call). `exists()` / `count()` swallow these and return `False` / `0`. |
### Inspection (safe from multi/zero match)
| Method | Returns | Raises | Notes |
|---|---|---|---|
| `loc.exists()` | `bool` | — | True if query resolves to ≥1 node. Never raises on lookup issues; connection errors still propagate. |
| `loc.count()` | `int` | — | Number of matching nodes. |
| `loc.is_visible()` | `bool` | `MultipleMatchesError`, `NodeNotFoundError` | Whether single-match target is visible in scene tree (uses `is_visible_in_tree`). |
| `loc.is_actionable()` | `bool` | `MultipleMatchesError`, `NodeNotFoundError` | Whether single-match target passes all actionability checks. |
### Action (re-resolves; requires exactly one match)
| Method | Signature | Notes / Raises |
|---|---|---|
| `loc.click(*, force=False, timeout=5.0)` | `None` | For `Control`: polls actionability up to `timeout`, raises `NotActionableError` if never passes. For `Node2D`: only checks `is_visible_in_tree()`. For `Node3D` / `Window` / `Node`: fails with `unclickable_node_type`. `force=True` skips check entirely. |
| `loc.hover()` | `None` | Inject `InputEventMouseMotion` at node's screen position. Triggers `mouse_entered` / `_gui_input` on intervening Controls. |
| `loc.get_property(prop)` | (deserialized) | Same semantics as `game.get_property`. Sub-property paths like `"position:x"` supported. |
| `loc.set_property(prop, value)` | `None` | Same semantics as `game.set_property`. Python type wrappers auto-serialized. |
| `loc.call(method, args=None)` | (deserialized) | Same semantics as `game.call`. |
| `loc.wait_visible(*, timeout=5.0)` | `None` | Block until target passes actionability checks. Identical checks to `click()` auto-wait. Raises `NotActionableError` with structured `reasons` (list of: `"not_visible_in_tree"`, `"mouse_filter_ignore"`, `"outside_viewport"`, `"unclickable_node_type"`) and `checks` (per-check booleans). |
| `loc.wait_for_signal(signal_name, timeout=5.0)` | `list` | Signal arguments. Raises `TimeoutError`, `CommandError` (signal doesn't exist). |
All action methods raise `MultipleMatchesError` (with `paths` attribute)
when query matches multiple nodes without `.first()` / `.nth()` /
`.filter()`, and `NodeNotFoundError` when zero match (except
`.all()`, `.exists()`, `.count()`).
### Resolution Semantics
- Each action method re-runs the full query against the live scene tree immediately before executing. This keeps Locators valid across `reload_scene()` and tree mutations.
- `filter(**kwargs)` predicates AND with primary query.
- Chained Locators (`.locator(**kwargs)`): parent resolved at action time; parent resolution errors propagate (not swallowed like `.all()`).
### Examples
```python
# Single button by visible text
game.get_by_button("Start").click()
# Player by group
player = game.locator(group="player")
expect(player).to_have_property("health", 100)
# Multiple enemies with explicit indexing
enemies = game.locator(group="enemies").all()
for enemy in enemies:
enemy.call("take_damage", [10])
# Disambiguate with filter
game.locator(type="Button").filter(text="OK").click()
# Sub-query — find a specific child by name within the player
overlay = game.locator(group="player").locator(name="HealthBar")
```
---
## expect() — Auto-Retry Assertions
Playwright-style polling assertions over a Locator. Each matcher
polls until it passes or times out.
### Constructor
```python
expect(
locator: Locator,
*,
timeout: float = 5.0,
poll_interval: float = 0.05,
) -> LocatorAssertions
```
| Parameter | Default | Notes |
|---|---|---|
| `locator` | required | Re-resolved on every poll. |
| `timeout` | `5.0` | Seconds. Validates `>= 0`. |
| `poll_interval` | `0.05` | Seconds between polls (50 ms). Validates `> 0`. |
**Raises**: `TypeError` (locator is not a `Locator`), `ValueError` (invalid timeout / poll_interval).
### Matchers
All return `None` on success. Raise `ExpectationFailedError` on timeout.
| Matcher | Signature | Passes When |
|---|---|---|
| `to_have_property(name, value)` | — | `locator.get_property(name) == value`. |
| `to_have_text(text)` | — | Target's `text` property equals `text`. Sugar for `to_have_property("text", text)`. Works on `Label`, `Button`, `LineEdit`, `RichTextLabel`, etc. (all expose under same name). |
| `to_be_visible()` | — | Target visible in scene tree (Control / Node2D). For `Node3D` / `Window` / `Node`, use `to_satisfy(lambda l: l.get_property("visible"))`. |
| `to_exist()` | — | Locator's query resolves to ≥1 node. Does not require exactly one match. |
| `to_satisfy(predicate, *, description=None)` | predicate: `Callable[[Locator], Any]` | `predicate(locator)` returns truthy. Lookup errors inside predicate (`NodeNotFoundError`, `MultipleMatchesError`, `CommandError`) are caught and treated as "not yet satisfied". Use `description=` for human-readable failure messages (else `repr(predicate)` is used — useless for lambdas). |
### Polling Error Handling
| Exception during poll | Behavior |
|---|---|
| `NodeNotFoundError` | Caught, loop keeps polling (node may appear later). |
| `MultipleMatchesError` | Caught, loop keeps polling. |
| `CommandError` | Caught, stashed as `last_error` for failure message; loop keeps polling. |
| Other exceptions | Propagate immediately (real bugs, not transient states). |
### ExpectationFailedError Attributes
```python
class ExpectationFailedError(GodotE2EError, AssertionError):
actual: Any # last observed value (None if never observed)
observation_captured: bool # True if at least one poll succeeded
matcher: str # e.g., "to_have_text('Ready')"
scene_tree: dict | None # depth-4 dump of /root at failure time; None on dump failure
timeout: float # the timeout that was exceeded, in seconds
last_error: Exception | None # last CommandError swallowed during polling, if any
logs: list[LogEntry] # via GodotE2EError base
```
**Dual-inheritance**: Inherits both `GodotE2EError` and `AssertionError`,
so pytest renders it as a regular assertion failure (in the assertion
section of the report, not as a generic exception traceback).
### Examples
```python
from godot_e2e import expect
# Property equality
expect(game.locator(group="player")).to_have_property("health", 100)
# Text assertion with shorter timeout
expect(game.locator(name="StatusLabel"), timeout=2.0).to_have_text("Ready")
# Visibility
expect(game.locator(name="GameOverPanel")).to_be_visible()
# Existence (≥1 match — count NOT required to be 1)
expect(game.locator(group="enemies")).to_exist()
# Custom predicate with description
expect(game.locator(group="player")).to_satisfy(
lambda l: l.get_property("position:x") > 500.0,
description="player crossed x=500",
)
```
---
## Engine Log Capture
A Godot-side `Logger` subclass intercepts engine log events
(`push_error`, `push_warning`, runtime errors, shader errors) plus
optional `print()` / `printerr()` at info verbosity. Events are
returned in every command's response under `_logs`, parsed into
`LogEntry` objects by the Python client.
### LogEntry
```python
@dataclass
class LogEntry:
level: str # "error" | "warning" | "info" | "stderr"
message: str
function: str # populated only for engine errors (_log_error callback)
file: str # populated only for engine errors
line: int # populated only for engine errors
```
| Field | Populated When |
|---|---|
| `level` | always |
| `message` | always |
| `function` | engine errors only (empty for `info` / `stderr`) |
| `file` | engine errors only (empty for `info` / `stderr`) |
| `line` | engine errors only (0 for `info` / `stderr`) |
`LogEntry.__str__()` renders as `[LEVEL] message (file:line)` for use
in failure reports.
### LogVerbosity
```python
from godot_e2e import LogVerbosity
LogVerbosity.ERROR # "error" — only push_error / runtime / shader errors
LogVerbosity.WARNING # "warning" — + push_warning [DEFAULT]
LogVerbosity.INFO # "info" — + print() / printerr()
```
### Properties / Methods
| Member | Description |
|---|---|
| `game.last_logs -> list[LogEntry]` | Engine log entries captured during the most recent command. Cleared on each new command. |
| `game.collected_logs -> list[LogEntry]` | All entries since last reset. Pytest fixtures reset at test entry, so under standard `game` / `game_fresh` fixtures this list reflects the current test only (including its scene reload). On test failure, appended to pytest report under `captured godot logs` section alongside `captured stdout` / `captured stderr`. |
| `game.reset_collected_logs()` | Discard `collected_logs` and `last_logs`. Pytest fixtures call automatically; manual use only when scoping a sub-assertion to a narrower window. |
| `game.set_log_verbosity(level: str)` | Adjust capture verbosity at runtime. `level` ∈ `"error"`, `"warning"`, `"info"`. Raises `CommandError` for invalid values. |
| `game.set_log_buffer_size(size: int)` | Resize ring buffer at runtime. Default 200. Raises `ValueError` (Python boundary) if `size < 1`; `CommandError` (wire boundary) for other invalid values. Use to raise for high-error-density debug sessions where entries drop, or shrink to validate overflow handling. |
| `parse_log_entries(raw: list) -> list[LogEntry]` | Convert raw `_logs` array (as it arrives on the wire) into list. Exposed for callers bypassing the high-level API. |
### Startup Configuration
| Flag / Kwarg | Default | Notes |
|---|---|---|
| `--e2e-log-verbosity=<level>` (CLI) | `"warning"` | Set at Godot startup. Passed via `GodotLauncher.launch()`. |
| `log_verbosity=<level>` (`GodotE2E.launch()` kwarg) | `None` (defers to addon default) | Validated and raises `ValueError` before subprocess starts. |
### Buffer Overflow
When the ring buffer overflows between drains (more entries emitted
than buffer size allows), the response carries a `_logs_dropped`
count. The Python client synthesizes a single warning entry with
message `"<N log entries dropped due to capture buffer overflow>"`
and appends it uniformly to:
- `last_logs`
- `collected_logs`
- Any raised exception's `.logs`
### Exception Log Attachment
Every `GodotE2EError` subclass has a `.logs` attribute (list of
`LogEntry`) populated from the failing command's `_logs` payload.
Empty list when log capture inactive.
### Example
```python
from godot_e2e import GodotE2E, expect
with GodotE2E.launch("./my_project", log_verbosity="info") as game:
game.wait_for_node("/root/Main", timeout=10.0)
# Run game logic
game.get_by_button("Start").click()
expect(game.locator(name="Status")).to_have_text("Playing")
# Assert no errors during the click
errors = [e for e in game.collected_logs if e.level == "error"]
assert not errors, f"errors during click: {[str(e) for e in errors]}"
# Narrow to a single command
game.reset_collected_logs()
game.call("/root/Main", "trigger_dangerous_thing")
assert any(e.message == "expected warning" for e in game.last_logs), \
f"missing expected warning; got: {game.last_logs}"
```
---
## Node Operations
### node_exists(path) -> bool
Check if a node exists in the scene tree.
```python
game.node_exists("/root/Main/Player") # True or False
```
### get_property(path, property) -> value
Get a node property. Supports Godot's colon-separated sub-property notation.
| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `str` | Absolute node path: `"/root/Main/Player"` |
| `property` | `str` | Property name. Use `:` for sub-properties: `"position:x"` |
**Returns**: Deserialized Python value (float, str, Vector2, etc.).
**Raises**: `NodeNotFoundError`, `CommandError` (property doesn't exist).
```python
pos = game.get_property("/root/Main/Player", "position") # Vector2
x = game.get_property("/root/Main/Player", "position:x") # float
text = game.get_property("/root/Main/Label", "text") # str
visible = game.get_property("/root/Main/Menu", "visible") # bool
health = game.get_property("/root/Main/Player", "health") # int
```
### set_property(path, property, value)
Set a property on a node. Use godot-e2e type classes for Godot types.
```python
from godot_e2e import Vector2
game.set_property("/root/Main/Player", "position", Vector2(100.0, 200.0))
game.set_property("/root/Main/Player", "position:x", 500.0)
game.set_property("/root/Main", "score", 0)
game.set_property("/root/Main/Label", "text", "Hello")
```
### call(path, method, args=None) -> value
Call a GDScript method on a node.
| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `str` | Node path |
| `method` | `str` | Method name |
| `args` | `list` | Arguments list (each is serialized) |
```python
result = game.call("/root/Main", "get_counter") # No args
game.call("/root/Main", "add_to_counter", [5]) # With args
game.call("/root/Main", "reset_level", [True, 3]) # Multiple args
```
### find_by_group(group) -> list[str]
Find all nodes in a Godot group. Returns list of absolute path strings.
```python
enemies = game.find_by_group("enemies")
# ["/root/Main/Enemy1", "/root/Main/Enemy2"]
```
### query_nodes(pattern="", group="") -> list[str]
Query nodes by glob pattern (`*`, `?` wildcards), group, or both.
**Note**: For new code, prefer `game.locator(...)` — Locator wraps
this with a richer query DSL and re-resolution.
```python
game.query_nodes(pattern="Enemy*") # All nodes named Enemy*
game.query_nodes(group="enemies") # All in "enemies" group
game.query_nodes(pattern="Boss*", group="enemies") # Bosses in enemies group
```
### get_tree(path="/root", depth=4) -> dict
Scene tree snapshot as nested dict. Keys: `name`, `type`, `path`, `children`.
```python
tree = game.get_tree("/root/Main", depth=2)
# {"name": "Main", "type": "Node2D", "path": "/root/Main",
# "children": [
# {"name": "Player", "type": "CharacterBody2D", ...},
# {"name": "Label", "type": "Label", ...}
# ]}
```
---
## Input Simulation
All input commands are **deferred**: the server injects the input event,
waits 2 physics frames for Godot to process it, then responds.
### input_action(action_name, pressed, strength=1.0)
Simulate a named input action (defined in Godot's Input Map).
**Most reliable method** — focus-independent. Use for all gameplay actions.
**Limitation**: Does NOT drive `Input.get_axis()` / `Input.get_vector()`.
If game code uses these, use `input_key()` instead.
```python
game.input_action("ui_right", True) # press
game.input_action("ui_right", False) # release
game.input_action("jump", True, strength=0.5) # partial strength
```
### input_key(keycode, pressed, physical=False)
Simulate a keyboard key event. Goes through Godot's full input pipeline
(`_input`, `_unhandled_input`, action mapping). **DOES drive `Input.get_axis()`**.
| Parameter | Type | Description |
|-----------|------|-------------|
| `keycode` | `int` | Godot key constant (e.g., `4194321` = KEY_RIGHT) |
| `pressed` | `bool` | True for key-down, False for key-up |
| `physical` | `bool` | If True, sets physical_keycode (layout-independent) |
Common Godot keycodes (decimal):
- KEY_LEFT: 4194319, KEY_RIGHT: 4194321, KEY_UP: 4194320, KEY_DOWN: 4194322
- KEY_SPACE: 32, KEY_ENTER: 4194309, KEY_ESCAPE: 4194305
- KEY_A: 65, KEY_D: 68, KEY_W: 87, KEY_S: 83
### input_mouse_button(x, y, button=1, pressed=True)
Mouse button at screen coordinates. Button: 1=left, 2=right, 3=middle.
### input_mouse_motion(x, y, relative_x=0, relative_y=0)
Mouse motion event at screen position with optional relative movement.
---
## High-Level Input Helpers
Convenience wrappers that handle press + release automatically.
### press_action(action_name, strength=1.0)
Press and immediately release a named action. Equivalent to:
`input_action(action, True)` then `input_action(action, False)`.
Total wait: 4 physics frames (2 per input_action call).
**Use for taps/clicks, NOT for held movement.** For held input, use
`input_action(name, True)` → `wait_physics_frames(N)` → `input_action(name, False)`.
### press_key(keycode)
Press and release a key. Equivalent to two `input_key` calls.
### click(x, y, button=1)
Click at screen coordinates. Mouse down + wait + mouse up.
### click_node(path)
Click at a node's screen position. The server computes coordinates:
- **Control nodes**: center of `get_global_rect()`
- **Node2D nodes**: viewport-transformed global position
```python
game.click_node("/root/Menu/StartButton") # Click the button
```
**Raises**: `NodeNotFoundError`, `CommandError` (unsupported node type).
**For new code, prefer `Locator.click()`** — it auto-waits actionability
(visible + mouse_filter + in viewport) and surfaces structured failure
reasons via `NotActionableError`.
---
## Frame Synchronization
### wait_process_frames(count=1)
Wait N `_process` (render) frames. Use for UI animations, `_process` logic.
### wait_physics_frames(count=1)
Wait N `_physics_process` frames. **Use for movement, collision, physics.**
### wait_seconds(seconds)
Wait N in-game seconds. Affected by `Engine.time_scale`.
Timeout parameters use wall-clock time (NOT affected by time_scale).
---
## Synchronization
### wait_for_node(path, timeout=5.0)
Block until node exists. Polls every process frame on the Godot side (fast).
**Raises**: `TimeoutError` with `.scene_tree` attribute containing a tree dump.
```python
game.wait_for_node("/root/Level2", timeout=10.0)
```
### wait_for_signal(path, signal_name, timeout=5.0)
Wait for a signal to emit. Returns list of signal arguments.
**IMPORTANT**: Only catches signals emitted AFTER the command is received.
For state changes triggered by actions, prefer `expect(locator).to_have_property(...)`.
```python
args = game.wait_for_signal("/root/Main", "level_complete", timeout=10.0)
```
### wait_for_property(path, property, value, timeout=5.0)
Poll until property equals expected value. Polls on Godot side (fast, no
network round-trips per poll).
**For new code, prefer `expect(locator).to_have_property(...)`** — it
adds Locator re-resolution and richer failure context. Use this only
when working with hardcoded paths and the assertion is downstream of
non-Locator code.
```python
game.wait_for_property("/root/Main", "score", 10, timeout=5.0)
```
---
## Scene Management
### get_scene() -> str
Returns current scene's `res://` path.
### change_scene(scene_path)
Change to a new scene. **Blocks until new scene is loaded and ready.**
```python
game.change_scene("res://levels/level2.tscn")
# No need for wait_for_node — change_scene already waits
```
### reload_scene()
Reload the current scene. **Blocks until reloaded.** Primary test isolation
mechanism — resets all scene state.
---
## Screenshot
### screenshot(save_path="") -> str
Capture viewport to PNG. Returns absolute file path.
If `save_path` is empty, saves to `user://e2e_screenshots/<timestamp>.png`.
The built-in pytest fixtures auto-capture on test failure to `test_output/`.
---
## Batch Operations
### batch(commands) -> list
Execute multiple **instant** commands in one TCP round-trip.
Each command is either a dict with `"action"` key, or a tuple of
`(action, params_dict)`.
**Deferred commands (input, waits) are NOT supported in batch** — they return
an error entry.
```python
results = game.batch([
("get_property", {"path": "/root/Main/Player", "property": "position:x"}),
("get_property", {"path": "/root/Main/Player", "property": "position:y"}),
("get_property", {"path": "/root/Main", "property": "score"}),
{"action": "node_exists", "path": "/root/Main/Enemy"},
])
x, y, score, enemy_exists = results
```
---
## Types
`from godot_e2e import Vector2, Vector2i, Vector3, Vector3i, Rect2, Rect2i, Color, Transform2D, NodePath`
All are Python dataclasses mirroring Godot types. Used for `set_property`
values and returned by `get_property`.
| Type | Wire Tag | Fields |
|------|----------|--------|
| `Vector2(x, y)` | `"v2"` | `float, float` |
| `Vector2i(x, y)` | `"v2i"` | `int, int` |
| `Vector3(x, y, z)` | `"v3"` | `float, float, float` |
| `Vector3i(x, y, z)` | `"v3i"` | `int, int, int` |
| `Rect2(x, y, w, h)` | `"r2"` | `float, float, float, float` |
| `Rect2i(x, y, w, h)` | `"r2i"` | `int, int, int, int` |
| `Color(r, g, b, a=1.0)` | `"col"` | `float, float, float, float` |
| `Transform2D(x, y, origin)` | `"t2d"` | `Vector2, Vector2, Vector2` |
| `NodePath(path)` | `"np"` | `str` |
Wire protocol uses `_t` type tags for lossless JSON round-trip.
Unsupported Godot types become `{"_t": "_unknown", "_class": "...", "_str": "..."}`.
---
## Exceptions
All inherit from `GodotE2EError`. **Every instance carries `.logs`**
(list of `LogEntry`) populated from the failing command's response.
```python
from godot_e2e import (
GodotE2EError,
NodeNotFoundError,
TimeoutError,
ConnectionLostError,
CommandError,
MultipleMatchesError,
NotActionableError,
ExpectationFailedError,
)
```
### NodeNotFoundError
Node path doesn't exist in scene tree.
Raised by: `get_property`, `set_property`, `call`, `click_node`,
`wait_for_signal`, Locator actions.
### TimeoutError
Wait operation exceeded timeout. Has `.scene_tree` attribute (dict or None)
with a tree dump captured at timeout.
```python
try:
game.wait_for_node("/root/Missing", timeout=2.0)
except TimeoutError as e:
print(e.scene_tree) # Shows what nodes DO exist
```
### ConnectionLostError
Godot process crashed or TCP connection dropped. Raised by any command.
### CommandError
Server returned an error (unknown command, bad property, failed method call).
### MultipleMatchesError
Locator action matched multiple nodes without `.first()` / `.nth()` /
`.filter()` to disambiguate.
| Attribute | Type | Description |
|---|---|---|
| `paths` | `list[str]` | All matching node paths. |
```python
try:
game.locator(type="Button").click()
except MultipleMatchesError as e:
print(f"matched {len(e.paths)} buttons: {e.paths}")
# Disambiguate:
game.locator(type="Button").filter(text="OK").click()
```
### NotActionableError
`Locator.click()` or `Locator.wait_visible()` timed out waiting for
the target to become actionable.
| Attribute | Type | Description |
|---|---|---|
| `path` | `str` | Resolved node path. |
| `reasons` | `list[str]` | Failed checks, drawn from: `"not_visible_in_tree"`, `"mouse_filter_ignore"`, `"outside_viewport"`, `"unclickable_node_type"`. |
| `checks` | `dict[str, bool]` | Per-check booleans for full visibility into actionability state. |
### ExpectationFailedError
Raised by `expect(locator).to_*` matchers on timeout. Dual-inherits
`GodotE2EError` and `AssertionError`, so pytest renders it as a
regular assertion failure.
| Attribute | Type | Description |
|---|---|---|
| `actual` | `Any` | Last observed value (or `None` if never observed). |
| `observation_captured` | `bool` | True if at least one poll succeeded and returned a value. |
| `matcher` | `str` | Human-readable matcher name (e.g., `"to_have_text('Ready')"`). |
| `scene_tree` | `dict \| None` | Depth-4 dump of `/root` at failure time; `None` on dump failure. |
| `timeout` | `float` | The timeout that was exceeded, in seconds. |
| `last_error` | `Exception \| None` | Last `CommandError` swallowed during polling, if any. |
---
## GodotClient
`from godot_e2e import GodotClient`
Low-level TCP client. You normally use `GodotE2E` instead.
- `GodotClient(host, port)` — constructor
- `connect(timeout=10.0)` — open TCP connection
- `close()` — close connection
- `hello(token)` — send handshake
- `send_command(action, **params)` — send command and block for response
---
## GodotLauncher
`from godot_e2e import GodotLauncher`
Process manager. Used internally by `GodotE2E.launch()`.
- `launch(project_path, godot_path, port, timeout, extra_args, log_verbosity=None)` — start Godot, return connected client
- `kill()` — gracefully shut down Godot (quit command → terminate → kill)
The launcher:
1. Finds Godot binary
2. If `port=0` (default), creates a temporary port file and passes
`--e2e-port=0 --e2e-port-file=<path>` so Godot auto-selects a free port
and writes it to the file. This avoids TOCTOU race conditions and enables
multiple parallel instances.
3. Generates random authentication token
4. Starts Godot with `--e2e`, `--e2e-port=N`, `--e2e-token=X`,
`--e2e-port-file` (when auto-allocating), and
`--e2e-log-verbosity=<level>` (when `log_verbosity` is set)
5. Reads actual port from port file (if auto-allocated), then polls until
TCP connection + handshake succeeds
Validates `log_verbosity` and raises `ValueError` before subprocess starts
for invalid values.
---
## pytest Fixtures
The `godot_e2e.fixtures` module registers as a pytest plugin via
`pytest11` entry point — fixtures available in any test without
`pytest_plugins` declaration.
### Built-in `game` fixture (function scope)
Backed by a module-scoped Godot process. Reloads scene before each test.
Auto-resets `collected_logs` at test entry. Auto-captures screenshot on
test failure to `test_output/<test_name>_failure.png`.
Project path resolution order:
1. `@pytest.mark.godot_project("path")` marker
2. `godot_e2e_project_path` in pytest config (`pytest.ini` / `pyproject.toml`)
3. `GODOT_E2E_PROJECT_PATH` env var
4. Auto-detection of `project.godot` in `./godot_project`, `../godot_project`, `.`
### Built-in `game_fresh` fixture (function scope)
Fresh Godot process per test. Maximum isolation, slowest. Same auto-reset
and auto-screenshot behavior.
### Pytest report integration
On test failure, the plugin appends `collected_logs` under the
`captured godot logs` section of the report — alongside `captured stdout`
and `captured stderr`. No setup required.
### Custom fixtures (recommended for pipeline)
Write your own `conftest.py` for full control:
```python
import os
import pytest
from godot_e2e import GodotE2E
GODOT_PROJECT = os.path.join(os.path.dirname(__file__), "..", "godot_project")
GODOT_CONFIG = os.path.join(GODOT_PROJECT, ".claude", "godotmaker.yaml")
def _read_godot_path():
try:
with open(GODOT_CONFIG, "r", encoding="utf-8") as f:
for line in f:
line = line.split("#", 1)[0].strip()
if line.startswith("godot_path:"):
value = line.split(":", 1)[1].strip().strip("\"'")
return value or None
except OSError:
return None
return None
GODOT_PATH = _read_godot_path()
@pytest.fixture(scope="module")
def _game_process():
with GodotE2E.launch(
GODOT_PROJECT,
godot_path=GODOT_PATH,
timeout=15.0,
) as game:
game.wait_for_node("/root/Main", timeout=10.0)
yield game
@pytest.fixture(scope="function")
def game(_game_process):
_game_process.reload_scene()
_game_process.wait_for_node("/root/Main", timeout=5.0)
yield _game_process
```
---
## Godot Addon Setup
### Files to copy
Copy `addons/godot_e2e/` into your Godot project. It contains:
| File | Purpose |
|------|---------|
| `plugin.gd` | EditorPlugin: auto-registers `AutomationServer` autoload |
| `plugin.cfg` | Addon metadata |
| `automation_server.gd` | Autoload: TCP server + state machine |
| `command_handler.gd` | Command dispatch + execution |
| `json_serializer.gd` | GDScript <-> JSON type conversion |
| `config.gd` | CLI flag parser (`--e2e`, `--e2e-port`, etc.) |
| `logger.gd` | `Logger` subclass for engine log capture |
### Plugin registration
Enable in **Project > Project Settings > Plugins** — check the **GodotE2E** entry.
The plugin automatically adds `AutomationServer` as an autoload (no
manual `project.godot` edit needed).
### CLI flags (passed after `--` separator)
| Flag | Description |
|------|-------------|
| `--e2e` | Enable automation server. Required. |
| `--e2e-port=N` | TCP port (default: 6008). Use `0` for auto-selection. |
| `--e2e-port-file=PATH` | Write actual port to this file. Used with `--e2e-port=0` for parallel instances. |
| `--e2e-token=X` | Auth token (must match client). |
| `--e2e-log` | Verbose **server-side wire log** to stdout (separate from engine log capture — this logs request/response on Godot side). |
| `--e2e-log-verbosity=<level>` | Engine log capture verbosity at startup. `"error"` / `"warning"` / `"info"`. |
The launcher passes these automatically. For manual launch:
```bash
godot --path ./project -- --e2e --e2e-port=6008 --e2e-log --e2e-log-verbosity=info
```
### Zero production impact
The AutomationServer checks `--e2e` in `_ready()`. Without it:
- No TCP server is created
- `set_process(false)` + `set_physics_process(false)`
- Zero runtime overhead
---
## Wire Protocol Summary
Every response includes a `_logs` array (empty if log capture inactive
or no logs emitted). The Python client parses this into `LogEntry`
objects and populates `last_logs`, `collected_logs`, and exception
`.logs` attributes.
### Locator-related commands
| Command | Params | Response | Notes |
|---|---|---|---|
| `find_nodes` | `query: dict` (with `by`, `value`, optional `filters`), `start_path: str` | `{"nodes": [...], "_logs": [...]}` | Multi-strategy node lookup. Backs all `Locator` queries. |
| `node_actionable` | `path: str` | `{"actionable": bool, "checks": {"visible": bool, "mouse_filter": bool, "in_viewport": bool}, "reasons": [<failed_checks>], "_logs": [...]}` | Snapshot of node actionability. |
| `hover_node` | `path: str` | (deferred) | Inject `InputEventMouseMotion` at node's screen position. |
### Log capture commands
| Command | Params | Response | Notes |
|---|---|---|---|
| `set_log_verbosity` | `level: str` | (empty dict + `_logs`) | Runtime verbosity adjustment. |
| `set_log_buffer_size` | `size: int` | (empty dict + `_logs`) | Runtime ring buffer resize. |
### Direct-path commands
| Command | Params | Notes |
|---|---|---|
| `get_property` / `set_property` / `call` / `node_exists` / `find_by_group` / `query_nodes` / `get_tree` / `batch` | (see sections above) | Instant. |
| `click_node` | `path: str` | Deferred. Used by `Locator.click()`. |
| `input_action` / `input_key` / `input_mouse_button` / `input_mouse_motion` | (see Input Simulation) | Deferred. |
| `wait_for_node` / `wait_for_signal` / `wait_for_property` / `wait_physics_frames` / `wait_process_frames` / `wait_seconds` | (see Synchronization) | Deferred. |
| `change_scene` / `reload_scene` / `get_scene` | (see Scene Management) | Deferred (scene loads), instant (`get_scene`). |
| `screenshot` | `save_path: str` | Instant. |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |