feat: add retryingTest helper for DOM testing (#517)

* feat: add retryingTest helper for DOM testing

- Add retryingTest function to handle async DOM element detection
- Useful for waiting for elements that appear after API calls or rendering
- Configurable retry attempts (default 20) with 1ms delay between attempts
- Returns Promise that resolves when test passes or rejects with error message
- Add comprehensive test suite with 8 test cases covering all scenarios
- Export as part of __helpers global object for use in curriculum tests

* Apply suggestions from code review

Co-authored-by: Oliver Eyton-Williams <ojeytonwilliams@gmail.com>

* Update packages/tests/javascript-helper.test.ts

---------

Co-authored-by: Oliver Eyton-Williams <ojeytonwilliams@gmail.com>

Author: ilenia-magoni

packages/helpers/lib/index.ts

@@ -669,3 +669,30 @@ export function getFunctionParams(code: string) {
   // Return an empty array if no function parameters are found
   return [];
 }
+
+/**
+ * Retries a test function with a specified delay between attempts
+ * Useful for testing DOM elements that may not be immediately available
+ * @param test - Function that returns a truthy value when the condition is met
+ * @param message - Error message to throw if all retry attempts fail
+ * @param tries - Number of retry attempts (defaults to 20)
+ * @returns Promise that resolves when test passes or rejects with message
+ * @example
+ * await retryingTest(() => document.querySelector('img'), "'img' element not found");
+ */
+export function retryingTest(
+  test: () => unknown,
+  message: string,
+  tries = 20,
+): Promise<void> {
+  if (tries < 1) return Promise.reject(new Error(message));
+  if (test()) return Promise.resolve();
+
+  return new Promise((resolve, reject) => {
+    setTimeout(() => {
+      retryingTest(test, message, tries - 1)
+        .then(resolve)
+        .catch(reject);
+    }, 1);
+  });
+}

packages/tests/javascript-helper.test.ts

@@ -1,6 +1,6 @@
 import jsTestValues from "./__fixtures__/curriculum-helpers-javascript";
 
-import { getFunctionParams } from "./../helpers/lib/index";
+import { getFunctionParams, retryingTest } from "./../helpers/lib/index";
 
 const {
   functionDeclaration,
@@ -46,4 +46,128 @@ describe("js-help", () => {
       expect(parameters[3].name).toBe("...rest");
     });
   });
+
+  describe("retryingTest", () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it("should resolve immediately when test passes on first try", async () => {
+      const testFn = vi.fn().mockReturnValue(true);
+
+      const promise = retryingTest(testFn, "Test failed");
+
+      await expect(promise).resolves.toBeUndefined();
+      expect(testFn).toHaveBeenCalledTimes(1);
+    });
+
+    it("should resolve when test passes after retries", async () => {
+      const testFn = vi
+        .fn()
+        .mockReturnValueOnce(false)
+        .mockReturnValueOnce(false)
+        .mockReturnValueOnce(true);
+
+      const promise = retryingTest(testFn, "Test failed");
+
+      // Run all timers and wait for the promise to settle
+      vi.runAllTimers();
+
+      await expect(promise).resolves.toBeUndefined();
+      expect(testFn).toHaveBeenCalledTimes(3);
+    });
+
+    it("should reject with error message when all retries fail", async () => {
+      const testFn = vi.fn().mockReturnValue(false);
+      const errorMessage = "Element not found";
+
+      const promise = retryingTest(testFn, errorMessage, 3);
+
+      // Run all timers and wait for the promise to settle
+      vi.runAllTimers();
+
+      await expect(promise).rejects.toThrow(errorMessage);
+      expect(testFn).toHaveBeenCalledTimes(3);
+    });
+
+    it("should reject immediately when tries is less than 1", async () => {
+      const testFn = vi.fn();
+      const errorMessage = "Invalid tries";
+
+      const promise = retryingTest(testFn, errorMessage, 0);
+
+      await expect(promise).rejects.toThrow(errorMessage);
+      expect(testFn).not.toHaveBeenCalled();
+    });
+
+    it("should use default tries value of 20", async () => {
+      const testFn = vi.fn().mockReturnValue(false);
+
+      const promise = retryingTest(testFn, "Test failed");
+
+      // Run all timers and wait for the promise to settle
+      vi.runAllTimers();
+
+      await expect(promise).rejects.toThrow("Test failed");
+      expect(testFn).toHaveBeenCalledTimes(20);
+    });
+
+    it("should work with truthy values (not just boolean true)", async () => {
+      const testFn = vi
+        .fn()
+        .mockReturnValueOnce(null)
+        .mockReturnValueOnce(undefined)
+        .mockReturnValueOnce(0)
+        .mockReturnValueOnce("")
+        .mockReturnValueOnce("found element"); // Truthy
+
+      const promise = retryingTest(testFn, "Test failed");
+
+      vi.runAllTimers();
+
+      await expect(promise).resolves.toBeUndefined();
+      expect(testFn).toHaveBeenCalledTimes(5);
+    });
+
+    it("should handle DOM element testing scenario", async () => {
+      // Mock DOM element that appears after delay
+      let mockElement: Element | null = null;
+      const testFn = vi.fn(() => mockElement);
+
+      // Simulate element appearing after 3 attempts
+      setTimeout(() => {
+        mockElement = { tagName: "IMG" } as Element;
+      }, 3);
+
+      const promise = retryingTest(testFn, "'img' element not found");
+
+      vi.runAllTimers();
+
+      await expect(promise).resolves.toBeUndefined();
+      expect(testFn).toHaveBeenCalledTimes(4);
+    });
+
+    it("should wait 1ms between retries", async () => {
+      const testFn = vi
+        .fn()
+        .mockReturnValueOnce(false)
+        .mockReturnValueOnce(false)
+        .mockReturnValueOnce(true);
+
+      const promise = retryingTest(testFn, "Test failed");
+
+      // Step through timers manually to verify 1ms delay
+      expect(testFn).toHaveBeenCalledTimes(1);
+      vi.advanceTimersByTime(1);
+      expect(testFn).toHaveBeenCalledTimes(2);
+      vi.advanceTimersByTime(1);
+
+      await expect(promise).resolves.toBeUndefined();
+      expect(testFn).toHaveBeenCalledTimes(3);
+    });
+  });
 });