Fix: Migrate tests to GdUnit4

.githooks/pre-push

@@ -112,7 +112,7 @@ echo ""
 echo "🎮 [4/4] Godot Script Parse Check..."
 if command -v "$GODOT_BIN" &>/dev/null; then
     "$GODOT_BIN" --headless --editor --quit --path . 2>&1 | tee tools/godot_lint.log
-    if grep -iE "SCRIPT ERROR|Parse Error|Compile Error|hides an autoload singleton|SHADER ERROR" tools/godot_lint.log; then
+    if ! python3 tools/filter_godot_errors.py tools/godot_lint.log; then
         echo ""
         echo "  ❌ Godot reported script/shader errors. Fix before pushing."
         exit 1

.github/pull_request_template.md

@@ -4,8 +4,7 @@ Please ensure all items are checked before submitting this PR for review.
 
 ## 1. Automated Testing
 - [ ] **Deterministic Math Validation**: Run `python3 tests/validate_math.py`.
-- [ ] **In-Engine Math Validation**: Run `godot --script tests/test_deterministic_math.gd --headless`.
-- [ ] **Full Test Suite**: Run `bash tests/run_all_tests.sh`.
+- [ ] **Full Test Suite**: Run `bash tools/pre_push_check.sh` (which executes GdUnit4 tests).
 
 ## 2. Pre-Commit Hooks
 - [ ] **GDScript Format**: Run `gdformat scripts/ tests/ ui/`.

.github/workflows/ci.yml

@@ -1,5 +1,9 @@
 name: CI
 
+permissions:
+  contents: read
+  checks: write
+  pull-requests: write
 on:
   push:
     branches: [main]
@@ -79,28 +83,25 @@ jobs:
         run: |
           mkdir -p tools
           godot --headless --editor --quit --path . 2>&1 | tee tools/godot_lint.log
-          if grep -iE "SCRIPT ERROR|Parse Error|Compile Error|hides an autoload singleton" tools/godot_lint.log; then
+          if ! python3 tools/filter_godot_errors.py tools/godot_lint.log; then
             echo "❌ GDScript linting failed."
             exit 1
           fi
           echo "✅ GDScript lint passed."
-      - name: Run Full Test Suite
-        run: |
-          chmod +x tests/run_all_tests.sh
-          tests/run_all_tests.sh 2>&1 | tee tests/test_output.log
+      - name: Run GdUnit4 Tests
+        uses: MikeSchulze/gdUnit4-action@v1
+        with:
+          godot-version: '4.2.2'
+          version: 'v4.4.3'
+          paths: 'res://tests'
+          publish-report: true
+          report-name: 'gdUnit4-report'
       - name: Upload Test Results
         uses: actions/upload-artifact@v7
         if: always()
         with:
           name: test-results
           path: |
-            tests/test_output.log
-            tests/validate_math_report.json
             tools/godot_lint.log
-      - name: Report Test Summary
-        if: always()
-        run: |
-          echo "### Test Results" >> $GITHUB_STEP_SUMMARY
-          echo '```' >> $GITHUB_STEP_SUMMARY
-          tail -20 tests/test_output.log >> $GITHUB_STEP_SUMMARY
-          echo '```' >> $GITHUB_STEP_SUMMARY
+            tests/validate_math_report.json
+

.github/workflows/release.yml

@@ -43,9 +43,10 @@ jobs:
       - name: Regenerate asset cache
         run: godot --headless --import --path .
       - name: Run Godot test suites
-        run: |
-          chmod +x tests/run_all_tests.sh
-          tests/run_all_tests.sh
+        uses: MikeSchulze/gdUnit4-action@v1
+        with:
+          godot-version: '4.2.2'
+          paths: 'res://tests'
 
       - name: Export Windows build
         run: |

AGENTS.md

@@ -198,8 +198,8 @@ CombatRoom (Node2D)
 ## Testing Commands
 
 ```bash
-# Run all tests
-bash tests/run_all_tests.sh
+# Run all tests via GdUnit4
+godot --headless --path . -s res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a tests/ --ignoreHeadlessMode
 
 # Run specific test
 godot --headless --path . -s tests/test_entity_lifecycle.gd
@@ -312,7 +312,7 @@ GitHub Actions (`.github/workflows/ci.yml`) runs **exactly the same checks** as
 |---|---|
 | `gdscript-format` | `gdformat`, `markdownlint`, and `json.tool` |
 | `validate-math` | `python3 tests/validate_math.py` |
-| `gdscript-lint` | Godot headless editor scan + `tests/run_all_tests.sh` |
+| `gdscript-lint` | Godot headless editor scan + GdUnit4 test suite |
 
 > **CI uses `--check` only (no auto-fix).** Auto-fixing happens locally via hooks.
 > If CI fails on formatting, it means the pre-push hook was bypassed — run `bash tools/setup_hooks.sh` to re-install hooks.
@@ -347,8 +347,7 @@ GitHub Actions (`.github/workflows/ci.yml`) runs **exactly the same checks** as
 
 1. Create `tests/test_feature.gd`
 2. Use strict typing throughout
-3. Include in `tests/run_all_tests.sh`
-4. Run `bash tests/run_all_tests.sh` to verify
+3. Run `godot --headless --path . -s res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a tests/test_feature.gd` to verify
 
 ### Debugging Tips
 

CONTRIBUTING.md

@@ -127,11 +127,11 @@ func _config_int(key: String, fallback: int) -> int:
 ## Running Tests
 
 ```bash
-# Full test suite (mirrors CI)
-bash tests/run_all_tests.sh
+# Full test suite via GdUnit4 (mirrors CI)
+godot --headless --path . -s res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a tests/ --ignoreHeadlessMode
 
 # Single test file
-godot --headless --path . -s tests/test_deterministic_math.gd
+godot --headless --path . -s res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a tests/test_deterministic_math.gd
 
 # Python cross-platform math validator
 python3 tests/validate_math.py
@@ -148,11 +148,10 @@ bash tools/pre_push_check.sh
 ## Adding a Test
 
 1. Create `tests/test_<feature>.gd`.
-2. Use `extends SceneTree` (with `_initialize()`) for standalone tests.
+2. Use `extends GdUnitTestSuite`.
 3. Use strict typing throughout.
-4. Exit with `quit(0)` (pass) or `quit(1)` (fail).
-5. Add it to `tests/run_all_tests.sh`.
-6. Run the full suite to confirm no regressions.
+4. Use `assert_that()` for assertions.
+5. Run the suite locally or headlessly to confirm no regressions.
 
 ---
 

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.

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")

addons/gdUnit4/bin/GdUnitCmdTool.gd.uid

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

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

addons/gdUnit4/bin/GdUnitCopyLog.gd.uid

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

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-rc1"
+script="plugin.gd"