fix: improve SmartSpy type safety and cross-framework test compatibility

Author: trurl-master

jest-setup.ts

@@ -1,3 +1,33 @@
+/**
+ * Jest-specific setup for unified testing framework abstraction.
+ *
+ * This file provides Jest implementations of the unified testing utilities
+ * available on the global `runner` object. It creates a consistent interface
+ * that allows the library's tests to work identically across Jest, Vitest,
+ * and SWC test environments.
+ *
+ * The key pattern here is the SmartSpy system, which wraps framework-specific
+ * spy objects (like Jest's SpyInstance) to provide a unified API.
+ */
+
+/**
+ * Unified spy interface that works consistently across Jest and Vitest.
+ *
+ * This interface defines the common spy methods that our library needs,
+ * providing a consistent API regardless of the underlying testing framework.
+ * The implementation only includes the methods we actually use in our tests.
+ */
+interface SmartSpy {
+  /** Mock the implementation of the spied method */
+  mockImplementation: (fn: () => void) => SmartSpy;
+  /** Assert that the spy was called with specific arguments */
+  toHaveBeenCalledWith: (...args: unknown[]) => void;
+  /** Restore the original method implementation */
+  mockRestore: () => void;
+  /** Allow access to any other spy properties/methods from the underlying framework */
+  [key: string]: unknown;
+}
+
 function useFakeTimers() {
   jest.useFakeTimers();
 }
@@ -14,32 +44,78 @@ function fn() {
   return jest.fn();
 }
 
-// Smart proxy that only implements what we need
-function createSmartSpy(realSpy: unknown) {
+/**
+ * Creates a unified spy interface that works consistently across Jest and Vitest.
+ *
+ * This function wraps a Jest SpyInstance in a Proxy to provide a consistent API
+ * that matches the SmartSpy interface expected by the testing framework abstraction.
+ *
+ * The proxy intercepts calls to specific methods (mockImplementation, toHaveBeenCalledWith,
+ * mockRestore) and ensures they work the same way regardless of whether the underlying
+ * spy is from Jest or Vitest. For all other properties/methods, it passes through
+ * to the original spy.
+ *
+ * This is part of the broader pattern in this library where we create unified interfaces
+ * across different testing frameworks (Jest, Vitest, SWC) so that the library's mocks
+ * work consistently in any environment.
+ *
+ * @param realSpy - The underlying Jest SpyInstance to wrap
+ * @returns A proxy that implements the SmartSpy interface
+ */
+function createSmartSpy(realSpy: jest.SpyInstance): SmartSpy {
   return new Proxy(realSpy as object, {
     get(target, prop) {
       // Only implement the methods we actually use
       if (prop === 'mockImplementation') {
         return (fn: () => void) => {
-          (target as { mockImplementation: (fn: () => void) => unknown }).mockImplementation(fn);
-          return createSmartSpy(target);
+          (target as jest.SpyInstance).mockImplementation(fn);
+          return createSmartSpy(target as jest.SpyInstance);
         };
       }
       if (prop === 'toHaveBeenCalledWith') {
-        return (target as { toHaveBeenCalledWith: (...args: unknown[]) => unknown }).toHaveBeenCalledWith.bind(target);
+        return (...args: unknown[]) => {
+          // Jest SpyInstance doesn't have toHaveBeenCalledWith as a method,
+          // it's available through expect(spy).toHaveBeenCalledWith()
+          // For compatibility, we'll check if the method exists and call it
+          const spy = target as Record<string, unknown>;
+          if (typeof spy.toHaveBeenCalledWith === 'function') {
+            return (
+              spy.toHaveBeenCalledWith as (...args: unknown[]) => unknown
+            )(...args);
+          }
+          return undefined;
+        };
       }
       if (prop === 'mockRestore') {
-        return (target as { mockRestore: () => void }).mockRestore.bind(target);
+        return () => {
+          (target as jest.SpyInstance).mockRestore();
+        };
       }
-      
+
       // For everything else, just pass through to the real spy
       return (target as Record<string | symbol, unknown>)[prop];
-    }
-  });
+    },
+  }) as SmartSpy;
 }
 
-function spyOn<T extends object, K extends keyof T>(object: T, method: K) {
-  const realSpy = (jest.spyOn as (obj: T, method: K) => unknown)(object, method);
+/**
+ * Creates a spy on an object method using Jest's spyOn, wrapped with SmartSpy interface.
+ *
+ * This is the Jest-specific implementation of the unified spyOn function that's available
+ * on the global `runner` object. It creates a Jest spy and wraps it with createSmartSpy
+ * to provide a consistent interface across testing frameworks.
+ *
+ * @param object - The object to spy on
+ * @param method - The method name to spy on
+ * @returns A SmartSpy that provides unified spy functionality
+ */
+function spyOn<T extends object, K extends keyof T>(
+  object: T,
+  method: K
+): SmartSpy {
+  // Use a more specific type assertion to avoid 'any'
+  const spyFunction = jest.spyOn as (object: T, method: K) => jest.SpyInstance;
+  const realSpy = spyFunction(object, method);
   return createSmartSpy(realSpy);
 }
 

src/mocks/web-animations-api/__tests__/cssNumberishHelpers.test.ts

@@ -1,4 +1,8 @@
-import { cssNumberishToNumber, cssNumberishToNumberWithDefault, initCSSTypedOM } from '../cssNumberishHelpers';
+import {
+  cssNumberishToNumber,
+  cssNumberishToNumberWithDefault,
+  initCSSTypedOM,
+} from '../cssNumberishHelpers';
 
 describe('cssNumberishHelpers', () => {
   beforeAll(() => {
@@ -37,32 +41,43 @@ describe('cssNumberishHelpers', () => {
     });
 
     it('should return null for non-time units like px', () => {
+      const consoleWarnSpy = runner
+        .spyOn(console, 'warn')
+        .mockImplementation(() => {
+          /* do nothing */
+        });
       const oneHundredPx = new CSSUnitValue(100, 'px');
       expect(cssNumberishToNumber(oneHundredPx)).toBeNull();
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        "jsdom-testing-mocks: Unsupported CSS unit 'px' in cssNumberishToNumber. Returning null."
+      );
+      consoleWarnSpy.mockRestore();
     });
 
     it('should handle CSSMathValue for time calculations', () => {
       // Test time-dimensioned math values
       const timeSum = CSS.s(1).add(CSS.ms(500)); // 1.5 seconds = 1500ms
       expect(cssNumberishToNumber(timeSum)).toBe(1500);
-      
-      const timeProduct = CSS.s(2).mul(CSS.number(1.5)); // 3 seconds = 3000ms  
+
+      const timeProduct = CSS.s(2).mul(CSS.number(1.5)); // 3 seconds = 3000ms
       expect(cssNumberishToNumber(timeProduct)).toBe(3000);
     });
 
     it('should handle CSSMathValue for dimensionless calculations', () => {
       // Test dimensionless math values
       const numberSum = CSS.number(2).add(CSS.number(3)); // = 5
       expect(cssNumberishToNumber(numberSum)).toBe(5);
-      
+
       const iterations = CSS.number(2.5).mul(CSS.number(2)); // = 5
       expect(cssNumberishToNumber(iterations)).toBe(5);
     });
 
     it('should return null and warn for incompatible CSSMathValue dimensions', () => {
       const consoleWarnSpy = runner
         .spyOn(console, 'warn')
-        .mockImplementation(() => { /* do nothing */ });
+        .mockImplementation(() => {
+          /* do nothing */
+        });
 
       const lengthValue = CSS.px(100).add(CSS.em(1)); // Different length units create CSSMathSum
       expect(cssNumberishToNumber(lengthValue)).toBeNull();
@@ -73,11 +88,12 @@ describe('cssNumberishHelpers', () => {
       consoleWarnSpy.mockRestore();
     });
 
-
     it('should return null and warn for unsupported values', () => {
       const consoleWarnSpy = runner
         .spyOn(console, 'warn')
-        .mockImplementation(() => { /* do nothing */ });
+        .mockImplementation(() => {
+          /* do nothing */
+        });
 
       expect(cssNumberishToNumber({} as unknown as CSSNumberish)).toBeNull();
       expect(consoleWarnSpy).toHaveBeenCalledWith(
@@ -91,12 +107,26 @@ describe('cssNumberishHelpers', () => {
   describe('cssNumberishToNumberWithDefault', () => {
     it('should return the converted value if conversion succeeds', () => {
       expect(cssNumberishToNumberWithDefault(100, 50)).toBe(100);
-      expect(cssNumberishToNumberWithDefault(new CSSUnitValue(2, 's'), 500)).toBe(2000);
+      expect(
+        cssNumberishToNumberWithDefault(new CSSUnitValue(2, 's'), 500)
+      ).toBe(2000);
     });
 
     it('should return the default value if conversion fails', () => {
       expect(cssNumberishToNumberWithDefault(null, 50)).toBe(50);
-      expect(cssNumberishToNumberWithDefault(new CSSUnitValue(100, 'px'), 42)).toBe(42);
+
+      const consoleWarnSpy = runner
+        .spyOn(console, 'warn')
+        .mockImplementation(() => {
+          /* do nothing */
+        });
+      expect(
+        cssNumberishToNumberWithDefault(new CSSUnitValue(100, 'px'), 42)
+      ).toBe(42);
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        "jsdom-testing-mocks: Unsupported CSS unit 'px' in cssNumberishToNumber. Returning null."
+      );
+      consoleWarnSpy.mockRestore();
     });
   });
-}); 
+});