Godot Skill

Develop, test, build, and deploy Godot 4.x games.

Quick Reference

GdUnit4 - Unit testing framework (GDScript, runs inside Godot)

godot --headless --path . -s res://addons/gdUnit4/bin/GdUnitCmdTool.gd --run-tests

PlayGodot - Game automation framework (Python, like Playwright for games)

export GODOT_PATH=/path/to/godot-automation-fork pytest tests/ -v

Export web build

godot --headless --export-release "Web" ./build/index.html

Deploy to Vercel

vercel deploy ./build --prod

Testing Overview

GdUnit4 PlayGodot

Type Unit testing Game automation

Language GDScript Python

Runs Inside Godot External (like Playwright)

Requires Addon Custom Godot fork

Best for Unit/component tests E2E/integration tests

GdUnit4 (GDScript Tests)

GdUnit4 runs tests written in GDScript directly inside Godot.

Project Structure

project/ ├── addons/gdUnit4/ # GdUnit4 addon ├── test/ # Test directory │ ├── game_test.gd │ └── player_test.gd └── scripts/ └── game.gd

Setup

Install GdUnit4

git clone --depth 1 https://github.com/MikeSchulze/gdUnit4.git addons/gdUnit4

Enable plugin in Project Settings → Plugins

Basic Unit Test

test/game_test.gd

extends GdUnitTestSuite

var game: Node

func before_test() -> void: game = auto_free(load("res://scripts/game.gd").new())

func test_initial_state() -> void: assert_that(game.is_game_active()).is_true() assert_that(game.get_current_player()).is_equal("X")

func test_make_move() -> void: var success := game.make_move(4) assert_that(success).is_true() assert_that(game.get_board_state()[4]).is_equal("X")

Scene Test with Input Simulation

test/game_scene_test.gd

extends GdUnitTestSuite

var runner: GdUnitSceneRunner

func before_test() -> void: runner = scene_runner("res://scenes/main.tscn")

func after_test() -> void: runner.free()

func test_click_cell() -> void: await runner.await_idle_frame()

var cell = runner.find_child("Cell4")
runner.set_mouse_position(cell.global_position + cell.size / 2)
runner.simulate_mouse_button_pressed(MOUSE_BUTTON_LEFT)
await runner.await_input_processed()

var game = runner.scene()
assert_that(game.get_board_state()[4]).is_equal("X")

func test_keyboard_restart() -> void: runner.simulate_key_pressed(KEY_R) await runner.await_input_processed() assert_that(runner.scene().is_game_active()).is_true()

Running GdUnit4 Tests

All tests

godot --headless --path . -s res://addons/gdUnit4/bin/GdUnitCmdTool.gd --run-tests

Specific test file

godot --headless --path . -s res://addons/gdUnit4/bin/GdUnitCmdTool.gd
--run-tests --add res://test/my_test.gd

Generate reports for CI

godot --headless --path . -s res://addons/gdUnit4/bin/GdUnitCmdTool.gd
--run-tests --report-directory ./reports

GdUnit4 Assertions

Values

assert_that(value).is_equal(expected) assert_that(value).is_not_null() assert_that(condition).is_true()

Numbers

assert_that(number).is_greater(5) assert_that(number).is_between(1, 100)

Strings

assert_that(text).contains("expected") assert_that(text).starts_with("prefix")

Arrays

assert_that(array).contains(element) assert_that(array).has_size(5)

Signals

await assert_signal(node).is_emitted("signal_name")

Scene Runner Input API

Mouse

runner.set_mouse_position(Vector2(100, 100)) runner.simulate_mouse_button_pressed(MOUSE_BUTTON_LEFT) runner.simulate_mouse_button_released(MOUSE_BUTTON_LEFT)

Keyboard

runner.simulate_key_pressed(KEY_SPACE) runner.simulate_key_pressed(KEY_S, false, true) # Ctrl+S

Input actions

runner.simulate_action_pressed("jump") runner.simulate_action_released("jump")

Waiting

await runner.await_input_processed() await runner.await_idle_frame() await runner.await_signal("game_over", [], 5000)

PlayGodot (Game Automation)

PlayGodot is a game automation framework for Godot - like Playwright, but for games. It enables E2E testing, automated gameplay, and external control of Godot games via the native RemoteDebugger protocol.

Requirements:

• Custom Godot fork: Randroids-Dojo/godot (automation branch)

• PlayGodot Python library

Setup

Install PlayGodot

python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install playgodot

Option 1: Download pre-built binary (recommended)

See releases: https://github.com/Randroids-Dojo/godot/releases/tag/automation-latest

- godot-automation-linux-x86_64.zip

- godot-automation-macos-universal.zip (Intel + Apple Silicon)

Option 2: Build custom Godot fork from source

git clone https://github.com/Randroids-Dojo/godot.git cd godot && git checkout automation scons platform=macos arch=arm64 target=editor -j8 # macOS Apple Silicon

scons platform=macos arch=x86_64 target=editor -j8 # macOS Intel

scons platform=linuxbsd target=editor -j8 # Linux

scons platform=windows target=editor -j8 # Windows

Test Configuration (conftest.py)

import os import pytest_asyncio from pathlib import Path from playgodot import Godot

GODOT_PROJECT = Path(file).parent.parent GODOT_PATH = os.environ.get("GODOT_PATH", "/path/to/godot-fork")

@pytest_asyncio.fixture async def game(): async with Godot.launch( str(GODOT_PROJECT), headless=True, timeout=15.0, godot_path=GODOT_PATH, ) as g: await g.wait_for_node("/root/Game") yield g

Writing PlayGodot Tests

import pytest

GAME = "/root/Game"

@pytest.mark.asyncio async def test_game_starts_empty(game): board = await game.call(GAME, "get_board_state") assert board == ["", "", "", "", "", "", "", "", ""]

@pytest.mark.asyncio async def test_clicking_cell(game): await game.click("/root/Game/VBoxContainer/GameBoard/GridContainer/Cell4") board = await game.call(GAME, "get_board_state") assert board[4] == "X"

@pytest.mark.asyncio async def test_game_win(game): for pos in [0, 3, 1, 4, 2]: # X wins top row await game.call(GAME, "make_move", [pos])

is_active = await game.call(GAME, "is_game_active")
assert is_active is False

Running PlayGodot Tests

export GODOT_PATH=/path/to/godot-automation-fork pytest tests/ -v pytest tests/test_game.py::test_clicking_cell -v

PlayGodot API

Node interaction

node = await game.get_node("/root/Game") await game.wait_for_node("/root/Game", timeout=10.0) exists = await game.node_exists("/root/Game") result = await game.call("/root/Node", "method", [arg1, arg2]) value = await game.get_property("/root/Node", "property") await game.set_property("/root/Node", "property", value)

Node queries

paths = await game.query_nodes("Button") count = await game.count_nodes("Label")

Mouse input

await game.click("/root/Button") await game.click(300, 200) await game.double_click("/root/Button") await game.right_click(100, 100) await game.drag("/root/Item", "/root/Slot")

Keyboard input

await game.press_key("space") await game.press_key("ctrl+s") await game.type_text("hello")

Input actions

await game.press_action("jump") await game.hold_action("sprint", 2.0)

Touch input

await game.tap(300, 200) await game.swipe(100, 100, 400, 100) await game.pinch((200, 200), 0.5)

Screenshots

png_bytes = await game.screenshot() await game.screenshot("/tmp/screenshot.png") similarity = await game.compare_screenshot("expected.png") await game.assert_screenshot("reference.png", threshold=0.99)

Scene management

scene = await game.get_current_scene() await game.change_scene("res://scenes/level2.tscn") await game.reload_scene()

Game state

await game.pause() await game.unpause() is_paused = await game.is_paused() await game.set_time_scale(0.5) scale = await game.get_time_scale()

Waiting

await game.wait_for_node("/root/Game/SpawnedEnemy", timeout=5.0) await game.wait_for_visible("/root/Game/UI/GameOverPanel", timeout=10.0) await game.wait_for_signal("game_over") await game.wait_for_signal("health_changed", source="/root/Game/Player")

Building & Deployment

Web Export

Requires export_presets.cfg with Web preset

godot --headless --export-release "Web" ./build/index.html

Export Preset (export_presets.cfg)

[preset.0] name="Web" platform="Web" runnable=true export_path="build/index.html"

Deploy to Vercel

npm i -g vercel vercel deploy ./build --prod

CI/CD

GitHub Actions Example

• name: Setup Godot uses: chickensoft-games/setup-godot@v2 with: version: 4.3.0 include-templates: true

• name: Run GdUnit4 Tests run: | godot --headless --path .
  -s res://addons/gdUnit4/bin/GdUnitCmdTool.gd
  --run-tests --report-directory ./reports

• name: Upload Results uses: actions/upload-artifact@v4 if: always() with: name: test-results path: reports/

References

• references/gdunit4-quickstart.md

• GdUnit4 setup

• references/scene-runner.md

• Input simulation API

• references/assertions.md

• Assertion methods

• references/playgodot.md

• PlayGodot guide

• references/deployment.md

• Deployment guide

• references/ci-integration.md

• CI/CD setup