GD-1293: Opt-in ProjectSettings auto save/restore with explicit API (#1297)

## Why

GdUnit automatically snapshots and restores `ProjectSettings` around
every suite and test case. Most tests never touch the settings, so
backing them up only makes sense when a test actually changes one — the
direction agreed in #1293.

## What

- Adds a **Save and restore your project settings around each test
execution** setting (default **on**, non-breaking) that gates the
automatic per-suite and per-test snapshot.
- Adds `save_project_settings()` / `restore_project_settings()` so a
suite can snapshot on demand in `before()`/`before_test()` and
`after()`/`after_test()` when the automatic behaviour is turned off.
- Documents the setting and the two helpers.

The framework keeps auto save enabled by default, so existing projects
are unaffected.

Closes #1293

Author: eth0net

addons/gdUnit4/src/GdUnitTestSuite.gd

@@ -109,6 +109,28 @@ func auto_free(obj: Variant) -> Variant:
 	return execution_context.register_auto_free(obj)
 
 
+## Saves the current project settings into the active execution context.[br]
+## Useful when the "Auto Save Project Settings" setting is disabled and a test needs settings isolation on demand.[br]
+## [br]
+## Call this in [code]before()[/code]/[code]before_test()[/code] to snapshot the settings a test
+## is about to change, to restore see [method restore_project_settings].
+func save_project_settings() -> void:
+	var execution_context := GdUnitThreadManager.get_current_context().get_execution_context()
+	if execution_context == null:
+		return
+	execution_context.save_project_settings()
+
+
+## Restores the project settings previously captured by [method save_project_settings].[br]
+## [br]
+## Call this in [code]after()[/code]/[code]after_test()[/code] to undo any settings a test changed.
+func restore_project_settings() -> void:
+	var execution_context := GdUnitThreadManager.get_current_context().get_execution_context()
+	if execution_context == null:
+		return
+	execution_context.restore_project_settings()
+
+
 @warning_ignore("native_method_override")
 func add_child(node: Node, force_readable_name := false, internal := Node.INTERNAL_MODE_DISABLED) -> void:
 	super.add_child(node, force_readable_name, internal)

addons/gdUnit4/src/core/GdUnitSettings.gd

@@ -22,6 +22,7 @@ const TEST_DISCOVER_ENABLED = GROUP_TEST + "/test_discovery"
 const TEST_FLAKY_CHECK = GROUP_TEST + "/flaky_check_enable"
 const TEST_FLAKY_MAX_RETRIES = GROUP_TEST + "/flaky_max_retries"
 const TEST_RERUN_UNTIL_FAILURE_RETRIES = GROUP_TEST + "/rerun_until_failure_retries"
+const TEST_PROJECT_SETTINGS_AUTO_SAVE = GROUP_TEST + "/project_settings_auto_save"
 
 
 # Report Setiings
@@ -131,6 +132,7 @@ static func setup() -> void:
 	create_property_if_need(TEST_FLAKY_CHECK, false, "Rerun tests on failure and mark them as FLAKY")
 	create_property_if_need(TEST_FLAKY_MAX_RETRIES, 3, "Sets the number of retries for rerunning a flaky test")
 	create_property_if_need(TEST_RERUN_UNTIL_FAILURE_RETRIES, 10, "The number of reruns until the test fails.")
+	create_property_if_need(TEST_PROJECT_SETTINGS_AUTO_SAVE, true, "Save and restore your project settings around each test execution")
 	# report settings
 	create_property_if_need(REPORT_PUSH_ERRORS, false, "Report push_error() as failure")
 	create_property_if_need(REPORT_SCRIPT_ERRORS, true, "Report script errors as failure")
@@ -320,6 +322,13 @@ static func is_test_flaky_check_enabled() -> bool:
 	return get_setting(TEST_FLAKY_CHECK, false)
 
 
+## Returns whether the framework automatically saves and restores the project settings
+## around each test execution. When disabled, use [method GdUnitTestSuite.save_project_settings]
+## and [method GdUnitTestSuite.restore_project_settings] to snapshot settings on demand.
+static func is_project_settings_auto_save() -> bool:
+	return get_setting(TEST_PROJECT_SETTINGS_AUTO_SAVE, true)
+
+
 static func is_feature_enabled(feature: String) -> bool:
 	return get_setting(feature, false)
 

addons/gdUnit4/src/core/execution/stages/GdUnitTestCaseExecutionStage.gd

@@ -16,7 +16,8 @@ var _stage_fuzzer_test: IGdUnitExecutionStage = GdUnitTestCaseFuzzedExecutionSta
 func _execute(context :GdUnitExecutionContext) -> void:
 	var test_case := context.test_case
 
-	context.save_project_settings()
+	if GdUnitSettings.is_project_settings_auto_save():
+		context.save_project_settings()
 	context.error_monitor_start()
 
 	if test_case.is_fuzzed():
@@ -26,7 +27,8 @@ func _execute(context :GdUnitExecutionContext) -> void:
 
 	await context.gc()
 	context.error_monitor_stop()
-	context.restore_project_settings()
+	if GdUnitSettings.is_project_settings_auto_save():
+		context.restore_project_settings()
 
 	# finally free the test instance
 	if is_instance_valid(context.test_case):

addons/gdUnit4/src/core/execution/stages/GdUnitTestSuiteExecutionStage.gd

@@ -23,7 +23,8 @@ func _execute(context :GdUnitExecutionContext) -> void:
 		await (Engine.get_main_loop() as SceneTree).process_frame
 		@warning_ignore("return_value_discarded")
 		GdUnitMemoryObserver.guard_instance(context.test_suite.__awaiter)
-		context.save_project_settings()
+		if GdUnitSettings.is_project_settings_auto_save():
+			context.save_project_settings()
 		await _stage_before.execute(context)
 		for test_case_index in context.test_suite.get_child_count():
 			# iterate only over test cases
@@ -42,7 +43,8 @@ func _execute(context :GdUnitExecutionContext) -> void:
 				# and replace it by a clone without function state
 				context.test_suite = await clone_test_suite(context.test_suite)
 		await _stage_after.execute(context)
-		context.restore_project_settings()
+		if GdUnitSettings.is_project_settings_auto_save():
+			context.restore_project_settings()
 		GdUnitMemoryObserver.unguard_instance(context.test_suite.__awaiter)
 
 	await (Engine.get_main_loop() as SceneTree).process_frame

addons/gdUnit4/test/core/execution/GdUnitProjectSettingsAutoSaveTest.gd

@@ -0,0 +1,74 @@
+# GdUnit generated TestSuite
+class_name GdUnitProjectSettingsAutoSaveTest
+extends GdUnitTestSuite
+
+
+const __source = "res://addons/gdUnit4/src/GdUnitTestSuite.gd"
+
+const IGNORE := GdUnitSettings.GdScriptWarningMode.IGNORE
+const ERROR := GdUnitSettings.GdScriptWarningMode.ERROR
+
+const MUTATION_SUITE := "res://addons/gdUnit4/test/core/resources/testsuites/TestSuiteProjectSettingsMutation.gd"
+const PROBE_KEY := "application/config/name"
+
+
+#region auto save flag
+
+func test_is_project_settings_auto_save_defaults_true() -> void:
+	assert_bool(GdUnitSettings.is_project_settings_auto_save()).is_true()
+
+
+func test_is_project_settings_auto_save_reflects_disabled_flag() -> void:
+	var original: Variant = ProjectSettings.get_setting(GdUnitSettings.TEST_PROJECT_SETTINGS_AUTO_SAVE, true)
+	ProjectSettings.set_setting(GdUnitSettings.TEST_PROJECT_SETTINGS_AUTO_SAVE, false)
+	assert_bool(GdUnitSettings.is_project_settings_auto_save()).is_false()
+	# restore the flag so the change never leaves this test
+	ProjectSettings.set_setting(GdUnitSettings.TEST_PROJECT_SETTINGS_AUTO_SAVE, original)
+
+#endregion
+
+#region explicit save / restore
+
+func test_save_restore_isolates_setting_change() -> void:
+	var key := GdUnitSettings.GDSCRIPT_WARNINGS_INFERRED_DECLARATION
+	var original: Variant = ProjectSettings.get_setting(key, IGNORE)
+	# snapshot, mutate, restore — the mutation must not survive restore
+	save_project_settings()
+	ProjectSettings.set_setting(key, ERROR)
+	restore_project_settings()
+	assert_that(ProjectSettings.get_setting(key)).is_equal(original)
+
+#endregion
+
+#region execution stage gating
+
+# Runs a suite through the real executor in an isolated thread context with a chosen
+# auto-save flag, so the execution stages decide whether to snapshot the settings.
+func run_isolated(tests: Array[GdUnitTestCase], auto_save: bool) -> void:
+	await GdUnitThreadManager.run("auto_save_probe_%d" % randi(), func() -> void:
+		var previous: Variant = ProjectSettings.get_setting(GdUnitSettings.TEST_PROJECT_SETTINGS_AUTO_SAVE, true)
+		ProjectSettings.set_setting(GdUnitSettings.TEST_PROJECT_SETTINGS_AUTO_SAVE, auto_save)
+		var executor := GdUnitTestSuiteExecutor.new(true)
+		await get_tree().process_frame
+		await executor.run_and_wait(tests)
+		ProjectSettings.set_setting(GdUnitSettings.TEST_PROJECT_SETTINGS_AUTO_SAVE, previous)
+	)
+
+
+func test_execution_stage_snapshot_is_gated_by_flag() -> void:
+	var loaded := GdUnitTestResourceLoader.load_tests(MUTATION_SUITE)
+	var tests: Array[GdUnitTestCase] = Array(loaded.values(), TYPE_OBJECT, "RefCounted", GdUnitTestCase)
+	var original: Variant = ProjectSettings.get_setting(PROBE_KEY)
+
+	# auto save on: the stage snapshots around the test, so the mutation is rolled back
+	await run_isolated(tests, true)
+	assert_str(str(ProjectSettings.get_setting(PROBE_KEY))).is_equal(str(original))
+
+	# auto save off: the stage skips the snapshot, so the mutation leaks past the run
+	await run_isolated(tests, false)
+	assert_str(str(ProjectSettings.get_setting(PROBE_KEY))).is_equal("__auto_save_probe__")
+
+	# clean up the mutation that leaked from the off run
+	ProjectSettings.set_setting(PROBE_KEY, original)
+
+#endregion

addons/gdUnit4/test/core/resources/testsuites/TestSuiteProjectSettingsMutation.gd

@@ -0,0 +1,10 @@
+# Inner suite for GdUnitProjectSettingsAutoSaveTest.
+# A single test mutates an existing project setting. Whether the change survives the run
+# tells us whether the execution stages snapshotted around it:
+#   auto save on  -> the stage restores the setting, the mutation is gone after the run
+#   auto save off -> the stage skips the snapshot, the mutation leaks past the run
+extends GdUnitTestSuite
+
+func test_mutates_project_setting() -> void:
+	ProjectSettings.set_setting("application/config/name", "__auto_save_probe__")
+	assert_str(str(ProjectSettings.get_setting("application/config/name"))).is_equal("__auto_save_probe__")

documentation/doc/_advanced_testing/tools.md

@@ -134,6 +134,38 @@ func print_obj_usage(name :String) :
 |      UNPARENTED | [Deleted Object] | [Deleted Object] | [Deleted Object] |
 |       PREDELETE | [Deleted Object] | [Deleted Object] | [Deleted Object] |
 
+## save_project_settings() / restore_project_settings()
+
+Helpers to snapshot and restore the in-memory [`ProjectSettings`](https://docs.godotengine.org/en/stable/classes/class_projectsettings.html)
+around a test that changes them, so the change does not leak into later tests.
+
+By default GdUnit automatically saves and restores your project settings around every test execution
+(the **Auto Save Project Settings** setting). If you turn that off — for example to save time in a suite
+where almost no test touches the settings — you can snapshot on demand in just the tests that need it:
+call **save_project_settings()** in `before()`/`before_test()` and **restore_project_settings()** in
+`after()`/`after_test()`.
+
+```gd
+func save_project_settings() -> void:
+func restore_project_settings() -> void:
+```
+
+Here's a small example:
+
+```gd
+func before_test() -> void:
+    save_project_settings()
+
+func after_test() -> void:
+    restore_project_settings()
+
+func test_changes_a_setting() -> void:
+    ProjectSettings.set_setting("application/config/custom", true)
+    # the change is rolled back in after_test(), so later tests see the original value
+```
+
+---
+
 ## collect_orphan_node_details()
 
 A helper to itemize the orphan nodes detected in the current test, reporting each one's class, instance ID, and the exact

documentation/doc/_first_steps/settings.md

@@ -36,6 +36,12 @@ To access these settings, simply press the 'tools' button located in the GdUnit
     This setting configures the maximum number of times a test is rerun when using **Run Tests Until Fail** from the Inspector Context Menu.
     Once the limit is reached or a failure occurs, the run stops. The default value is **10**.
 
+  * **Auto Save Project Settings**<br>
+    When enabled (the default), GdUnit automatically saves your project settings before each test execution and restores them afterwards,
+    so a test that changes a setting cannot leak that change into later tests. Disable it to skip this snapshot when your suites rarely
+    touch the project settings, and instead snapshot on demand with `save_project_settings()` / `restore_project_settings()`
+    (see [Tools and Helpers]({{site.baseurl}}/advanced_testing/tools/)) in only the tests that need it.
+
   * **Test Discovery**<br>
    This setting configures the auto-discovery of tests. If enabled, it will scan the configured Test Root Folder for available tests at startup.
    Directories containing a `.gdignore` file are excluded from test discovery,