Release v1.2.1

Author: DAndrewBox

Docs/Documentation.md

@@ -259,7 +259,7 @@ So, the `beforeAll` function will run before all tests in the suite, the `before
 
 The `beforeEach` function is used to run a piece of code before each test in a section. This is useful when you want to set up some data before each test. You can put a `beforeEach` function in any section and it will run before each test in that section.
 
-When `describe` blocks are nested, **all ancestor `beforeEach` hooks run in order from outermost to innermost** before each test. This matches Jest/Vitest behaviour and allows shared setup to be split across describe levels.
+When `describe` blocks are nested, **all ancestor `beforeEach` hooks run in order from outermost to innermost** before each test. This matches Jest/Vitest behavior and allows shared setup to be split across describe levels.
 
 ```gml
 describe("outer", function() {
@@ -617,9 +617,12 @@ The `simulateEvent` function is used to simulate an event for an object. This fu
 
 The `simulateTimesource` function is used to simulate a [timesource](https://manual.gamemaker.io/lts/en/GameMaker_Language/GML_Reference/Time_Sources/Time_Sources.htm). This function takes the exact same parameters than a GameMaker native timesource, but it will not actually create a timesource, it will just virtually simulate the event. This is useful when you want to test pseudo-async events like a custom garbage collector or waiting some frames for an event to happen.
 
-This function creates a constructor that will be used to simulate the timesource and has 2 methods to call for it to work: `.start()` that mimics the behaviour of [time_source_start()](https://manual.gamemaker.io/lts/en/GameMaker_Language/GML_Reference/Time_Sources/time_source_start.htm), and `.stop()` that mimics the behaviour of [time_source_stop()](https://manual.gamemaker.io/lts/en/GameMaker_Language/GML_Reference/Time_Sources/time_source_stop.htm).
+This function creates a constructor that will be used to simulate the timesource and has 2 methods to call for it to work: `.start()` that mimics the behavior of [time_source_start()](https://manual.gamemaker.io/lts/en/GameMaker_Language/GML_Reference/Time_Sources/time_source_start.htm), and `.stop()` that mimics the behavior of [time_source_stop()](https://manual.gamemaker.io/lts/en/GameMaker_Language/GML_Reference/Time_Sources/time_source_stop.htm).
 
-**If you want to strictly call the GameMaker's built-in functions you can use `original_time_source_create()`, `original_time_source_start()`, etc**
+**If you want to strictly call the GameMaker's built-in functions during tests you can use `original_time_source_create()`, `original_time_source_start()`, `original_time_source_exists()`, etc**
+
+> [!IMPORTANT]
+> The library redefines `time_source_create`, `time_source_start`, `time_source_stop`, `time_source_pause`, `time_source_resume`, `time_source_destroy`, `time_source_exists` and `call_later` so they can be mocked during tests. Mocking is **only** active while your suites are actually running. Timesources created by your game or by third-party libraries (Input, Scribble, etc.) at boot or during normal gameplay hit the real GameMaker functions and behave normally. If you need the built-in behavior explicitly at any time, call the `original_` prefixed version.
 
 ### simulateCallLater ![](https://img.shields.io/badge/v1.1-00cbca?style=flat)
 

Docs/Home.md

@@ -25,15 +25,16 @@ The minimum version of GameMaker required to use this library is **GameMaker 202
 
 ❌: Not compatible.
 
-| GameMaker Version | GMTL v1.0.x | GMTL v1.1.x |
-| ----------------: | :---------: | :---------: |
-|      Studio 1.4.x |     ❌      |     ❌      |
-|    Studio 2 - 2.2 |     ❌      |     ❌      |
-|      Studio 2.3.x |     ❌      |     ❌      |
-| 2022.x & 2022 LTS |     ❌      |     ❌      |
-|   2023.1 - 2023.3 |     ⚠️      |     ❌      |
-|  2023.4 - 2023.11 |     ✅      |     ✅      |
-|          2023 LTS |     ✅      |     ✅      |
-| 2024.x / 2024 LTS |    ✅\*     |    ✅\*     |
+| GameMaker Version | GMTL v1.0.x | GMTL v1.1.x | GMTL v1.2.x |
+| ----------------: | :---------: | :---------: | :---------: |
+|      Studio 1.4.x |      ❌      |      ❌      |      ❌      |
+|    Studio 2 - 2.2 |      ❌      |      ❌      |      ❌      |
+|      Studio 2.3.x |      ❌      |      ❌      |      ❌      |
+| 2022.x & 2022 LTS |      ❌      |      ❌      |      ❌      |
+|   2023.1 - 2023.3 |      ⚠️      |      ❌      |      ❌      |
+|  2023.4 - 2023.11 |      ✅      |      ✅      |      ⚠️      |
+|          2023 LTS |      ✅      |      ✅      |      ✅      |
+| 2024.x / 2024 LTS |      ✅      |     ✅\*     |      ✅      |
+|          2026 LTS |      ✅      |      ✅      |     ✅\*     |
 
 > [!NOTE] > **Author's comment:** Depending if anyone is interested in using this library with older versions of GameMaker, I could make a version compatible up to **GameMaker Studio 2.3.7** as I did with the compatibility update in the [**GML-Extended**](https://github.com/DAndrewBox/GML-Extended/) library.

Docs/Troubleshooting.md

@@ -79,6 +79,7 @@ Also confirm your script files are not inside a folder starting with `GMTL_` - t
 ### My functions don't appear in the coverage report
 
 The scanner only indexes top-level named functions (`function name() { ... }`) defined at script scope. It skips:
+
 - Functions whose folder starts with `GMTL_` (unless whitelisted)
 - Anonymous / lambda functions
 - Constructor methods defined inside a constructor body
@@ -105,3 +106,7 @@ This issue should be solved since v1.1.0, but if you still encounter it, you can
 I'm not really sure what causes this issue, but it seems to be related to the import process of the library that GameMaker does. If you encounter this issue, please [create an issue](https://github.com/DAndrewBox/GM-Testing-Library/issues) so I can investigate it further.
 
 ---
+
+### Timesources are not working in tests or not working when created before the test suite
+
+This issue is caused by the timesources not being initialized correctly in the test environment. It was fixed in v1.2.1, I heavily recommend updating to the latest version of the library if you encounter any issues before opening a new issue.

GM-Testing-Library/scripts/GMTL_definitions/GMTL_definitions.gml

@@ -33,6 +33,7 @@
 #macro	gmtl_timesources			gmtl_internal.timesources
 #macro	gmtl_has_finished			__gmtl_internal_fn_has_finished()
 #macro	gmtl_is_initializing		__gmtl_internal_fn_is_initializing()
+#macro	gmtl_is_running				__gmtl_internal_fn_is_running()
 
 #macro	gmtl_test_before_all		gmtl_internal.tests.before_all
 #macro	gmtl_test_before_all_ran	gmtl_internal.tests.before_all_ran
@@ -129,6 +130,7 @@
 #macro	original_time_source_pause		time_source_pause
 #macro	original_time_source_resume		time_source_resume
 #macro	original_time_source_destroy	time_source_destroy
+#macro	original_time_source_exists		time_source_exists
 #macro	original_call_later				call_later
 
 #macro	time_source_create				__gmtl_internal_fn_time_source_create
@@ -137,4 +139,5 @@
 #macro	time_source_pause				__gmtl_internal_fn_time_source_pause
 #macro	time_source_resume				__gmtl_internal_fn_time_source_resume
 #macro	time_source_destroy				__gmtl_internal_fn_time_source_destroy
+#macro	time_source_exists				__gmtl_internal_fn_time_source_exists
 #macro	call_later						__gmtl_internal_fn_call_later

GM-Testing-Library/scripts/GMTL_demo_tests/GMTL_demo_tests.gml

@@ -764,3 +764,76 @@ suite(function() {
 		});
 	});
 });
+
+// Regression - timesource mocking scope
+// Guards the regression reported in the GitHub issue: timesources created by game / 3rd-party
+// code during the boot window were being silently mocked (returned unusable structs that
+// never ticked and were unknown to time_source_exists). Mocking must be scoped to the
+// window where suites are actually executing (gmtl_is_running), and time_source_exists
+// must recognize mocked timesources.
+suite(function() {
+	describe("Regression - timesource mocking is scoped to the test run", function() {
+		// Issue repro: the exact symptom the user hit - time_source_exists() returning
+		// false for a freshly created/started timesource.
+		it("time_source_exists() recognizes a mocked timesource through its lifecycle", function() {
+			var _ts = time_source_create(time_source_game, 2, time_source_units_seconds, show_debug_message, ["Hello World"], -1);
+			expect(time_source_exists(_ts)).toBeTruthy();	// exists after creation
+
+			time_source_start(_ts);
+			expect(time_source_exists(_ts)).toBeTruthy();	// exists after starting
+
+			time_source_destroy(_ts);
+			expect(time_source_exists(_ts)).toBeFalsy();	// gone after destroy
+		});
+
+		// End-to-end through the PUBLIC time_source_create / time_source_start macros
+		// (not simulateTimeSource) so the mock create+start path is exercised.
+		it("time_source_create() + time_source_start() fire the callback during simulated frames", function() {
+			var _inst = create(100, 100, o_gmtl_demo_timer);
+			expect(_inst.timer_test_value).toBeEqual(0);
+
+			var _ts = time_source_create(time_source_game, 5, time_source_units_frames, function(_inst) {
+				_inst.timer_test_value = 100;
+			}, [_inst], 1);
+			time_source_start(_ts);
+
+			simulateFrameWait(5);
+			expect(_inst.timer_test_value).toBeEqual(100);
+
+			instance_destroy(_inst);
+		});
+
+		// PUBLIC call_later macro should be mocked and fire during simulated frames too.
+		it("call_later() is mocked and fires during simulated frames", function() {
+			global.__gmtl_reg_call_later = 0;
+			call_later(10, time_source_units_frames, function() {
+				global.__gmtl_reg_call_later = 77;
+			});
+
+			simulateFrameWait(10);
+			expect(global.__gmtl_reg_call_later).toBeEqual(77);
+		});
+
+		// The core fix: OUTSIDE the test-run window the mock must delegate to the real
+		// engine, so game / 3rd-party (Input, Scribble, ...) timesources work normally.
+		// We temporarily flip the internal running flag to emulate boot / normal gameplay.
+		it("timesources created outside the test-run window are REAL, not mocked", function() {
+			var _prev_running = gmtl_internal.running;
+			gmtl_internal.running = false;
+			try {
+				var _ts = time_source_create(time_source_game, 1, time_source_units_seconds, function() {}, [], 1);
+
+				// Real engine returns a numeric id, not a mocked GMTL_TimeSource struct.
+				expect(is_struct(_ts)).toBeFalsy();
+
+				// ...and the real engine recognizes it as existing.
+				expect(time_source_exists(_ts)).toBeTruthy();
+
+				time_source_destroy(_ts);
+			} finally {
+				// Always restore so a failure here cannot leak into other tests.
+				gmtl_internal.running = _prev_running;
+			}
+		});
+	});
+});

GM-Testing-Library/scripts/GMTL_dependencies/GMTL_dependencies.gml

@@ -8,7 +8,10 @@ function __gmtl_dep_fn_string_percentage(_val, _max) {
 			var _n = power(10, _dec);
 			return round(_x * _n) / _n;
 		}
-		
+
+		// Guard against divide-by-zero when there are no suites/tests/functions to report.
+		if (_max == 0) return 0;
+
 		return round_dec(100 * (_val / _max), 2);
 	}
 	return string(percentage(_val, _max)) + "%";

GM-Testing-Library/scripts/GMTL_init/GMTL_init.gml

@@ -23,6 +23,11 @@ gml_pragma("global", "__gmtl_init()");
 /// @func __gmtl_setup()
 /// @ignore
 function __gmtl_setup() {
+	// Idempotent: never wipe an already-initialized state. Suites are registered
+	// synchronously by suite() and, depending on the game's global-init order, that can
+	// happen before this pragma runs. A second setup call must not discard them.
+	if (variable_global_exists("__gmtl_internal")) return;
+
 	global.__gmtl_async_event_map = -1;
 	gmtl_internal = {
 		indent:	0,
@@ -73,6 +78,7 @@ function __gmtl_setup() {
 		},
 		timesources: [],
 		initializing: true,
+		running: false,
 		finished: false,
 	};
 }
@@ -96,9 +102,16 @@ function __gmtl_init() {
 
 		var _t_start = get_timer();
 		var _suites_len = array_length(gmtl_suite_list);
+
+		// Mocking is only active while suites are actually executing. Any timesource,
+		// input, etc. created by game/library code OUTSIDE this window hits the real
+		// engine functions. Prevents boot-window timesources from being silently mocked.
+		gmtl_internal.running = true;
 		for (var i = 0; i < _suites_len; i++) {
 			__gmtl_internal_fn_call_suite(gmtl_suite_list[i]);
 		}
+		gmtl_internal.running = false;
+
 		__gmtl_internal_fn_finish_suites(_t_start);
 
 		if (gmtl_show_coverage) {