From e08c85158380161da5e2f0de4c7834bd7f00e1dd Mon Sep 17 00:00:00 2001
From: =?utf8?q?J=C3=A9r=C3=B4me=20Benoit?= <jerome.benoit@sap.com>
Date: Fri, 27 Feb 2026 17:12:21 +0100
Subject: [PATCH] docs(tests): document timer mock pattern for test reuse

---
 tests/utils/Utils.test.ts                     | 29 +++++++++++++++++++
 .../unit/{CSTable.spec.ts => CSTable.test.ts} |  0
 2 files changed, 29 insertions(+)
 rename ui/web/tests/unit/{CSTable.spec.ts => CSTable.test.ts} (100%)

diff --git a/tests/utils/Utils.test.ts b/tests/utils/Utils.test.ts
index 3557757b..1abbd5bd 100644
--- a/tests/utils/Utils.test.ts
+++ b/tests/utils/Utils.test.ts
@@ -78,6 +78,35 @@ await describe('Utils test suite', async () => {
   })
 
   await it('Verify sleep()', async t => {
+    /**
+     * Timer mock pattern for testing asynchronous timer-based operations.
+     * Uses Node.js test module's built-in timer mocking API.
+     * @example
+     * // Enable timer mocking with setTimeout API
+     * t.mock.timers.enable({ apis: ['setTimeout'] })
+     *
+     * try {
+     *   const delay = 10
+     *   const sleepPromise = sleep(delay)
+     *   // Advance mocked timers by specified milliseconds
+     *   t.mock.timers.tick(delay)
+     *   const timeout = await sleepPromise
+     *   expect(timeout).toBeDefined()
+     * } finally {
+     *   // Always reset timers after test to prevent side effects
+     *   t.mock.timers.reset()
+     * }
+     * @description
+     * This pattern demonstrates:
+     * - `t.mock.timers.enable()`: Activates timer mocking for specified APIs (e.g., setTimeout)
+     * - `t.mock.timers.tick()`: Advances the mocked internal clock by the given milliseconds
+     * - `t.mock.timers.reset()`: Clears mocked timers; use in finally block to ensure cleanup
+     *
+     * Useful for testing:
+     * - Timeout and interval-based logic
+     * - Async functions that depend on timing
+     * - Avoiding slow tests caused by actual delays
+     */
     t.mock.timers.enable({ apis: ['setTimeout'] })
     try {
       const delay = 10
diff --git a/ui/web/tests/unit/CSTable.spec.ts b/ui/web/tests/unit/CSTable.test.ts
similarity index 100%
rename from ui/web/tests/unit/CSTable.spec.ts
rename to ui/web/tests/unit/CSTable.test.ts
-- 
2.53.0