StagTest

Experimental: Fairly solidified, but changes may be made as seen fit.

Inherits: Node

Singleton for handling unit and integration tests.

Properties

Dictionary[String, String]	args
Callable	_quit_function	_quit_default
StagLogger	_logger
Dictionary[String, Variant]	statistics	{...}
Dictionary[String, Variant]	test_data_default	{...}
Dictionary	test_data	<unknown>
Dictionary	_benchmarks	Dictionary()
Dictionary	_reports_benchmarks	Dictionary()
float	_time_scale_base	1.0
String	_reports_path	"res://test/reports/"
PackedStringArray	tests	[]
PackedStringArray	test_failures	[]
PackedStringArray	_test_suffixes	[]
int	test_idx	0
String	active_path	""
bool	force_exiting	false
bool	test_resulted	false
bool	in_test	false
Array[StagTest.TickTimer]	_tick_timers_process	[]
Array[StagTest.TickTimer]	_tick_timers_physics_process	[]
Mutex	_tick_timers_process_mu	<unknown>
Mutex	_tick_timers_physics_process_mu	<unknown>

Methods

void	_init()
void	_ready()
void	_exit_tree()
void	_begin(test_root: String)
String	_join_path(directory: String, relpath: String)
void	_print_rich(msg: String)
void	_display_post_test_message()
void	_walk_directory(dirpath: String)
void	_run_test(filepath: String)
void	_cleanup_test()
void	_finish_test()
void	_results()
void	_exit(status: int = 0)
void	_timeout(timeout: float)
void	_force_exit(reason: String)
void	_pass_test_if_not_failed()
bool	_has_failed()
Variant	_format_assertion_message(message: String)
String	_format_assertion_value(val: Variant)
String	_format_duration(t: float)
void	_add_report(reports_list: Dictionary, new_report: Variant, label: String)
void	_output_reports()
int	_ensure_directory(filepath: String)
void	_quit_default(status: int)
void	_process(_delta: float)
void	_physics_process(_delta: float)
void	_catch_error(message: String)
void	override_exit_function(new_quit: Callable)
bool	is_active()
String	path()
void	pause(paused: bool)
void	time_scale(new_scale: float = _time_scale_base)
void	teardown()
void	skip(reason: String)
void	fail(reason: String)
void	assert_true(value: bool, message: String = “”)
void	assert_equal(a: Variant, b: Variant, message: String = “”)
void	assert_unequal(a: Variant, b: Variant, message: String = “”)
void	assert_valid(a: Object, message: String = “”)
void	assert_approx_equal(a: Variant, b: Variant, message: String = “”)
void	assert_in_delta(a: Variant, b: Variant, delta: float = 1e-05, message: String = “”)
StagTest.SignalExpector	signal_expector(emitter: Signal, message: String = “”)
Signal	tick_timer_process(ticks: int)
Signal	tick_timer_physics_process(ticks: int)
StagTest.BenchmarkResult	benchmark(f: Callable, count: int, label: String, timeout: float = -1.0)

---

Signals

test_post_ready() 🔗

Called just after beginning a test.

---

tick_process() 🔗

Emitted at the beginning of each process tick during the test.

---

tick_physics_process() 🔗

Emitted at the beginning of each physics process tick during the test.

---

internal_tick_process_list_ready() 🔗

There is currently no description for this signal. Please help us by contributing one!

---

internal_tick_physics_process_list_ready() 🔗

There is currently no description for this signal. Please help us by contributing one!

---

test_pre_exit() 🔗

Called just before exiting a test.

---

Enumerations

enum ExitCodes: 🔗

ExitCodes Ok = 0

There is currently no description for this enum. Please help us by contributing one!

ExitCodes Failed = 1

There is currently no description for this enum. Please help us by contributing one!

ExitCodes BadFile = 15

There is currently no description for this enum. Please help us by contributing one!

---

Constants

DEFAULT_TEST_PATH = "res://test/scenarios/" 🔗

There is currently no description for this constant. Please help us by contributing one!

DEFAULT_BENCHMARK_PATH = "res://test/benchmarks/" 🔗

There is currently no description for this constant. Please help us by contributing one!

DEFAULT_REPORTS_PATH = "res://test/reports/" 🔗

There is currently no description for this constant. Please help us by contributing one!

DEFAULT_SUFFIXES = ".tscn,.scn" 🔗

There is currently no description for this constant. Please help us by contributing one!

DEFAULT_TIMEOUT = 30.0 🔗

There is currently no description for this constant. Please help us by contributing one!

DEFAULT_TIME_SCALE = 1.0 🔗

There is currently no description for this constant. Please help us by contributing one!

---

Property Descriptions

Dictionary[String, String] args 🔗

There is currently no description for this property. Please help us by contributing one!

---

Callable _quit_function = _quit_default 🔗

There is currently no description for this property. Please help us by contributing one!

---

StagLogger _logger 🔗

There is currently no description for this property. Please help us by contributing one!

---

Dictionary[String, Variant] statistics = {...} 🔗

There is currently no description for this property. Please help us by contributing one!

---

Dictionary[String, Variant] test_data_default = {...} 🔗

There is currently no description for this property. Please help us by contributing one!

---

Dictionary test_data = <unknown> 🔗

There is currently no description for this property. Please help us by contributing one!

---

Dictionary _benchmarks = Dictionary() 🔗

There is currently no description for this property. Please help us by contributing one!

---

Dictionary _reports_benchmarks = Dictionary() 🔗

There is currently no description for this property. Please help us by contributing one!

---

float _time_scale_base = 1.0 🔗

There is currently no description for this property. Please help us by contributing one!

---

String _reports_path = "res://test/reports/" 🔗

There is currently no description for this property. Please help us by contributing one!

---

PackedStringArray tests = [] 🔗

There is currently no description for this property. Please help us by contributing one!

Note: The returned array is copied and any changes to it will not update the original property value. See PackedStringArray for more details.

---

PackedStringArray test_failures = [] 🔗

There is currently no description for this property. Please help us by contributing one!

Note: The returned array is copied and any changes to it will not update the original property value. See PackedStringArray for more details.

---

PackedStringArray _test_suffixes = [] 🔗

There is currently no description for this property. Please help us by contributing one!

Note: The returned array is copied and any changes to it will not update the original property value. See PackedStringArray for more details.

---

int test_idx = 0 🔗

There is currently no description for this property. Please help us by contributing one!

---

String active_path = "" 🔗

There is currently no description for this property. Please help us by contributing one!

---

bool force_exiting = false 🔗

There is currently no description for this property. Please help us by contributing one!

---

bool test_resulted = false 🔗

There is currently no description for this property. Please help us by contributing one!

---

bool in_test = false 🔗

There is currently no description for this property. Please help us by contributing one!

---

Array[StagTest.TickTimer] _tick_timers_process = [] 🔗

There is currently no description for this property. Please help us by contributing one!

---

Array[StagTest.TickTimer] _tick_timers_physics_process = [] 🔗

There is currently no description for this property. Please help us by contributing one!

---

Mutex _tick_timers_process_mu = <unknown> 🔗

There is currently no description for this property. Please help us by contributing one!

---

Mutex _tick_timers_physics_process_mu = <unknown> 🔗

There is currently no description for this property. Please help us by contributing one!

---

Method Descriptions

void _init() 🔗

There is currently no description for this method. Please help us by contributing one!

---

void _ready() 🔗

There is currently no description for this method. Please help us by contributing one!

---

void _exit_tree() 🔗

There is currently no description for this method. Please help us by contributing one!

---

void _begin(test_root: String) 🔗

There is currently no description for this method. Please help us by contributing one!

---

String _join_path(directory: String, relpath: String) 🔗

There is currently no description for this method. Please help us by contributing one!

---

void _print_rich(msg: String) 🔗

There is currently no description for this method. Please help us by contributing one!

---

void _display_post_test_message() 🔗

There is currently no description for this method. Please help us by contributing one!

---

void _walk_directory(dirpath: String) 🔗

There is currently no description for this method. Please help us by contributing one!

---

void _run_test(filepath: String) 🔗

There is currently no description for this method. Please help us by contributing one!

---

void _cleanup_test() 🔗

There is currently no description for this method. Please help us by contributing one!

---

void _finish_test() 🔗

There is currently no description for this method. Please help us by contributing one!

---

void _results() 🔗

There is currently no description for this method. Please help us by contributing one!

---

void _exit(status: int = 0) 🔗

There is currently no description for this method. Please help us by contributing one!

---

void _timeout(timeout: float) 🔗

There is currently no description for this method. Please help us by contributing one!

---

void _force_exit(reason: String) 🔗

There is currently no description for this method. Please help us by contributing one!

---

void _pass_test_if_not_failed() 🔗

There is currently no description for this method. Please help us by contributing one!

---

bool _has_failed() 🔗

There is currently no description for this method. Please help us by contributing one!

---

Variant _format_assertion_message(message: String) 🔗

There is currently no description for this method. Please help us by contributing one!

---

String _format_assertion_value(val: Variant) 🔗

There is currently no description for this method. Please help us by contributing one!

---

String _format_duration(t: float) 🔗

There is currently no description for this method. Please help us by contributing one!

---

void _add_report(reports_list: Dictionary, new_report: Variant, label: String) 🔗

There is currently no description for this method. Please help us by contributing one!

---

void _output_reports() 🔗

There is currently no description for this method. Please help us by contributing one!

---

int _ensure_directory(filepath: String) 🔗

There is currently no description for this method. Please help us by contributing one!

---

void _quit_default(status: int) 🔗

There is currently no description for this method. Please help us by contributing one!

---

void _process(_delta: float) 🔗

There is currently no description for this method. Please help us by contributing one!

---

void _physics_process(_delta: float) 🔗

There is currently no description for this method. Please help us by contributing one!

---

void _catch_error(message: String) 🔗

There is currently no description for this method. Please help us by contributing one!

---

void override_exit_function(new_quit: Callable) 🔗

Overrides the runtime exit function, in case the game needs additional teardown steps.

---

bool is_active() 🔗

Returns true if StagTest is testing, in case the game needs to avoid certain setup steps.

---

String path() 🔗

Returns the path of the active test.

---

void pause(paused: bool) 🔗

Sets the pause of the scene tree.

---

void time_scale(new_scale: float = _time_scale_base) 🔗

Sets the engine time scale.

---

void teardown() 🔗

Puts the test into Teardown mode. If the test is not skipped or failed during Teardown, it passes.

---

void skip(reason: String) 🔗

Puts the test into Teardown mode (if not already), skipping the remainder of the test.

---

void fail(reason: String) 🔗

Puts the test into Teardown mode (if not already), marking the test as failed.

---

void assert_true(value: bool, message: String = “”) 🔗

Assert that a given boolean is true.

---

void assert_equal(a: Variant, b: Variant, message: String = “”) 🔗

Assert that two values are equal.

---

void assert_unequal(a: Variant, b: Variant, message: String = “”) 🔗

Assert that two values are NOT equal.

---

void assert_valid(a: Object, message: String = “”) 🔗

Assert that the given instance is valid.

---

void assert_approx_equal(a: Variant, b: Variant, message: String = “”) 🔗

Assert that two values are equal within an epsilon value, that scales with magnitude.

Note: to use a specific delta threshold value, use StagTest.assert_in_delta(...) instead.

---

void assert_in_delta(a: Variant, b: Variant, delta: float = 1e-05, message: String = “”) 🔗

Assert that two values are equal, within a threshold amount. Use StagTest.assert_approx_equal() if the delta must scale with magnitude.

For floating-point vectors, the overall distance between vectors is compared. For integer vectors, Manhattan distance is used instead.

---

StagTest.SignalExpector signal_expector(emitter: Signal, message: String = “”) 🔗

Creates a StagTest.SignalExpector from the given signal, which can be used for further assertions. The StagTest.SignalExpector is thread-safe. Fails the test if the signal is null, or if the signal could not be connected.

---

Signal tick_timer_process(ticks: int) 🔗

Returns a signal that emits after the given amount of process ticks. If ticks is less than or equal to zero, the signal emits on the next process tick.

await StagTest.tick_timer_process(10) # Wait 10 ticks
# Resumes coroutine at the very beginning of tick 10 before anything else processes
StagTest.assert_equal(10, process_ticks_stagtest, "awaited 10 process ticks")
StagTest.assert_equal(9, process_ticks_node, "nodes are just about to process tick 10")

---

Signal tick_timer_physics_process(ticks: int) 🔗

Returns a signal that emits after the given amount of physics process ticks. If ticks is less than or equal to zero, the signal emits on the next physics tick.

await StagTest.tick_timer_physics_process(10) # Wait 10 ticks
# Resumes coroutine at the very beginning of tick 10 before anything else processes
StagTest.assert_equal(10, physics_ticks_stagtest, "awaited 10 process ticks")
StagTest.assert_equal(9, physics_ticks_node, "nodes are just about to process tick 10")

---

StagTest.BenchmarkResult benchmark(f: Callable, count: int, label: String, timeout: float = -1.0) 🔗

Experimental: This method may be changed or removed in future versions.

Performs a timing benchmark of the Callable (with no arguments) the specified number of times, returning an analysis.

If timeout is greater than zero, forcibly stops benchmark after X many seconds. If a test is skipped or failed during the benchmark, the benchmark exits without completing all iterations.

Results are always in microseconds, unless otherwise specified.

Use the --bench flag when running to output benchmark results.

Note: Requires the compiled Rust backend.