godot-e2e

godot-e2e — E2E Testing for Godot

$ARGUMENTS

godot-e2e is a custom framework with zero LLM training data coverage. Everything the model needs is in this skill (with deeper detail in references/). Do not guess — follow these docs exactly.

Architecture

The godot-e2e CLI launches a Godot process and communicates over TCP (localhost). Enabling the GodotE2E plugin in Project Settings auto-registers an AutomationServer autoload that receives JSON commands, executes them on the main thread, and sends back results. The game runs unmodified — the server is dormant unless launched with --e2e. Multiple instances can run in parallel (each auto-allocates a unique port). The framework rests on three pillars: Locator for semantic node queries, expect() for auto-retry assertions, and engine log capture so every error carries the Godot logs that preceded it.

Quick Start — conftest.py + Test File

# conftest.py (per test directory — explicit project path control;
# alternatively set GODOT_E2E_PROJECT_PATH env or pytest.ini
# `godot_e2e_project_path` and use the auto-registered `game` fixture).
# Replace "/root/Main" below with your project's entry-scene root —
# read it from `project.godot`'s `run/main_scene`.
import os

import pytest
from godot_e2e import GodotE2E

GODOT_PROJECT = os.path.join(os.path.dirname(__file__), "..")
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

# test_player.py
from godot_e2e import expect

def test_player_moves_right(game):
    player = game.locator(group="player")          # Locator query
    initial_x = player.get_property("position:x")

    game.input_action("ui_right", True)
    game.wait_physics_frames(10)
    game.input_action("ui_right", False)

    expect(player).to_satisfy(
        lambda l: l.get_property("position:x") > initial_x,
        description="player moved right",
    )

def test_button_starts_game(game):
    game.get_by_button("Start").click()           # auto-waits actionability
    expect(game.locator(name="GameStatus")).to_have_text("Playing")
    errors = [e for e in game.collected_logs if e.level == "error"]
    assert not errors, f"errors during click: {errors}"

godot-e2e e2e/ -v

API Quick Reference

Launch / Lifecycle

Locator — Semantic Queries

Locator is lazy: queries re-resolve on every action, so a Locator created before reload_scene() still works after.

expect() — Auto-Retry Assertions

expect(locator, *, timeout=5.0, poll_interval=0.05) → LocatorAssertions re-resolves the Locator on each poll. Lookup errors during polling (NodeNotFoundError, MultipleMatchesError, CommandError) are caught; node may appear / disambiguate later.

ExpectationFailedError dual-inherits AssertionError → pytest renders it as a regular assertion failure, with attributes actual, observation_captured, matcher, scene_tree, last_error.

Engine Log Capture

Pytest auto-includes captured godot logs section on failure (built-in plugin, no setup required). Buffer overflow synthesizes a "<N entries dropped>" warning.

Raw-Path Operations

Direct on game — used when you have a stable known path and a Locator query would just add ceremony (typically root-level singletons, autoloads, the Main entry node). Node ops (game.get_property / set_property / call / find_by_group / query_nodes / get_tree / batch), input (input_action / input_key / input_mouse_* / press_action / press_key / click / click_node), waits (wait_physics_frames / wait_process_frames / wait_seconds / wait_for_node / wait_for_signal / wait_for_property), scenes (get_scene / change_scene / reload_scene / screenshot).

Types & Exceptions

from godot_e2e import (
    Vector2, Vector2i, Vector3, Vector3i, Rect2, Rect2i,
    Color, Transform2D, NodePath,
    LogEntry, LogVerbosity, parse_log_entries,
    expect, Locator, LocatorAssertions,
)

All inherit from GodotE2EError (which carries .logs).

Critical Rules

Fixture Strategies

The pytest plugin auto-registers game (reload-based) and game_fresh (process-per-test) — both reset collected_logs at test entry and capture screenshots on failure to test_output/.

Running & Debugging

godot-e2e e2e/ -v                                  # all tests
godot-e2e e2e/test_player.py -v                    # single file
godot-e2e --godot-path /path/to/godot tests/ -v    # specific binary

• Engine log verbosity at launch: GodotE2E.launch(path, log_verbosity="info") or --e2e-log-verbosity=info flag
• Server-side wire log: extra_args=["--e2e-log"] (separate from engine log capture — this logs request/response traffic on the Godot side)
• TimeoutError diagnosis: exception has .scene_tree
• Locator actionability diagnosis: NotActionableError.reasons lists failed checks ("not_visible_in_tree", "mouse_filter_ignore", "outside_viewport", "unclickable_node_type")
• expect() failure context: ExpectationFailedError.actual (last observed value) + .scene_tree + .last_error (last swallowed CommandError)

E2E Test Quality Standards

Every E2E test MUST meet these minimum requirements. Tests that fail these criteria are rejected.

Minimum Per-Test Requirements

1. At least 1 user action — input_action, press_action, click, Locator.click(), or call that triggers gameplay
2. At least 1 state-change assertion — verify a property CHANGED (not just that a node exists). Prefer expect(...) matchers over manual assert get_property(...) == X.
3. No pure existence tests — node_exists / Locator.exists() may serve as a precondition, but NEVER as the only assertion

Bad vs Good Examples

# BAD — only checks existence, proves nothing about gameplay:
def test_player(game):
    assert game.locator(group="player").exists()

# GOOD — verifies actual gameplay behavior with auto-retry:
def test_player_moves_right(game):
    player = game.locator(group="player")
    initial_x = player.get_property("position:x")
    game.input_action("move_right", True)
    game.wait_physics_frames(10)
    game.input_action("move_right", False)
    expect(player).to_satisfy(
        lambda l: l.get_property("position:x") > initial_x,
        description="player moved right",
    )

Fixture Sync Rules

1. Entry scene change → update conftest.py: change wait_for_node path, add change_scene if needed
2. Entity naming change → if helpers used hardcoded paths, update; if they used Locators with group= / type= / text=, often no change needed
3. New game state (e.g., menu before gameplay) → create a game_playing fixture that navigates past menus to gameplay state
4. Private → public methods → E2E game.call() / Locator.call() cannot call _private() methods; any method called by E2E must be public
5. After ANY structural change → run godot-e2e e2e/ -v to catch broken fixtures immediately

Extended References

For full API details (every Locator method, every matcher's polling semantics, all wire commands, full exception attribute lists, type serialization tags): → Grep references/api-reference.md

For testing patterns (Locator-based UI recipes, expect() idioms, log-driven diagnosis, keep-alive, pause handling, CI config, flaky test mitigation): → Grep references/testing-patterns.md