Add gdUnit4 for game-based unit testing

.github/actions/godot-env/action.yml

@@ -19,6 +19,9 @@ outputs:
   godot-template-url:
     description: The link to the `.tpz` archive of export templates that was generated.
     value: ${{ steps.variables.outputs.godot-template-url }}
+  godot-version:
+    description: The version of Godot
+    value: ${{ inputs.godot-version }}${{ inputs.godot-version-type != 'stable' && format('-{0}', inputs.godot-version-type) || '' }}
   godot-api-version:
     description: The api_version to send to godot-cpp
     value: ${{ steps.variables.outputs.godot-api-version }}

.github/workflows/builds.yml

@@ -23,6 +23,7 @@ jobs:
       sources-changed: ${{ steps.changed-files.outputs.sources_any_changed }}
       godot-executable-url: ${{ steps.godot-env.outputs.godot-linux-url }}
       godot-templates-url: ${{ steps.godot-env.outputs.godot-template-url }}
+      godot-version: ${{ steps.godot-env.outputs.godot-version }}
       godot-api-version: ${{ steps.godot-env.outputs.godot-api-version }}
     steps:
       - name: Checkout project
@@ -105,6 +106,35 @@ jobs:
           cd ..
           git diff --color --exit-code -- '*.xml' && ! git ls-files --others --exclude-standard | sed -e 's/^/New doc file missing in PR: /' | grep 'xml$'
 
+  godot-unit-tests:
+    runs-on: ubuntu-latest
+    needs: [static-checks-builds, build-master]
+    name: 🧪 Run gdUnit4 unit tests
+    steps:
+      - name: Checkout project
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          submodules: recursive
+          fetch-depth: 0 # Treeless clone. Slightly less performant than a shallow clone, but makes finding diffs instantaneous.
+          filter: tree:0 # See: https://github.blog/open-source/git/get-up-to-speed-with-partial-clone-and-shallow-clone/
+          persist-credentials: false
+
+      - name: Download artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          path: game/bin/openvic
+          pattern: ${{ github.event.repository.name }}-*-extension
+          merge-multiple: true
+
+      - name: Run unit tests
+        uses: godot-gdunit-labs/gdUnit4-action@17eeffa988f9732fdc3dba3067405d16b55809de # v1.3.2
+        with:
+          version: installed
+          godot-version: ${{ needs.static-checks-builds.outputs.godot-version }}
+          paths: 'res://tests'
+          project_dir: './game/'
+          arguments: ${{ runner.debug && '--verbose' || '' }}
+
   export-master:
     runs-on: ubuntu-latest
     needs:  [static-checks-builds, build-master]
@@ -150,11 +180,11 @@ jobs:
   validate-master:
     name: ✅ Validate Success
     if: always()
-    needs: [static-checks-builds, build-master, godot-debug-checks, export-master, merge-library-files]
+    needs: [static-checks-builds, build-master, godot-debug-checks, godot-unit-tests, export-master, merge-library-files]
     runs-on: Ubuntu-latest
     steps:
       - name: Check
         uses: re-actors/alls-green@a638d6464689bbb24c325bb3fe9404d63a913030
         with:
-          allowed-skips: static-checks-builds, build-master, godot-debug-checks, export-master, merge-library-files
+          allowed-skips: static-checks-builds, build-master, godot-debug-checks, godot-unit-tests, export-master, merge-library-files
           jobs: ${{ toJson(needs) }}

COPYRIGHT

@@ -55,6 +55,11 @@ Comment: Quick Licenses Godot Plugin
 Copyright: 2025 ProgrammerOnCoffee
 License: MIT
 
+Files: game/addons/gdUnit4/*
+Comment: gdUnit4 Godot Plugin
+Copyright: 2023 Mike Schulze
+License: MIT
+
 Files: game/assets/audio/music/*.mp3
 Comment: OpenVic Game music
 Copyright: 2023-present Catylist

game/addons/gdUnit4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Mike Schulze
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

game/addons/gdUnit4/bin/GdUnitCmdTool.gd

@@ -0,0 +1,21 @@
+#!/usr/bin/env -S godot -s
+extends SceneTree
+
+
+var _cli_runner: GdUnitTestCIRunner
+
+
+func _initialize() -> void:
+	DisplayServer.window_set_mode(DisplayServer.WINDOW_MODE_MINIMIZED)
+	_cli_runner = GdUnitTestCIRunner.new()
+	root.add_child(_cli_runner)
+
+
+# do not use print statements on _finalize it results in random crashes
+func _finalize() -> void:
+	queue_delete(_cli_runner)
+	if OS.is_stdout_verbose():
+		prints("Finallize ..")
+		prints("-Orphan nodes report-----------------------")
+		Window.print_orphan_nodes()
+		prints("Finallize .. done")

game/addons/gdUnit4/bin/GdUnitCmdTool.gd.uid

@@ -0,0 +1 @@
+uid://e0xnhqp4qd01

game/addons/gdUnit4/bin/GdUnitCopyLog.gd

@@ -0,0 +1,167 @@
+#!/usr/bin/env -S godot -s
+extends MainLoop
+
+const GdUnitTools := preload("res://addons/gdUnit4/src/core/GdUnitTools.gd")
+
+# gdlint: disable=max-line-length
+const LOG_FRAME_TEMPLATE = """
+<!DOCTYPE html>
+<html style="display: inline-grid;">
+<head>
+	<meta charset="UTF-8">
+	<meta name="viewport" content="width=device-width, initial-scale=1.0">
+	<title>Godot Logging</title>
+	<link rel="stylesheet" href="css/styles.css">
+</head>
+
+<body style="background-color: #eee;">
+	<div class="godot-report-frame"">
+${content}
+	</div>
+</body>
+</html>
+"""
+
+const NO_LOG_MESSAGE = """
+<h3>No logging available!</h3>
+</br>
+<p>In order for logging to take place, you must activate the Activate file logging option in the project settings.</p>
+<p>You can enable the logging under:
+<b>Project Settings</b> > <b>Debug</b> > <b>File Logging</b> > <b>Enable File Logging</b> in the project settings.</p>
+"""
+
+#warning-ignore-all:return_value_discarded
+var _cmd_options := CmdOptions.new([
+		CmdOption.new(
+			"-rd, --report-directory",
+			"-rd <directory>",
+			"Specifies the output directory in which the reports are to be written. The default is res://reports/.",
+			TYPE_STRING,
+			true
+		)
+	])
+
+
+var _report_root_path: String
+var _current_report_path: String
+var _debug_cmd_args := PackedStringArray()
+
+
+func _init() -> void:
+	set_report_directory(GdUnitFileAccess.current_dir() + "reports")
+	set_current_report_path()
+
+
+func _process(_delta: float) -> bool:
+	# check if reports exists
+	if not reports_available():
+		prints("no reports found")
+		return true
+
+	# only process if godot logging is enabled
+	if not GdUnitSettings.is_log_enabled():
+		write_report(NO_LOG_MESSAGE, "")
+		return true
+
+	# parse possible custom report path,
+	var cmd_parser := CmdArgumentParser.new(_cmd_options, "GdUnitCmdTool.gd")
+	# ignore erros and exit quitly
+	if cmd_parser.parse(get_cmdline_args(), true).is_error():
+		return true
+	CmdCommandHandler.new(_cmd_options).register_cb("-rd", set_report_directory)
+
+	var godot_log_file := scan_latest_godot_log()
+	var result := read_log_file_content(godot_log_file)
+	if result.is_error():
+		write_report(result.error_message(), godot_log_file)
+		return true
+	write_report(result.value_as_string(), godot_log_file)
+	return true
+
+
+func set_current_report_path() -> void:
+	# scan for latest report directory
+	var iteration := GdUnitFileAccess.find_last_path_index(
+		_report_root_path, GdUnitConstants.REPORT_DIR_PREFIX
+	)
+	_current_report_path = "%s/%s%d" % [_report_root_path, GdUnitConstants.REPORT_DIR_PREFIX, iteration]
+
+
+func set_report_directory(path: String) -> void:
+	_report_root_path = path
+
+
+func get_log_report_html() -> String:
+	return _current_report_path + "/godot_report_log.html"
+
+
+func reports_available() -> bool:
+	return DirAccess.dir_exists_absolute(_report_root_path)
+
+
+func scan_latest_godot_log() -> String:
+	var path := GdUnitSettings.get_log_path().get_base_dir()
+	var files_sorted := Array()
+	for file in GdUnitFileAccess.scan_dir(path):
+		var file_name := "%s/%s" % [path, file]
+		files_sorted.append(file_name)
+	# sort by name, the name contains the timestamp so we sort at the end by timestamp
+	files_sorted.sort()
+	return files_sorted.back()
+
+
+func read_log_file_content(log_file: String) -> GdUnitResult:
+	var file := FileAccess.open(log_file, FileAccess.READ)
+	if file == null:
+		return GdUnitResult.error(
+			"Can't find log file '%s'. Error: %s"
+			% [log_file, error_string(FileAccess.get_open_error())]
+		)
+	var content := "<pre>" + file.get_as_text()
+	# patch out console format codes
+	for color_index in range(0, 256):
+		var to_replace := "[38;5;%dm" % color_index
+		content = content.replace(to_replace, "")
+	content += "</pre>"
+	content = content\
+		.replace("", "")\
+		.replace(GdUnitCSIMessageWriter.CSI_BOLD, "")\
+		.replace(GdUnitCSIMessageWriter.CSI_ITALIC, "")\
+		.replace(GdUnitCSIMessageWriter.CSI_UNDERLINE, "")
+	return GdUnitResult.success(content)
+
+
+func write_report(content: String, godot_log_file: String) -> GdUnitResult:
+	var file := FileAccess.open(get_log_report_html(), FileAccess.WRITE)
+	if file == null:
+		return GdUnitResult.error(
+			"Can't open to write '%s'. Error: %s"
+			% [get_log_report_html(), error_string(FileAccess.get_open_error())]
+		)
+	var report_html := LOG_FRAME_TEMPLATE.replace("${content}", content)
+	file.store_string(report_html)
+	_update_index_html(godot_log_file)
+	return GdUnitResult.success(file)
+
+
+func _update_index_html(godot_log_file: String) -> void:
+	var index_path := "%s/index.html" % _current_report_path
+	var index_file := FileAccess.open(index_path, FileAccess.READ_WRITE)
+	if index_file == null:
+		push_error(
+			"Can't add log path '%s' to `%s`. Error: %s"
+			% [godot_log_file, index_path, error_string(FileAccess.get_open_error())]
+		)
+		return
+	var content := index_file.get_as_text()\
+		.replace("${log_report}", get_log_report_html())\
+		.replace("${godot_log_file}", godot_log_file)
+	# overide it
+	index_file.seek(0)
+	index_file.store_string(content)
+
+
+func get_cmdline_args() -> PackedStringArray:
+	if _debug_cmd_args.is_empty():
+		return OS.get_cmdline_args()
+	return _debug_cmd_args

game/addons/gdUnit4/bin/GdUnitCopyLog.gd.uid

@@ -0,0 +1 @@
+uid://bkjlnuuoocm44

game/addons/gdUnit4/plugin.cfg

@@ -0,0 +1,7 @@
+[plugin]
+
+name="gdUnit4"
+description="Unit Testing Framework for Godot Scripts"
+author="Mike Schulze"
+version="6.2.0-rc2"
+script="plugin.gd"

game/addons/gdUnit4/plugin.gd

@@ -0,0 +1,95 @@
+@tool
+extends EditorPlugin
+
+var _gd_inspector: Control
+var _gd_console: Control
+var _filesystem_context_menu: EditorContextMenuPlugin
+var _editor_context_menu: EditorContextMenuPlugin
+var _editor_code_context_menu: EditorContextMenuPlugin
+
+
+func _enter_tree() -> void:
+	if not ClassDB.class_exists(&"GdUnitSettings"):
+		return
+
+	var inferred_declaration := GdUnitSettings.validate_is_inferred_declaration_enabled()
+	if inferred_declaration.is_error():
+		printerr(inferred_declaration.error_message())
+		printerr("Loading GdUnit4 Plugin failed.")
+		return
+
+	if check_running_in_test_env():
+		@warning_ignore("return_value_discarded")
+		GdUnitCSIMessageWriter.new().prints_warning("It was recognized that GdUnit4 is running in a test environment, therefore the GdUnit4 plugin will not be executed!")
+		return
+
+	if Engine.get_version_info().hex < 0x40500:
+		prints("This GdUnit4 plugin version '%s' requires Godot version '4.5' or higher to run." % GdUnit4Version.current())
+		return
+	GdUnitSettings.setup()
+	GdUnitEditorColorTheme.setup()
+	# Install the GdUnit Inspector
+	_gd_inspector = (load("res://addons/gdUnit4/src/ui/GdUnitInspector.tscn") as PackedScene).instantiate()
+	_add_context_menus()
+	add_control_to_dock(EditorPlugin.DOCK_SLOT_LEFT_UR, _gd_inspector)
+	# Install the GdUnit Console
+	_gd_console = (load("res://addons/gdUnit4/src/ui/GdUnitConsole.tscn") as PackedScene).instantiate()
+	var control: Control = add_control_to_bottom_panel(_gd_console, "gdUnitConsole")
+	@warning_ignore("unsafe_method_access")
+	await _gd_console.setup_update_notification(control)
+	if GdUnit4CSharpApiLoader.is_api_loaded():
+		prints("GdUnit4Net version '%s' loaded." % GdUnit4CSharpApiLoader.version())
+	else:
+		prints("No GdUnit4Net found.")
+	# Connect to be notified for script changes to be able to discover new tests
+	GdUnitTestDiscoverGuard.instance()
+	@warning_ignore("return_value_discarded")
+	resource_saved.connect(_on_resource_saved)
+	prints("Loading GdUnit4 Plugin success")
+
+
+func _exit_tree() -> void:
+	if not ClassDB.class_exists(&"GdUnitSettings"):
+		return
+	if check_running_in_test_env():
+		return
+	if is_instance_valid(_gd_inspector):
+		remove_control_from_docks(_gd_inspector)
+		_gd_inspector.free()
+	_remove_context_menus()
+	if is_instance_valid(_gd_console):
+		remove_control_from_bottom_panel(_gd_console)
+		_gd_console.free()
+	var gdUnitTools: GDScript = load("res://addons/gdUnit4/src/core/GdUnitTools.gd")
+	@warning_ignore("unsafe_method_access")
+	gdUnitTools.dispose_all(true)
+	prints("Unload GdUnit4 Plugin success")
+
+
+func check_running_in_test_env() -> bool:
+	var args: PackedStringArray = OS.get_cmdline_args()
+	args.append_array(OS.get_cmdline_user_args())
+	return DisplayServer.get_name() == "headless" or args.has("--selftest") or args.has("--add") or args.has("-a") or args.has("--quit-after") or args.has("--import")
+
+
+func _add_context_menus() -> void:
+	_filesystem_context_menu = preload("res://addons/gdUnit4/src/ui/menu/GdUnitEditorFileSystemContextMenuHandler.gd").new()
+	_editor_context_menu = preload("res://addons/gdUnit4/src/ui/menu/GdUnitScriptEditorContextMenuHandler.gd").new()
+	_editor_code_context_menu = preload("res://addons/gdUnit4/src/ui/menu/GdUnitScriptEditorContextMenuHandler.gd").new()
+	add_context_menu_plugin(EditorContextMenuPlugin.CONTEXT_SLOT_FILESYSTEM, _filesystem_context_menu)
+	add_context_menu_plugin(EditorContextMenuPlugin.CONTEXT_SLOT_SCRIPT_EDITOR, _editor_context_menu)
+	add_context_menu_plugin(EditorContextMenuPlugin.CONTEXT_SLOT_SCRIPT_EDITOR_CODE, _editor_code_context_menu)
+
+
+func _remove_context_menus() -> void:
+	if is_instance_valid(_filesystem_context_menu):
+		remove_context_menu_plugin(_filesystem_context_menu)
+	if is_instance_valid(_editor_context_menu):
+		remove_context_menu_plugin(_editor_context_menu)
+	if is_instance_valid(_editor_code_context_menu):
+		remove_context_menu_plugin(_editor_code_context_menu)
+
+
+func _on_resource_saved(resource: Resource) -> void:
+	if resource is Script:
+		await GdUnitTestDiscoverGuard.instance().discover(resource as Script)