Mock API Reference

All functions below are available as unqualified calls when your test class extends GdTest, or as Gdt.* static calls.

For a walkthrough with context, see Mocking Dependencies.

Creating a mock

mock(SomeClass) -> Object
mock(load("res://path/to/script.gd")) -> Object

Returns a runtime double of the given class. All public methods exist on the double but do nothing. Unstubbed methods return their declared type's zero value (0, "", [], ...), or null for object and untyped methods. Use stub to override return values. Stubbed values must match the declared return type, and stubs on void methods have no effect.

var ai = mock(EnemyAI)
var ai = mock(load("res://enemy/enemy_ai.gd"))

Stubs

stub(mock_obj, "method_name", return_value)
stub_with_args(mock_obj, "method_name", [arg1, arg2], return_value)

stub sets the default return value for a method regardless of arguments.

stub_with_args sets the return value only when the method is called with arguments that exactly equal [arg1, arg2]. Calls with different arguments fall back to the plain stub value, or the unstubbed default if no plain stub is set.

stub(ai, "choose_action", "attack")
stub_with_args(ai, "choose_action", [{"hp": 10}], "retreat")

Call assertions

assert_called(mock_obj, "method_name", msg = "")
assert_not_called(mock_obj, "method_name", msg = "")
assert_call_count(mock_obj, "method_name", expected_count, msg = "")
assert_called_with(mock_obj, "method_name", [args], msg = "")

assert_called — passes if the method was called at least once.

assert_not_called — passes if the method was never called.

assert_call_count — passes if the method was called exactly expected_count times.

assert_called_with — passes if any recorded call has arguments equal to [args].

assert_called(ai, "choose_action")
assert_call_count(ai, "choose_action", 1)
assert_called_with(ai, "choose_action", [battle_state])

Inspecting calls

get_calls(mock_obj, "method_name") -> Array

Returns an Array where each element is an Array of arguments from one call.

var calls = get_calls(ai, "choose_action")
# [[{"hp": 80}], [{"hp": 10}]]  — two calls, each with one argument

assert_eq(calls[0][0]["hp"], 80)

Spies, partial mocks and autoloads

spy(real_object) -> Object         # wraps an existing instance
partial_mock(SomeClass) -> Object  # fresh instance
mock_singleton("AutoloadName") -> Object

A spy and a partial mock run the real implementation of every method and record each call. stub replaces only the methods you name, and the call assertions above work on both.

mock_singleton replaces a project autoload (a GDScript node at /root/<name>) with a mock for the current test, so code calling AutoloadName.method() reaches the mock. The real autoload is restored after after_each. Engine singletons such as Input, OS or Time are C++ objects and can't be replaced.

var audio = mock_singleton("AudioBus")
player.take_damage(10)
assert_called_with(audio, "play", ["hurt"])

Limitations

• Methods prefixed with _ are not replaced and retain their original implementation.
• static func methods are not recorded.
• Built-in Godot classes (Node, Resource, Area2D, etc.) cannot be mocked directly. Create a GDScript subclass and mock that instead:

class MockArea extends Area2D:
    pass

var area = mock(MockArea)