@trackunit/react-vite-test-setup 0.0.1

package/index.esm.js

@@ -0,0 +1,1201 @@
+import 'vitest-canvas-mock';
+import failOnConsole from 'vitest-fail-on-console';
+import { jsx, Fragment } from 'react/jsx-runtime';
+import { vi, beforeEach, afterEach } from 'vitest';
+import '@testing-library/jest-dom/vitest';
+import { cleanup, act } from '@testing-library/react';
+import { TextEncoder, TextDecoder } from 'util';
+import { isValidElement, cloneElement } from 'react';
+import * as reactI18next from 'react-i18next';
+import { Temporal } from '@js-temporal/polyfill';
+import { Globals } from '@react-spring/web';
+import { WritableStream, TransformStream } from 'web-streams-polyfill';
+
+/**
+ * Sets up a mock implementation for HTML Canvas API in testing environments.
+ *
+ * This function uses vitest-canvas-mock to provide a mock implementation of the
+ * HTML Canvas API, allowing tests to run without requiring a real DOM canvas.
+ * Useful for testing components that use canvas rendering.
+ *
+ * Importing vitest-canvas-mock at module load time has the side effect of
+ * patching HTMLCanvasElement.prototype.getContext globally; calling this
+ * function is a no-op kept for API compatibility with the previous Jest
+ * setup.
+ *
+ * @example
+ * import { setupCanvasMock } from '@trackunit/react-vite-test-setup';
+ *
+ * setupCanvasMock();
+ */
+const setupCanvasMock = () => {
+    // The canvas mock is registered via the side-effect import at module
+    // load time; nothing further is needed here.
+};
+
+/**
+ * This will make your tests fail if they log to console.error during the tests.
+ * See more details here: https://www.npmjs.com/package/vitest-fail-on-console
+ *
+ * This setup also automatically suppresses jsdom CSS parsing errors for modern CSS features
+ * that jsdom doesn't support (@container queries and :has() selector). Other CSS parsing
+ * errors will still cause tests to fail.
+ *
+ * If your tests logs to console.error on purpose, you should spy on the console like so:
+ * ```
+ * vi.spyOn(console, 'error').mockImplementation()
+ * // Do your logic ...
+ * expect(console.error).toHaveBeenCalledWith('your error message')
+ * ```
+ */
+const setupFailOnConsole = (overrides = {}) => {
+    failOnConsole({
+        shouldFailOnError: true,
+        shouldFailOnWarn: false,
+        silenceMessage: (message) => {
+            // Suppress ONLY jsdom CSS parsing errors for specific modern CSS features
+            // that we know jsdom doesn't support (@container queries, :has() selector)
+            if (typeof message === "string" &&
+                message.includes("Could not parse CSS stylesheet") &&
+                (message.includes("@container") || message.includes(":has("))) {
+                return true;
+            }
+            return false;
+        },
+        ...overrides,
+    });
+};
+
+/**
+ * `@googlemaps/jest-mocks` still calls `jest.fn()` internally; aliasing the
+ * vitest namespace under the legacy `jest` global keeps it working without
+ * pulling in the real Jest runtime.
+ */
+const ensureJestGlobalAlias = () => {
+    const globalAny = globalThis;
+    if (globalAny.jest === undefined) {
+        globalAny.jest = vi;
+    }
+};
+/**
+ * Sets up mocks for Google Maps API and @vis.gl/react-google-maps components
+ * in testing environments.
+ *
+ * Replaces the `@vis.gl/react-google-maps` hooks/components (`APIProvider`,
+ * `useMap`, `Map`, `Marker`, `AdvancedMarker`, `InfoWindow`,
+ * `useApiIsLoaded`, `useApiLoadingStatus`) with deterministic fakes and
+ * registers a `beforeEach` hook that re-populates `global.window.google.maps`
+ * with mocked `Geocoder` / `geometry` / `AutocompleteService` implementations
+ * via `@googlemaps/jest-mocks`.
+ *
+ * Opt-in: the mock is registered via `vi.doMock` so it is
+ * NOT hoisted and only takes effect once `setupGoogleMaps()` is called from
+ * a test setup file. Tests that need the real `@vis.gl/react-google-maps`
+ * (or their own mock) are unaffected unless they explicitly call this.
+ *
+ * The factory body uses `require()` rather than `import` for
+ * `@vis.gl/react-google-maps` and `@googlemaps/jest-mocks` so neither
+ * package is evaluated until the factory actually runs (the latter still
+ * uses Jest globals internally, so a static import would crash any
+ * consumer that doesn't actually use the Google Maps mock).
+ *
+ * @example
+ * import { setupGoogleMaps } from '@trackunit/react-vite-test-setup';
+ * setupGoogleMaps();
+ */
+const setupGoogleMaps = () => {
+    ensureJestGlobalAlias();
+    const getPlacePredictionsMock = vi.fn();
+    vi.doMock("@vis.gl/react-google-maps", async () => {
+        const originalModule = await vi.importActual("@vis.gl/react-google-maps");
+        ensureJestGlobalAlias();
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { APILoadingStatus } = require("@vis.gl/react-google-maps");
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { initialize } = require("@googlemaps/jest-mocks");
+        // The Google Maps API needs to be initialized before constructing a map
+        // instance so the mocked constructors / classes exist on `global.google`.
+        initialize();
+        const mapOptions = { center: { lat: 0, lng: 0 }, zoom: 10 };
+        const mapContainer = document.createElement("div");
+        const map = new google.maps.Map(mapContainer, mapOptions);
+        vi.spyOn(map, "getDiv").mockReturnValue(mapContainer);
+        const AdvancedMarkerMock = vi.fn(function (props) {
+            return (jsx("div", { "data-position": JSON.stringify(props.position), "data-testid": "marker", children: props.children }));
+        });
+        const MapMock = vi.fn(function (props) {
+            return jsx("div", { "data-testid": "map", children: props.children });
+        });
+        const MapMarkerMock = vi.fn(function (props) {
+            return jsx("div", { "data-testid": "map", children: props.children });
+        });
+        const InfoWindowMock = vi.fn(function (props) {
+            return jsx("div", { "data-testid": "google-info-window", children: props.children });
+        });
+        const APIProviderMock = vi.fn(function (props) {
+            return jsx(Fragment, { children: props.children });
+        });
+        return {
+            ...originalModule,
+            APIProvider: APIProviderMock,
+            useApiLoadingStatus: () => APILoadingStatus.LOADED,
+            useApiIsLoaded: () => true,
+            useMap: () => map,
+            AdvancedMarker: AdvancedMarkerMock,
+            Map: MapMock,
+            Marker: MapMarkerMock,
+            InfoWindow: InfoWindowMock,
+        };
+    });
+    beforeEach(() => {
+        ensureJestGlobalAlias();
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { initialize } = require("@googlemaps/jest-mocks");
+        initialize();
+        global.window.google.maps = {
+            ...global.window.google.maps,
+            Geocoder: vi.fn(),
+            geometry: {
+                ...global.window.google.maps.geometry,
+                spherical: {
+                    computeDistanceBetween: vi.fn(),
+                    computeArea: vi.fn(),
+                    computeHeading: vi.fn(),
+                    computeLength: vi.fn(),
+                    computeOffset: vi.fn(),
+                    computeOffsetOrigin: vi.fn(),
+                    computeSignedArea: vi.fn(),
+                    interpolate: vi.fn(),
+                },
+            },
+            places: {
+                ...global.window.google.maps.places,
+                // `new google.maps.places.AutocompleteService()` invokes this mock
+                // with `[[Construct]]`. Vitest 4's spy enforces that the impl is
+                // a real function (not an arrow), so we use a `function` expression
+                // to expose the construct slot. Cast to never to satisfy the
+                // strict mocked-class type that vi.fn() infers for arrow impls.
+                AutocompleteService: vi.fn().mockImplementation(function () {
+                    return {
+                        ...global.window.google.maps.places,
+                        getPlacePredictions: getPlacePredictionsMock,
+                    };
+                }),
+            },
+        };
+    });
+};
+
+/**
+ * Replaces `react-helmet-async`'s `Helmet` and `HelmetProvider` with no-op
+ * components so head-mutating components rendered under test do not touch
+ * the jsdom document.
+ *
+ * Opt-in: the mock is registered via `vi.doMock` so it is
+ * NOT hoisted and only takes effect once `setupHelmetMock()` is called from
+ * a test setup file. Tests that need the real `react-helmet-async` (or
+ * their own mock) are unaffected unless they explicitly call this.
+ *
+ * See more details here: https://www.npmjs.com/package/react-helmet-async
+ *
+ * @example
+ * import { setupHelmetMock } from '@trackunit/react-vite-test-setup';
+ * setupHelmetMock();
+ */
+const setupHelmetMock = () => {
+    vi.doMock("react-helmet-async", () => ({
+        Helmet: () => null,
+        HelmetProvider: () => null,
+    }));
+};
+
+/**
+ * Mocks the IntersectionObserver API for testing environments.
+ *
+ * This function adds a mock implementation of the IntersectionObserver API to the global window object.
+ * The mock implementation provides all the necessary methods (observe, unobserve, disconnect, takeRecords)
+ * but with empty implementations, allowing tests of components that use IntersectionObserver to run
+ * without errors in Jest's JSDOM environment.
+ *
+ * Useful for testing components that rely on:
+ * - Lazy loading
+ * - Infinite scrolling
+ * - Visibility-based rendering
+ * - Any other intersection-based functionality
+ *
+ * @example
+ * // In your jest setup file
+ * import { setupIntersectionObserver } from '@trackunit/react-vite-test-setup';
+ *
+ * setupIntersectionObserver();
+ */
+const setupIntersectionObserver = () => (window.IntersectionObserver = MockIntersectionObserver);
+class MockIntersectionObserver {
+    constructor() {
+        this.root = null;
+        this.rootMargin = "";
+        this.scrollMargin = "";
+        this.thresholds = [];
+    }
+    disconnect() {
+        // Empty
+    }
+    observe() {
+        // Empty
+    }
+    takeRecords() {
+        return [];
+    }
+    unobserve() {
+        // Empty
+    }
+}
+
+/**
+ * Creates a new listener registry for tracking event subscriptions.
+ */
+const createListenerRegistry = () => ({
+    regular: new Map(),
+    once: new Map(),
+});
+/**
+ * Mock LngLat class matching Mapbox GL's interface.
+ * Returns actual objects with lng/lat properties rather than class instances.
+ */
+const createMockLngLat = (lng, lat) => ({
+    lng,
+    lat,
+    wrap: () => createMockLngLat(lng, lat),
+    toArray: () => [lng, lat],
+    distanceTo: () => 0,
+    toBounds: () => createMockLngLatBounds(lng - 1, lat - 1, lng + 1, lat + 1),
+    toString: () => `LngLat(${lng}, ${lat})`,
+    toEcef: () => [0, 0, 0],
+});
+/**
+ * Mock LngLatBounds matching Mapbox GL's interface.
+ */
+const createMockLngLatBounds = (west, south, east, north) => {
+    const sw = createMockLngLat(west, south);
+    const ne = createMockLngLat(east, north);
+    const bounds = {
+        _sw: sw,
+        _ne: ne,
+        getSouthWest: () => sw,
+        getNorthEast: () => ne,
+        getNorthWest: () => createMockLngLat(west, north),
+        getSouthEast: () => createMockLngLat(east, south),
+        getWest: () => west,
+        getSouth: () => south,
+        getEast: () => east,
+        getNorth: () => north,
+        getCenter: () => createMockLngLat((west + east) / 2, (south + north) / 2),
+        toArray: () => [
+            [west, south],
+            [east, north],
+        ],
+        toString: () => `LngLatBounds(${sw.toString()}, ${ne.toString()})`,
+        isEmpty: () => false,
+        contains: () => true,
+        extend: () => bounds,
+        setNorthEast: () => bounds,
+        setSouthWest: () => bounds,
+    };
+    return bounds;
+};
+/**
+ * Creates a mock Mapbox map instance for unit testing adapter instances directly.
+ *
+ * Use this when you need fine-grained control over mock behavior, such as:
+ * - Testing adapter instance methods (connect, setCenter, etc.)
+ * - Simulating map events (idle, click, movestart)
+ * - Verifying method calls on the map
+ *
+ * @example
+ * ```typescript
+ * import { createMockMapboxMap } from "@trackunit/react-vite-test-setup";
+ *
+ * it("should connect to map", () => {
+ *   const { map, triggerEvent } = createMockMapboxMap();
+ *   const adapter = new MapboxAdapterInstance(config);
+ *
+ *   adapter.connect(map as unknown as mapboxgl.Map);
+ *   triggerEvent("idle");
+ *
+ *   expect(adapter.getState().isReady).toBe(true);
+ * });
+ * ```
+ */
+const createMockMapboxMap = () => {
+    const registry = createListenerRegistry();
+    const addListener = (store, event, handler) => {
+        const handlers = store.get(event);
+        if (handlers === undefined) {
+            store.set(event, new Set([handler]));
+        }
+        else {
+            handlers.add(handler);
+        }
+        return map;
+    };
+    const map = {
+        on: vi.fn((event, handler) => addListener(registry.regular, event, handler)),
+        once: vi.fn((event, handler) => addListener(registry.once, event, handler)),
+        off: vi.fn((event, handler) => {
+            registry.regular.get(event)?.delete(handler);
+            return map;
+        }),
+        remove: vi.fn(),
+        getCenter: vi.fn(() => createMockLngLat(0, 0)),
+        getZoom: vi.fn(() => 10),
+        getBounds: vi.fn(() => createMockLngLatBounds(-1, -1, 1, 1)),
+        setCenter: vi.fn((_center) => map),
+        setZoom: vi.fn((_zoom) => map),
+        panTo: vi.fn((_lngLat) => map),
+        panBy: vi.fn((_offset) => map),
+        fitBounds: vi.fn((_bounds, _options) => map),
+        setStyle: vi.fn((_style) => map),
+        isStyleLoaded: vi.fn(() => true),
+        isMoving: vi.fn(() => false),
+        addSource: vi.fn(),
+        removeSource: vi.fn(),
+        getSource: vi.fn(() => undefined),
+        addLayer: vi.fn(),
+        removeLayer: vi.fn(),
+        getLayer: vi.fn(() => undefined),
+        setPaintProperty: vi.fn(),
+        hasImage: vi.fn(() => false),
+        addImage: vi.fn(),
+        getCanvas: vi.fn(() => ({ style: {} })),
+        getCanvasContainer: vi.fn(() => document.createElement("div")),
+    };
+    const triggerEvent = (eventName, event) => {
+        // Fire regular listeners
+        const regularHandlers = registry.regular.get(eventName);
+        if (regularHandlers !== undefined) {
+            regularHandlers.forEach((handler) => handler(event));
+        }
+        // Fire and clear once listeners
+        const onceHandlers = registry.once.get(eventName);
+        if (onceHandlers !== undefined) {
+            onceHandlers.forEach((handler) => handler(event));
+            registry.once.delete(eventName);
+        }
+    };
+    return { map, triggerEvent };
+};
+/**
+ * Mock click event matching Mapbox GL's MapMouseEvent shape.
+ * Use with triggerEvent("click", createMockClickEvent(...))
+ *
+ * Note: The `point` property is intentionally omitted because:
+ * 1. It requires the full Point class from @mapbox/point-geometry with 30+ methods
+ * 2. No tests currently use the point property
+ * 3. Since this returns Partial<MapMouseEvent>, point is optional
+ */
+const createMockClickEvent = (lng, lat) => ({
+    lngLat: createMockLngLat(lng, lat),
+    originalEvent: new MouseEvent("click"),
+    type: "click",
+});
+/**
+ * Sets up mocks for Mapbox GL JS in testing environments.
+ *
+ * Replaces `mapbox-gl`'s `Map` and `Marker` constructors with deterministic
+ * fakes (the `Map` mock auto-fires the `load` event so renderer tests don't
+ * have to wait for it) and registers a `beforeEach` hook that clears mock
+ * call records between tests.
+ *
+ * Opt-in: the mock is registered via `vi.doMock` so it is
+ * NOT hoisted and only takes effect once `setupMapbox()` is called from a
+ * test setup file. Tests that need the real `mapbox-gl` (or their own mock)
+ * are unaffected unless they explicitly call this.
+ *
+ * @example
+ * ```typescript
+ * // In your test file
+ * import { setupMapbox } from "@trackunit/react-vite-test-setup";
+ *
+ * setupMapbox();
+ *
+ * describe("MapboxRenderer", () => {
+ *   it("renders map when loaded", async () => {
+ *     // The mock will auto-fire "load" event
+ *     render(<MapboxRenderer adapterInstance={instance} />);
+ *     await waitFor(() => expect(screen.getByRole("application")).toBeInTheDocument());
+ *   });
+ * });
+ * ```
+ */
+const setupMapbox = () => {
+    vi.doMock("mapbox-gl", () => {
+        // SUT does `new mapboxgl.Map(...)` and `new mapboxgl.Marker(...)`. Vitest
+        // 4's spy invokes the implementation with `new` when the mock itself is
+        // called with `new`, and arrow functions are not constructable. Use
+        // `function` expressions so the implementation has a working
+        // `[[Construct]]` slot.
+        const createMockMapWithAutoLoad = function () {
+            const result = createMockMapboxMap();
+            const originalOn = result.map.on;
+            result.map.on = vi.fn((event, handler) => {
+                originalOn(event, handler);
+                if (event === "load") {
+                    setTimeout(() => handler(undefined), 0);
+                }
+                return result.map;
+            });
+            return result.map;
+        };
+        const createMockMarker = function (options) {
+            const el = options?.element ?? document.createElement("div");
+            const marker = {
+                setLngLat: vi.fn(() => marker),
+                addTo: vi.fn(() => marker),
+                remove: vi.fn(),
+                getElement: vi.fn(() => el),
+                setOffset: vi.fn(() => marker),
+                getLngLat: vi.fn(() => createMockLngLat(0, 0)),
+                setPopup: vi.fn(() => marker),
+                getPopup: vi.fn(() => null),
+                togglePopup: vi.fn(() => marker),
+                setDraggable: vi.fn(() => marker),
+                isDraggable: vi.fn(() => false),
+            };
+            return marker;
+        };
+        return {
+            __esModule: true,
+            default: {
+                Map: vi.fn(createMockMapWithAutoLoad),
+                Marker: vi.fn(createMockMarker),
+                accessToken: "",
+            },
+        };
+    });
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+};
+
+/**
+ * Mocks the window.matchMedia API for testing environments.
+ *
+ * This function creates a mock implementation of the window.matchMedia method that
+ * is commonly used for responsive design and media queries. The mock always returns
+ * a MediaQueryList-like object with standard methods and properties, but with default
+ * values (matches set to false).
+ *
+ * This allows tests of components that use media queries to run without errors in
+ * Jest's JSDOM environment, which doesn't implement matchMedia natively.
+ *
+ * Ideal for testing:
+ * - Responsive components
+ * - Components that adapt to screen size changes
+ * - Components that use CSS media query matching in JavaScript
+ *
+ * @example
+ * // In your jest setup file
+ * import { setupMatchMediaMock } from '@trackunit/react-vite-test-setup';
+ *
+ * setupMatchMediaMock();
+ */
+const setupMatchMediaMock = () => {
+    Object.defineProperty(window, "matchMedia", {
+        writable: true,
+        value: vi.fn().mockImplementation(query => ({
+            matches: false,
+            media: query,
+            onchange: null,
+            addListener: vi.fn(), // Deprecated
+            removeListener: vi.fn(), // Deprecated
+            addEventListener: vi.fn(),
+            removeEventListener: vi.fn(),
+            dispatchEvent: vi.fn(),
+        })),
+    });
+};
+
+/**
+ * Default factory for `new ResizeObserver(...)` invocations. Returns a
+ * fresh object per call so tests can spy on / replace per-instance
+ * methods without affecting later constructions.
+ */
+const buildResizeObserverInstance = () => ({
+    observe: vi.fn(),
+    unobserve: vi.fn(),
+    disconnect: vi.fn(),
+});
+/**
+ * Mock the ResizeObserver to be able to test components that use a resize
+ * observer (e.g. useMeasure, useContainerBreakpoints, and components that
+ * use them like BaseInput). Recommended for all React libs.
+ *
+ * Implementation note: under Vitest the mock was a single
+ * `vi.fn().mockImplementation(...)` so callers could:
+ *   1. `new global.ResizeObserver(cb)` from the SUT (the implementation
+ *      function is callable with `new` because it's a `function` expression
+ *      which has a working `[[Construct]]` slot), AND
+ *   2. `(global.ResizeObserver as Mock).mockImplementation(...)` from the
+ *      spec to capture the callback / inspect constructor arguments.
+ *
+ * Vitest 4's `vi.fn()` is also constructable when the impl is a `function`
+ * expression (arrow functions are *not* constructable), so we keep the
+ * same shape - this preserves both call sites that the migration would
+ * otherwise have to rewrite.
+ */
+const setupResizeObserver = () => {
+    global.ResizeObserver = vi.fn().mockImplementation(function (_callback) {
+        return buildResizeObserverInstance();
+    });
+};
+
+if (typeof global !== "undefined") {
+    global.TextEncoder = global.TextEncoder || TextEncoder;
+    global.TextDecoder = global.TextDecoder || TextDecoder;
+}
+/**
+ * Sets up internationalization and translation mocks for testing environments.
+ *
+ * Mock translations for react-i18next and @trackunit/i18n-library-translation. It creates
+ * simple mock implementations that return the key string as the translation, which allows
+ * for testing internationalized components without the complexity of actual translations.
+ *
+ * The mocks support common translation components and hooks like Trans, useTranslation,
+ * NamespaceTrans, and useNamespaceTranslation.
+ *
+ * @example
+ * // In your jest setup file
+ * import { setupTranslations } from '@trackunit/react-vite-test-setup';
+ *
+ * setupTranslations();
+ */
+const setupTranslations = () => {
+    const hasChildren = (node) => node && (node.children || (node.props && node.props.children));
+    const getChildren = (node) => (node && node.children ? node.children : node.props && node.props.children);
+    const renderNodes = (reactNodes) => {
+        if (typeof reactNodes === "string") {
+            return reactNodes;
+        }
+        return Object.keys(reactNodes).map((key, i) => {
+            const child = reactNodes[key];
+            const isElement = isValidElement(child);
+            if (typeof child === "string") {
+                return child;
+            }
+            if (hasChildren(child)) {
+                const inner = renderNodes(getChildren(child));
+                return cloneElement(child, { ...child.props, key: i }, inner);
+            }
+            if (typeof child === "object" && !isElement) {
+                return Object.keys(child).reduce((str, childKey) => `${str}${child[childKey]}`, "");
+            }
+            return child;
+        });
+    };
+    const i18n = { language: "en", exists: () => true };
+    const useMock = [
+        (k, extra) => k + (extra ? " props: " + JSON.stringify(extra) : ""),
+        i18n,
+    ];
+    useMock.t = (k, extra) => k + (extra ? " props: " + JSON.stringify(extra) : "");
+    useMock.i18n = i18n;
+    const useTranslation = () => useMock;
+    const Trans = ({ i18nKey, components, children }) => {
+        const result = [];
+        result.push(renderNodes([i18nKey]));
+        if (Array.isArray(children)) {
+            result.push(...renderNodes(children));
+        }
+        else if (children && "toArray" in children) {
+            result.push(...renderNodes(children.toArray()));
+        }
+        else {
+            result.push(...renderNodes([children]));
+        }
+        if (components) {
+            result.push(...Object.keys(components).map(key => jsx("span", { children: components[key] }, key)));
+        }
+        return jsx(Fragment, { children: result });
+    };
+    const Translation = ({ children }) => children((k) => k, { i18n });
+    vi.doMock("react-i18next", () => {
+        return {
+            // this mock makes sure any components using the translate HoC receive the t function as a prop
+            Trans,
+            Translation,
+            useTranslation,
+            // mock if needed
+            I18nextProvider: reactI18next.I18nextProvider,
+            initReactI18next: reactI18next.initReactI18next,
+            setDefaults: reactI18next.setDefaults,
+            getDefaults: reactI18next.getDefaults,
+            setI18n: reactI18next.setI18n,
+            getI18n: reactI18next.getI18n,
+        };
+    });
+    vi.doMock("@trackunit/i18n-library-translation", async () => ({
+        ...(await vi.importActual("@trackunit/i18n-library-translation")),
+        NamespaceTrans: (props) => jsx(Trans, { ...props }),
+        useNamespaceTranslation: useTranslation,
+    }));
+};
+
+/**
+ * Flushes all promises in the queue.
+ * This is useful when testing async code.
+ *
+ * @param waitTimeInMS - The amount of time to wait before resolving the promise.
+ * @returns {Promise<void>} - Returns a promise that resolves after the wait time.
+ */
+const flushPromisesInAct = (waitTimeInMS = 0) => {
+    return act(() => {
+        return new Promise(resolve => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            if (global.ORG_setTimeout) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                return global.ORG_setTimeout(() => global.ORG_setTimeout(resolve, waitTimeInMS), 1);
+            }
+            else {
+                setTimeout(() => setTimeout(resolve, waitTimeInMS), 1);
+            }
+        });
+    });
+};
+afterEach(async () => {
+    // Restore real timers BEFORE cleanup / flushPromisesInAct. Both rely on
+    // React's internal scheduler resolving microtasks; under Vitest 4 fake
+    // timers that scheduler waits on the fake clock, so an act-wrapped promise
+    // chained through `setTimeout` will never resolve until the clock is
+    // advanced. Putting `vi.useRealTimers()` first guarantees cleanup is not
+    // gated on whatever fake-timer state the test left installed.
+    // `vi.useRealTimers()` is a no-op when no fake timers are installed.
+    vi.useRealTimers();
+    vi.clearAllMocks();
+    cleanup();
+    await flushPromisesInAct();
+});
+const setupResponseForTanstackRouter = () => {
+    // Polyfill for Response global that TanStack Router v1+ requires
+    if (typeof globalThis.Response === "undefined") {
+        // Simple polyfill for Response in test environment
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        globalThis.Response = class Response {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            constructor(body, init) {
+                this.status = init?.status ?? 200;
+                this.statusText = init?.statusText ?? "";
+                this.headers = new Headers(init?.headers);
+                this.body = body;
+                this.ok = this.status >= 200 && this.status < 300;
+                this.redirected = false;
+                this.type = "default";
+                this.url = "";
+            }
+            static redirect(url, status = 302) {
+                return new Response(null, { status, headers: { Location: url } });
+            }
+            static error() {
+                return new Response(null, { status: 0 });
+            }
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            static json(data, init) {
+                return new Response(JSON.stringify(data), {
+                    ...init,
+                    headers: {
+                        "Content-Type": "application/json",
+                        ...init?.headers,
+                    },
+                });
+            }
+            clone() {
+                return new Response(this.body, {
+                    status: this.status,
+                    statusText: this.statusText,
+                    headers: this.headers,
+                });
+            }
+        };
+    }
+    if (typeof globalThis.Headers === "undefined") {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        globalThis.Headers = class Headers {
+            constructor(init) {
+                this.map = new Map();
+                if (init) {
+                    if (Array.isArray(init)) {
+                        init.forEach(([key, value]) => this.set(key, value));
+                    }
+                    else if (init instanceof Headers) {
+                        init.forEach((value, key) => this.set(key, value));
+                    }
+                    else {
+                        Object.entries(init).forEach(([key, value]) => this.set(key, value));
+                    }
+                }
+            }
+            append(name, value) {
+                this.map.set(name.toLowerCase(), value);
+            }
+            delete(name) {
+                this.map.delete(name.toLowerCase());
+            }
+            get(name) {
+                return this.map.get(name.toLowerCase()) || null;
+            }
+            has(name) {
+                return this.map.has(name.toLowerCase());
+            }
+            set(name, value) {
+                this.map.set(name.toLowerCase(), value);
+            }
+            forEach(callback) {
+                this.map.forEach((value, key) => callback(value, key, this));
+            }
+            entries() {
+                return this.map.entries();
+            }
+            keys() {
+                return this.map.keys();
+            }
+            values() {
+                return this.map.values();
+            }
+            [Symbol.iterator]() {
+                return this.map.entries();
+            }
+        };
+    }
+};
+/**
+ * Sets up React Testing Library and Okta authentication mocks for testing.
+ *
+ * Behaviour:
+ *  - The top-level `afterEach` further up this file (which clears mocks
+ *    and runs RTL `cleanup()`) is registered as a side effect of importing
+ *    this module - that's intentional and existed before this refactor.
+ *  - Calling `setupReactTestingLibrary()` additionally:
+ *      1. Registers the `@okta/okta-react` mock via `vi.doMock` so
+ *         `useOktaAuth()` returns a fixed authenticated session. Opt-in:
+ *         the mock is NOT hoisted, so tests that need the real okta
+ *         hook (or their own mock) are unaffected unless they explicitly
+ *         call this.
+ *      2. Installs the tanstack-router Response polyfill (keeps it
+ *         opt-in because it mutates `globalThis.Response`);
+ *      3. Calls `setupTranslations()` so the
+ *         `useTranslation`/`useNamespaceTranslation` hooks always
+ *         return a mocked i18next instance. Under Vitest, the
+ *         shared jest-preset's `setupFilesAfterEnv` is no longer
+ *         loaded, so projects that previously got translation
+ *         setup "for free" otherwise blow up at the first
+ *         `i18NextInstance.exists is not a function` call. Baking
+ *         it in here means projects can't forget it - the cost is
+ *         mocking i18n in tests that don't use it (harmless: the
+ *         mock only kicks in if the spec imports react-i18next).
+ *      4. Installs `setupMatchMediaMock()`, `setupResizeObserver()`
+ *         and `setupIntersectionObserver()`. Every component test
+ *         needs these three under jsdom, and missing any of them
+ *         causes React's render to throw, which `vitest-fail-on-console`
+ *         then re-raises as "Expected test not to call console.error()".
+ *         Under jest the workspace preset installed them via
+ *         `setupFilesAfterEnv`; under vitest only what each project's
+ *         setup file explicitly imports runs, so most setup files
+ *         called `setupReactTestingLibrary()` plus `setupFailOnConsole()`
+ *         but forgot the basic-DOM triplet. Folding the triplet in
+ *         here means "set up RTL" reads naturally as "set up
+ *         everything you need to render a component".
+ *
+ * @example
+ * import { setupReactTestingLibrary } from '@trackunit/react-vite-test-setup';
+ * setupReactTestingLibrary();
+ */
+const setupReactTestingLibrary = () => {
+    const mockedClaims = {
+        sub: "sub",
+        name: "user",
+    };
+    const mockedIdToken = {
+        idToken: "idToken",
+        claims: mockedClaims,
+        expiresAt: Date.now(),
+        authorizeUrl: "authorize.url",
+        scopes: [],
+        issuer: "issuer",
+        clientId: "clientId",
+    };
+    const mockedAccessToken = {
+        accessToken: "accessToken",
+        claims: mockedClaims,
+        tokenType: "tokenType",
+        userinfoUrl: "userinfo.url",
+        expiresAt: Date.now(),
+        authorizeUrl: "authorize.url",
+        scopes: [],
+    };
+    const mockedAuthState = {
+        accessToken: mockedAccessToken,
+        idToken: mockedIdToken,
+        isAuthenticated: true,
+    };
+    const mockedOktaAuth = () => {
+        return {
+            oktaAuth: {
+                tokenManager: {
+                    on: vi.fn(),
+                    renew: vi.fn(),
+                    setTokens: vi.fn(),
+                    clear: vi.fn(),
+                },
+                getOriginalUri: vi.fn(),
+                signOut: vi.fn().mockResolvedValue({ postLogoutRedirectUri: "mocked-url", clearTokensBeforeRedirect: true }),
+                token: {
+                    getWithRedirect: vi.fn(),
+                    getWithoutPrompt: vi.fn(),
+                },
+                session: {
+                    get: () => {
+                        return { status: "ACTIVE" };
+                    },
+                },
+                authStateManager: {
+                    getAuthState: vi.fn(),
+                    subscribe: vi.fn(),
+                    unsubscribe: vi.fn(),
+                },
+                closeSession: vi.fn(),
+                options: {
+                    restoreOriginalUri: "",
+                },
+                start: vi.fn(),
+                setOriginalUri: vi.fn(),
+            },
+            authState: mockedAuthState,
+        };
+    };
+    vi.doMock("@okta/okta-react", () => ({
+        useOktaAuth: () => mockedOktaAuth(),
+    }));
+    setupResponseForTanstackRouter();
+    setupTranslations();
+    setupMatchMediaMock();
+    setupResizeObserver();
+    setupIntersectionObserver();
+};
+
+/**
+ * Mocks the `react-virtualized-auto-sizer` component for testing
+ * environments.
+ *
+ * Provides fixed dimensions (600x600) so tests don't need real DOM
+ * measurements. Especially useful for components using virtualized lists or
+ * grids.
+ *
+ * Opt-in: the mock is registered via `vi.doMock` so it is
+ * NOT hoisted and only takes effect once `setupReactVirtualizedAutoSizer()`
+ * is called from a test setup file. Tests that need the real component (or
+ * their own mock) are unaffected unless they explicitly call this.
+ *
+ * @example
+ * import { setupReactVirtualizedAutoSizer } from '@trackunit/react-vite-test-setup';
+ * setupReactVirtualizedAutoSizer();
+ */
+const setupReactVirtualizedAutoSizer = () => {
+    vi.doMock("react-virtualized-auto-sizer", () => ({ children }) => children({ height: 600, width: 600, scaledWidth: 600, scaledHeight: 600 }));
+};
+
+/**
+ * Mocks the `@tanstack/react-virtual` library for testing environments.
+ *
+ * Replaces `useVirtualizer` with a deterministic implementation that
+ * returns every item (no real DOM virtualisation), so tests can assert on
+ * the full rendered list without worrying about scroll-driven windowing.
+ *
+ * Opt-in: the mock is registered via `vi.doMock` so it is
+ * NOT hoisted and only takes effect once `setupTanstackReactVirtual()` is
+ * called from a test setup file. Tests that need the real virtualizer (or
+ * their own mock) are unaffected unless they explicitly call this.
+ *
+ * @example
+ * import { setupTanstackReactVirtual } from '@trackunit/react-vite-test-setup';
+ * setupTanstackReactVirtual();
+ */
+const setupTanstackReactVirtual = () => {
+    vi.doMock("@tanstack/react-virtual", () => ({
+        useVirtualizer: ({ count }) => ({
+            getVirtualItems: () => {
+                const result = [];
+                for (let i = 0; i < count; i++) {
+                    result.push({
+                        index: i,
+                        start: i * 40,
+                        key: i,
+                        measureRef: () => {
+                            /* noop */
+                        },
+                    });
+                }
+                return result;
+            },
+            getTotalSize: () => count,
+            scrollToIndex: () => {
+                /* noop */
+            },
+            scrollToOffset: () => {
+                /* noop */
+            },
+            scrollToAlign: () => {
+                /* noop */
+            },
+            scrollToItem: () => {
+                /* noop */
+            },
+            resetAfterIndex: () => {
+                /* noop */
+            },
+            resetAfterItem: () => {
+                /* noop */
+            },
+            scrollTo: () => {
+                /* noop */
+            },
+            measure: () => {
+                /* noop */
+            },
+            measureElement: () => 42,
+        }),
+    }));
+};
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// Pin the test process timezone to UTC at module load (before the imports
+// below evaluate, since ESM hoists `import` statements above this assignment
+// only inside this module's body, and Node reads `process.env.TZ` lazily for
+// each new Date). This mirrors what `vitest.preset.js` did for the Vitest setup
+// and keeps Date#toISOString / time-of-day assertions stable across machines.
+// Without this, dev environments with non-UTC TZ produce off-by-an-hour
+// failures in tests that build dates from numeric components (e.g. the
+// `InsightsHelper` ISO-string assertions).
+process.env.TZ = "UTC";
+/**
+ * Mocks the Temporal API to use a fixed time zone for testing.
+ *
+ * This function specifically mocks the Temporal.Now.timeZoneId method from the
+ * Temporal library to always return "Europe/Copenhagen", ensuring consistent
+ * time zone-dependent behavior in tests regardless of where they run.
+ *
+ * Note: the host process timezone is also pinned to UTC at module load via
+ * `process.env.TZ` above, so non-Temporal Date arithmetic is deterministic.
+ *
+ * @example
+ * // In your vitest setup file
+ * import { setupTimeZone } from '@trackunit/react-vite-test-setup';
+ *
+ * setupTimeZone();
+ */
+const setupTimeZone = () => {
+    vi.spyOn(Temporal.Now, "timeZoneId").mockImplementation(function () {
+        return "Europe/Copenhagen";
+    });
+};
+/**
+ * Sets up time, animation, and language-related mocks for testing environments.
+ *
+ * This function configures multiple aspects of the testing environment:
+ * 1. Sets a fixed time zone using setupTimeZone()
+ * 2. Disables React Spring animations for faster, deterministic tests
+ * 3. Overrides setTimeout and setInterval to execute immediately (0ms delay)
+ *
+ * These changes make tests faster and more predictable by eliminating real-time
+ * delays, animations, and time zone dependencies that could cause flaky tests.
+ *
+ * @example
+ * // In your jest setup file
+ * import { setupTimeAndLanguage } from '@trackunit/react-vite-test-setup';
+ *
+ * setupTimeAndLanguage();
+ */
+const setupTimeAndLanguage = () => {
+    setupTimeZone();
+    Globals.assign({
+        skipAnimation: true,
+    });
+    const globalSetTimeout = global.setTimeout;
+    global.ORG_setTimeout = globalSetTimeout;
+    const globalSetInterval = global.setInterval;
+    global.ORG_setInterval = globalSetInterval;
+    global.setTimeout = function testSetTimeout(callback, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    ms, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    ...args) {
+        return globalSetTimeout.apply(this, [callback, 0]);
+    };
+    global.setInterval = function testSetInterval(callback, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    ms, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    ...args) {
+        return globalSetInterval.apply(this, [callback, 0]);
+    };
+};
+
+/**
+ * Sets up Web Streams API polyfills for testing environments.
+ *
+ * Web Streams API polyfills from web-streams-polyfill. These polyfills provide implementations
+ * of modern streaming APIs that may not be available in the Jest/JSDOM testing environment.
+ *
+ * The setup enables testing of components and utilities that rely on the Web Streams API,
+ * such as those that process streaming data or implement custom stream transformations.
+ *
+ * @example
+ * // In your jest setup file
+ * import { setupWebStreams } from '@trackunit/react-vite-test-setup';
+ *
+ * setupWebStreams();
+ */
+const setupWebStreams = () => {
+    Object.assign(global, { TransformStream, WritableStream });
+};
+
+/**
+ * Sets up all available testing mocks in a single function call.
+ *
+ * This convenience function sets up all the test mocks provided by the library:
+ * - Canvas API mocks
+ * - Console error reporting to fail tests (includes automatic CSS parser error suppression)
+ * - Google Maps API and components mocks
+ * - Mapbox GL JS mocks
+ * - React Helmet mocks
+ * - IntersectionObserver mocks
+ * - MatchMedia API mocks
+ * - React Testing Library and Okta authentication mocks
+ * - React Virtualized AutoSizer mocks
+ * - ResizeObserver mocks
+ * - Tanstack React Virtual mocks
+ * - Time and language related mocks (timezone, timers, etc.)
+ * - Translation mocks (i18n)
+ * - Web Streams API mocks
+ *
+ * Using this function is equivalent to calling each setup function individually.
+ *
+ * @param options Configuration options for individual mocks
+ * @param options.failOnConsoleOptions Options for setupFailOnConsole
+ * @example
+ * // In your jest setup file
+ * import { setupAllMocks } from '@trackunit/react-vite-test-setup';
+ *
+ * setupAllMocks();
+ *
+ * // Or with options for specific mocks:
+ * setupAllMocks({
+ *   failOnConsoleOptions: { shouldFailOnWarn: true }
+ * });
+ */
+const setupAllMocks = (options = {}) => {
+    setupFailOnConsole(options.failOnConsoleOptions);
+    setupGoogleMaps();
+    setupMapbox();
+    setupHelmetMock();
+    setupIntersectionObserver();
+    setupMatchMediaMock();
+    setupReactTestingLibrary();
+    setupReactVirtualizedAutoSizer();
+    setupResizeObserver();
+    setupTanstackReactVirtual();
+    setupTimeAndLanguage();
+    setupTranslations();
+    setupWebStreams();
+};
+
+/**
+ * Sets up essential testing mocks with no external library dependencies.
+ *
+ * @param options Configuration options for the mocks
+ */
+const setupBasicMocks = (options = {}) => {
+    setupIntersectionObserver();
+    setupMatchMediaMock();
+    setupResizeObserver();
+    setupWebStreams();
+    // Time and error handling
+    setupTimeAndLanguage();
+    setupFailOnConsole(options.failOnConsoleOptions);
+};
+
+/**
+ * Sets up default testing mocks that cover most common React testing needs.
+ *
+ * This convenience function provides a balanced set of mocks that cover most React
+ * application testing needs. It includes all the basic mocks plus essential React
+ * testing utilities. Specifically, it includes:
+ *
+ * From setupBasicMocks:
+ * - Canvas API mocks
+ * - Console error reporting to fail tests
+ * - IntersectionObserver mocks
+ * - MatchMedia API mocks
+ * - ResizeObserver mocks
+ * - Timer mocks (setTimeout, setInterval)
+ * - Web Streams API mocks
+ *
+ * Plus these additional mocks:
+ * - React Testing Library and Okta authentication mocks
+ * - Translation mocks (i18n)
+ *
+ * This is ideal for most React applications that use i18n translations and need
+ * standard testing environment setup, without requiring specialized mocks for things
+ * like Google Maps or virtualized lists.
+ *
+ * @param options Configuration options for individual mocks
+ * @param options.failOnConsoleOptions Options for setupFailOnConsole
+ * @example
+ * // In your jest setup file
+ * import { setupDefaultMocks } from '@trackunit/react-vite-test-setup';
+ *
+ * setupDefaultMocks();
+ *
+ * // Or with options for specific mocks:
+ * setupDefaultMocks({
+ *   failOnConsoleOptions: { shouldFailOnWarn: true }
+ * });
+ */
+/**
+ * Sets up default testing mocks covering most common React testing scenarios.
+ *
+ * @param options Configuration options for the mocks
+ */
+const setupDefaultMocks = (options = {}) => {
+    // Set up all basic mocks first
+    setupBasicMocks(options);
+    // Add standard React testing utilities
+    setupReactTestingLibrary();
+    setupTranslations();
+};
+
+/**
+ * Mocks the `@tanstack/react-router` library for testing environments.
+ *
+ * Replaces `useNavigate` with a no-op so components that call the
+ * navigation function during a test do not throw outside a router context.
+ *
+ * Opt-in: the mock is registered via `vi.doMock` so it is
+ * NOT hoisted and only takes effect once `setupTanstackReactRouter()` is
+ * called from a test setup file. Tests that need the real `useNavigate`
+ * (or their own mock) are unaffected unless they explicitly call this.
+ *
+ * @example
+ * // In your vitest setup file
+ * import { setupTanstackReactRouter } from '@trackunit/react-vite-test-setup';
+ *
+ * setupTanstackReactRouter();
+ */
+const setupTanstackReactRouter = () => {
+    vi.doMock("@tanstack/react-router", async () => ({
+        ...(await vi.importActual("@tanstack/react-router")),
+        useNavigate: () => () => {
+            /* noop */
+        },
+    }));
+};
+
+export { createMockClickEvent, createMockMapboxMap, setupAllMocks, setupBasicMocks, setupCanvasMock, setupDefaultMocks, setupFailOnConsole, setupGoogleMaps, setupHelmetMock, setupIntersectionObserver, setupMapbox, setupMatchMediaMock, setupReactTestingLibrary, setupReactVirtualizedAutoSizer, setupResizeObserver, setupTanstackReactRouter, setupTanstackReactVirtual, setupTimeAndLanguage, setupTimeZone, setupTranslations, setupWebStreams };