From de65b28697e95c5d1bef2c13f7c46bfa8d65ab78 Mon Sep 17 00:00:00 2001 From: Erick Wendel Date: Sun, 3 Sep 2023 18:04:19 -0300 Subject: [PATCH 1/2] test_runner: add jsdocs to MockTimers Signed-off-by: Erick Wendel --- lib/internal/test_runner/mock/mock_timers.js | 26 ++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/lib/internal/test_runner/mock/mock_timers.js b/lib/internal/test_runner/mock/mock_timers.js index 7e38f9f7b5113c..fc263a5998dc17 100644 --- a/lib/internal/test_runner/mock/mock_timers.js +++ b/lib/internal/test_runner/mock/mock_timers.js @@ -455,6 +455,13 @@ class MockTimers { ); } + /** + * Advances the virtual time of MockTimers by the specified duration (in milliseconds). + * This method simulates the passage of time and triggers any scheduled timers that are due. + * @param {number} [time=1] - The amount of time (in milliseconds) to advance the virtual time. + * @throws {ERR_INVALID_STATE} If MockTimers are not enabled. + * @throws {ERR_INVALID_ARG_VALUE} If a negative time value is provided. + */ tick(time = 1) { if (!this.#isEnabled) { throw new ERR_INVALID_STATE( @@ -488,6 +495,12 @@ class MockTimers { } } + /** + * Enables MockTimers for the specified timers + * @param {string[]} timers - An array of timer types to enable, e.g., ['setTimeout', 'setInterval']. + * @throws {ERR_INVALID_STATE} If MockTimers are already enabled. + * @throws {ERR_INVALID_ARG_VALUE} If an unsupported timer type is specified. + */ enable(timers = SUPPORTED_TIMERS) { if (this.#isEnabled) { throw new ERR_INVALID_STATE( @@ -513,10 +526,19 @@ class MockTimers { this.#toggleEnableTimers(true); } + /** + * The `[SymbolDispose]` method is a custom method that can be used to dispose of the MockTimers instance. + * It internally calls the `reset` method to reset and disable the timers. + * It is intended for internal use and should not be called directly in most cases. + */ [SymbolDispose]() { this.reset(); } + /** + * Resets MockTimers, disabling any enabled timers and clearing the execution queue. + * Does nothing if MockTimers are not enabled. + */ reset() { // Ignore if not enabled if (!this.#isEnabled) return; @@ -531,6 +553,10 @@ class MockTimers { } } + /** + * Runs all scheduled timers until there are no more pending timers. + * @throws {ERR_INVALID_STATE} If MockTimers are not enabled. + */ runAll() { if (!this.#isEnabled) { throw new ERR_INVALID_STATE( From 823aa0cd6748dfc974c28a304f164c04cb1df4d3 Mon Sep 17 00:00:00 2001 From: Erick Wendel Date: Mon, 4 Sep 2023 15:16:59 -0300 Subject: [PATCH 2/2] test_runner: apply suggestions Co-authored-by: Benjamin Gruenbaum Co-authored-by: Chemi Atlow --- lib/internal/test_runner/mock/mock_timers.js | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/lib/internal/test_runner/mock/mock_timers.js b/lib/internal/test_runner/mock/mock_timers.js index fc263a5998dc17..1624b03f8af674 100644 --- a/lib/internal/test_runner/mock/mock_timers.js +++ b/lib/internal/test_runner/mock/mock_timers.js @@ -496,7 +496,7 @@ class MockTimers { } /** - * Enables MockTimers for the specified timers + * Enables MockTimers for the specified timers. * @param {string[]} timers - An array of timer types to enable, e.g., ['setTimeout', 'setInterval']. * @throws {ERR_INVALID_STATE} If MockTimers are already enabled. * @throws {ERR_INVALID_ARG_VALUE} If an unsupported timer type is specified. @@ -527,9 +527,7 @@ class MockTimers { } /** - * The `[SymbolDispose]` method is a custom method that can be used to dispose of the MockTimers instance. - * It internally calls the `reset` method to reset and disable the timers. - * It is intended for internal use and should not be called directly in most cases. + * An alias for `this.reset()`, allowing the disposal of the `MockTimers` instance. */ [SymbolDispose]() { this.reset();