@probat/react 0.4.1 → 0.4.3

package/src/__tests__/useTrack.test.tsx

@@ -0,0 +1,682 @@
+import React, { StrictMode } from "react";
+import { render, screen, fireEvent, act } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { ProbatProviderClient } from "../components/ProbatProviderClient";
+import { useTrack } from "../hooks/useTrack";
+import { resetDedupe } from "../utils/dedupeStorage";
+import { resetInstanceIdState } from "../utils/stableInstanceId";
+import { MockIntersectionObserver } from "./setup";
+
+// ── Test component that uses useTrack ──────────────────────────────────────
+
+function TrackedContent(props: {
+    experimentId: string;
+    variantKey: string;
+    componentInstanceId?: string;
+    impression?: boolean;
+    click?: boolean;
+    children: React.ReactNode;
+}) {
+    const { experimentId, variantKey, componentInstanceId, impression, click, children } = props;
+    const trackRef = useTrack({
+        experimentId,
+        variantKey,
+        componentInstanceId,
+        impression,
+        click,
+    });
+
+    return (
+        <div ref={trackRef as React.RefObject<HTMLDivElement>} data-testid="tracked">
+            {children}
+        </div>
+    );
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function wrapper({ children }: { children: React.ReactNode }) {
+    return (
+        <ProbatProviderClient customerId="test-customer-id" host="https://api.test.com">
+            {children}
+        </ProbatProviderClient>
+    );
+}
+
+// ── Setup / teardown ───────────────────────────────────────────────────────
+
+beforeEach(() => {
+    vi.useFakeTimers();
+    localStorage.clear();
+    sessionStorage.clear();
+    resetDedupe();
+    resetInstanceIdState();
+    MockIntersectionObserver._reset();
+    vi.restoreAllMocks();
+    global.fetch = vi.fn().mockResolvedValue({ ok: true });
+});
+
+afterEach(() => {
+    vi.useRealTimers();
+});
+
+// ── Impression tracking ───────────────────────────────────────────────────
+
+describe("useTrack impression tracking", () => {
+    it("sends impression after >=250ms of 50% visibility", async () => {
+        const fetchMock = global.fetch as ReturnType<typeof vi.fn>;
+
+        render(
+            <TrackedContent experimentId="vis-exp" variantKey="ai_v1">
+                <div>Visible</div>
+            </TrackedContent>,
+            { wrapper }
+        );
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        const observer = MockIntersectionObserver._instances[MockIntersectionObserver._instances.length - 1];
+        expect(observer).toBeDefined();
+
+        act(() => observer._trigger(true));
+
+        // Before 250ms
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(200);
+        });
+
+        let impressionCalls = fetchMock.mock.calls.filter((c: any[]) => {
+            if (typeof c[0] !== "string" || !c[0].includes("/experiment/metrics")) return false;
+            const body = JSON.parse(c[1]?.body || "{}");
+            return body.event === "$experiment_exposure";
+        });
+        expect(impressionCalls.length).toBe(0);
+
+        // After 250ms
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(100);
+        });
+
+        impressionCalls = fetchMock.mock.calls.filter((c: any[]) => {
+            if (typeof c[0] !== "string" || !c[0].includes("/experiment/metrics")) return false;
+            const body = JSON.parse(c[1]?.body || "{}");
+            return body.event === "$experiment_exposure";
+        });
+        expect(impressionCalls.length).toBe(1);
+
+        const payload = JSON.parse(impressionCalls[0][1].body);
+        expect(payload.properties.experiment_id).toBe("vis-exp");
+        expect(payload.properties.variant_key).toBe("ai_v1");
+    });
+
+    it("cancels impression if element leaves viewport before 250ms", async () => {
+        const fetchMock = global.fetch as ReturnType<typeof vi.fn>;
+
+        render(
+            <TrackedContent experimentId="cancel-exp" variantKey="control">
+                <div>Short Visit</div>
+            </TrackedContent>,
+            { wrapper }
+        );
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        const observer = MockIntersectionObserver._instances[MockIntersectionObserver._instances.length - 1];
+
+        act(() => observer._trigger(true));
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(100);
+        });
+
+        act(() => observer._trigger(false));
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(300);
+        });
+
+        const impressionCalls = fetchMock.mock.calls.filter((c: any[]) => {
+            if (typeof c[0] !== "string" || !c[0].includes("/experiment/metrics")) return false;
+            const body = JSON.parse(c[1]?.body || "{}");
+            return body.event === "$experiment_exposure";
+        });
+        expect(impressionCalls.length).toBe(0);
+    });
+
+    it("dedupes impressions across unmount/remount with stable componentInstanceId", async () => {
+        const fetchMock = global.fetch as ReturnType<typeof vi.fn>;
+
+        const { unmount } = render(
+            <TrackedContent experimentId="dedupe-exp" variantKey="control" componentInstanceId="stable-inst">
+                <div>Content</div>
+            </TrackedContent>,
+            { wrapper }
+        );
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        const observer1 = MockIntersectionObserver._instances[0];
+        if (observer1) {
+            act(() => observer1._trigger(true));
+            await act(async () => {
+                await vi.advanceTimersByTimeAsync(300);
+            });
+        }
+
+        const metricCalls1 = fetchMock.mock.calls.filter(
+            (c: any[]) => typeof c[0] === "string" && c[0].includes("/experiment/metrics")
+        );
+
+        unmount();
+
+        render(
+            <TrackedContent experimentId="dedupe-exp" variantKey="control" componentInstanceId="stable-inst">
+                <div>Content</div>
+            </TrackedContent>,
+            { wrapper }
+        );
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        const observer2 = MockIntersectionObserver._instances[MockIntersectionObserver._instances.length - 1];
+        if (observer2) {
+            act(() => observer2._trigger(true));
+            await act(async () => {
+                await vi.advanceTimersByTimeAsync(300);
+            });
+        }
+
+        const metricCalls2 = fetchMock.mock.calls.filter(
+            (c: any[]) => typeof c[0] === "string" && c[0].includes("/experiment/metrics")
+        );
+
+        expect(metricCalls2.length).toBe(metricCalls1.length);
+    });
+
+    it("does not track impressions when impression=false", async () => {
+        const fetchMock = global.fetch as ReturnType<typeof vi.fn>;
+
+        render(
+            <TrackedContent experimentId="no-imp-exp" variantKey="ai_v1" impression={false}>
+                <div>No Track</div>
+            </TrackedContent>,
+            { wrapper }
+        );
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        // No observer should be created for this component
+        const impressionCalls = fetchMock.mock.calls.filter((c: any[]) => {
+            if (typeof c[0] !== "string" || !c[0].includes("/experiment/metrics")) return false;
+            const body = JSON.parse(c[1]?.body || "{}");
+            return body.event === "$experiment_exposure";
+        });
+        expect(impressionCalls.length).toBe(0);
+    });
+});
+
+// ── Click tracking ────────────────────────────────────────────────────────
+
+describe("useTrack click tracking", () => {
+    it("captures clicks on data-probat-click='primary'", async () => {
+        const fetchMock = global.fetch as ReturnType<typeof vi.fn>;
+
+        render(
+            <TrackedContent experimentId="click-exp" variantKey="control">
+                <span data-probat-click="primary" data-testid="primary-el">
+                    Primary CTA
+                </span>
+            </TrackedContent>,
+            { wrapper }
+        );
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        fireEvent.click(screen.getByTestId("primary-el"));
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        const clickCalls = fetchMock.mock.calls.filter((c: any[]) => {
+            if (typeof c[0] !== "string" || !c[0].includes("/experiment/metrics")) return false;
+            const body = JSON.parse(c[1]?.body || "{}");
+            return body.event === "$experiment_click";
+        });
+
+        expect(clickCalls.length).toBe(1);
+        const payload = JSON.parse(clickCalls[0][1].body);
+        expect(payload.properties.click_is_primary).toBe(true);
+        expect(payload.properties.click_target_text).toBe("Primary CTA");
+    });
+
+    it("captures clicks on <button>", async () => {
+        const fetchMock = global.fetch as ReturnType<typeof vi.fn>;
+
+        render(
+            <TrackedContent experimentId="click-exp" variantKey="control">
+                <button data-testid="btn">Click Me</button>
+            </TrackedContent>,
+            { wrapper }
+        );
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        fireEvent.click(screen.getByTestId("btn"));
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        const clickCalls = fetchMock.mock.calls.filter((c: any[]) => {
+            if (typeof c[0] !== "string" || !c[0].includes("/experiment/metrics")) return false;
+            const body = JSON.parse(c[1]?.body || "{}");
+            return body.event === "$experiment_click";
+        });
+
+        expect(clickCalls.length).toBe(1);
+        const payload = JSON.parse(clickCalls[0][1].body);
+        expect(payload.properties.click_target_tag).toBe("BUTTON");
+        expect(payload.properties.click_is_primary).toBe(false);
+    });
+
+    it("ignores clicks on non-interactive elements", async () => {
+        const fetchMock = global.fetch as ReturnType<typeof vi.fn>;
+
+        render(
+            <TrackedContent experimentId="click-exp" variantKey="control">
+                <p data-testid="paragraph">Just text</p>
+            </TrackedContent>,
+            { wrapper }
+        );
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        fireEvent.click(screen.getByTestId("paragraph"));
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        const clickCalls = fetchMock.mock.calls.filter((c: any[]) => {
+            if (typeof c[0] !== "string" || !c[0].includes("/experiment/metrics")) return false;
+            const body = JSON.parse(c[1]?.body || "{}");
+            return body.event === "$experiment_click";
+        });
+
+        expect(clickCalls.length).toBe(0);
+    });
+
+    it("does not track clicks when click=false", async () => {
+        const fetchMock = global.fetch as ReturnType<typeof vi.fn>;
+
+        render(
+            <TrackedContent experimentId="no-click-exp" variantKey="control" click={false}>
+                <button data-testid="btn">Click Me</button>
+            </TrackedContent>,
+            { wrapper }
+        );
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        fireEvent.click(screen.getByTestId("btn"));
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        const clickCalls = fetchMock.mock.calls.filter((c: any[]) => {
+            if (typeof c[0] !== "string" || !c[0].includes("/experiment/metrics")) return false;
+            const body = JSON.parse(c[1]?.body || "{}");
+            return body.event === "$experiment_click";
+        });
+
+        expect(clickCalls.length).toBe(0);
+    });
+});
+
+// ── Event payload fields ──────────────────────────────────────────────────
+
+describe("useTrack event payload", () => {
+    it("includes experiment_id, variant_key, and distinct_id in events", async () => {
+        const fetchMock = global.fetch as ReturnType<typeof vi.fn>;
+
+        render(
+            <TrackedContent experimentId="payload-exp" variantKey="ai_v1" componentInstanceId="hero-cta">
+                <div>Content</div>
+            </TrackedContent>,
+            { wrapper }
+        );
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        const observer = MockIntersectionObserver._instances[MockIntersectionObserver._instances.length - 1];
+        act(() => observer._trigger(true));
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(300);
+        });
+
+        const impressionCalls = fetchMock.mock.calls.filter((c: any[]) => {
+            if (typeof c[0] !== "string" || !c[0].includes("/experiment/metrics")) return false;
+            const body = JSON.parse(c[1]?.body || "{}");
+            return body.event === "$experiment_exposure";
+        });
+
+        expect(impressionCalls.length).toBe(1);
+        const payload = JSON.parse(impressionCalls[0][1].body);
+
+        expect(payload.properties.experiment_id).toBe("payload-exp");
+        expect(payload.properties.variant_key).toBe("ai_v1");
+        expect(payload.properties.component_instance_id).toBe("hero-cta");
+        expect(payload.properties.distinct_id).toBe("test-customer-id");
+        expect(payload.properties.source).toBe("react-sdk");
+        expect(payload.properties.captured_at).toBeDefined();
+    });
+});
+
+// ── Customer mode ─────────────────────────────────────────────────────────
+
+function CustomerTrackedContent(props: {
+    experimentId: string;
+    customerId?: string;
+    componentInstanceId?: string;
+    impression?: boolean;
+    click?: boolean;
+    children: React.ReactNode;
+}) {
+    const { experimentId, customerId, componentInstanceId, impression, click, children } = props;
+    const trackRef = useTrack({
+        experimentId,
+        customerId,
+        componentInstanceId,
+        impression,
+        click,
+    });
+
+    return (
+        <div ref={trackRef as React.RefObject<HTMLDivElement>} data-testid="tracked">
+            {children}
+        </div>
+    );
+}
+
+describe("useTrack customer mode", () => {
+    it("sends impression without variant_key but with distinct_id + experiment_id", async () => {
+        const fetchMock = global.fetch as ReturnType<typeof vi.fn>;
+
+        render(
+            <CustomerTrackedContent experimentId="cust-exp" customerId="user_42">
+                <div>Content</div>
+            </CustomerTrackedContent>,
+            { wrapper }
+        );
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        const observer = MockIntersectionObserver._instances[MockIntersectionObserver._instances.length - 1];
+        act(() => observer._trigger(true));
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(300);
+        });
+
+        const impressionCalls = fetchMock.mock.calls.filter((c: any[]) => {
+            if (typeof c[0] !== "string" || !c[0].includes("/experiment/metrics")) return false;
+            const body = JSON.parse(c[1]?.body || "{}");
+            return body.event === "$experiment_exposure";
+        });
+
+        expect(impressionCalls.length).toBe(1);
+        const payload = JSON.parse(impressionCalls[0][1].body);
+        expect(payload.properties.experiment_id).toBe("cust-exp");
+        expect(payload.properties.distinct_id).toBe("user_42");
+        expect(payload.properties).not.toHaveProperty("variant_key");
+    });
+
+    it("dedupes impressions using customerId in the dedupe key", async () => {
+        const fetchMock = global.fetch as ReturnType<typeof vi.fn>;
+
+        const { unmount } = render(
+            <CustomerTrackedContent experimentId="cust-dedupe" customerId="user_42" componentInstanceId="stable">
+                <div>Content</div>
+            </CustomerTrackedContent>,
+            { wrapper }
+        );
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        const observer1 = MockIntersectionObserver._instances[MockIntersectionObserver._instances.length - 1];
+        act(() => observer1._trigger(true));
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(300);
+        });
+
+        const callsAfterFirst = fetchMock.mock.calls.filter((c: any[]) => {
+            if (typeof c[0] !== "string" || !c[0].includes("/experiment/metrics")) return false;
+            const body = JSON.parse(c[1]?.body || "{}");
+            return body.event === "$experiment_exposure";
+        });
+        expect(callsAfterFirst.length).toBe(1);
+
+        unmount();
+
+        render(
+            <CustomerTrackedContent experimentId="cust-dedupe" customerId="user_42" componentInstanceId="stable">
+                <div>Content</div>
+            </CustomerTrackedContent>,
+            { wrapper }
+        );
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        const observer2 = MockIntersectionObserver._instances[MockIntersectionObserver._instances.length - 1];
+        act(() => observer2._trigger(true));
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(300);
+        });
+
+        const callsAfterSecond = fetchMock.mock.calls.filter((c: any[]) => {
+            if (typeof c[0] !== "string" || !c[0].includes("/experiment/metrics")) return false;
+            const body = JSON.parse(c[1]?.body || "{}");
+            return body.event === "$experiment_exposure";
+        });
+        // Should still be 1 -- deduped
+        expect(callsAfterSecond.length).toBe(1);
+    });
+
+    it("tracks clicks in customer mode", async () => {
+        const fetchMock = global.fetch as ReturnType<typeof vi.fn>;
+
+        render(
+            <CustomerTrackedContent experimentId="cust-click" customerId="user_42">
+                <button data-testid="btn">Buy</button>
+            </CustomerTrackedContent>,
+            { wrapper }
+        );
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        fireEvent.click(screen.getByTestId("btn"));
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        const clickCalls = fetchMock.mock.calls.filter((c: any[]) => {
+            if (typeof c[0] !== "string" || !c[0].includes("/experiment/metrics")) return false;
+            const body = JSON.parse(c[1]?.body || "{}");
+            return body.event === "$experiment_click";
+        });
+
+        expect(clickCalls.length).toBe(1);
+        const payload = JSON.parse(clickCalls[0][1].body);
+        expect(payload.properties.experiment_id).toBe("cust-click");
+        expect(payload.properties.distinct_id).toBe("user_42");
+        expect(payload.properties).not.toHaveProperty("variant_key");
+    });
+
+    it("falls back to provider customerId when customerId option is omitted", async () => {
+        const fetchMock = global.fetch as ReturnType<typeof vi.fn>;
+
+        render(
+            <CustomerTrackedContent experimentId="cust-fallback">
+                <div>Content</div>
+            </CustomerTrackedContent>,
+            { wrapper }
+        );
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        const observer = MockIntersectionObserver._instances[MockIntersectionObserver._instances.length - 1];
+        act(() => observer._trigger(true));
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(300);
+        });
+
+        const impressionCalls = fetchMock.mock.calls.filter((c: any[]) => {
+            if (typeof c[0] !== "string" || !c[0].includes("/experiment/metrics")) return false;
+            const body = JSON.parse(c[1]?.body || "{}");
+            return body.event === "$experiment_exposure";
+        });
+
+        expect(impressionCalls.length).toBe(1);
+        const payload = JSON.parse(impressionCalls[0][1].body);
+        // Falls back to provider's customerId ("test-customer-id" from wrapper)
+        expect(payload.properties.distinct_id).toBe("test-customer-id");
+        expect(payload.properties).not.toHaveProperty("variant_key");
+    });
+
+    it("warns when neither variantKey nor customerId is available", async () => {
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+        function NoCustomerProvider({ children }: { children: React.ReactNode }) {
+            return (
+                <ProbatProviderClient host="https://api.test.com">
+                    {children}
+                </ProbatProviderClient>
+            );
+        }
+
+        render(
+            <NoCustomerProvider>
+                <CustomerTrackedContent experimentId="no-id-exp" impression={true}>
+                    <div>Content</div>
+                </CustomerTrackedContent>
+            </NoCustomerProvider>
+        );
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        // debug is false by default, so the warning should not fire
+        expect(warnSpy).not.toHaveBeenCalled();
+
+        warnSpy.mockRestore();
+    });
+
+    it("warns when debug=true and no customerId available", async () => {
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+        function NoCustomerProvider({ children }: { children: React.ReactNode }) {
+            return (
+                <ProbatProviderClient host="https://api.test.com">
+                    {children}
+                </ProbatProviderClient>
+            );
+        }
+
+        function DebugCustomerTrackedContent() {
+            const trackRef = useTrack({
+                experimentId: "warn-exp",
+                debug: true,
+            });
+            return (
+                <div ref={trackRef as React.RefObject<HTMLDivElement>} data-testid="tracked">
+                    Content
+                </div>
+            );
+        }
+
+        render(
+            <NoCustomerProvider>
+                <DebugCustomerTrackedContent />
+            </NoCustomerProvider>
+        );
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        expect(warnSpy).toHaveBeenCalledWith(
+            expect.stringContaining("no customerId")
+        );
+
+        warnSpy.mockRestore();
+    });
+});
+
+// ── StrictMode safety ─────────────────────────────────────────────────────
+
+describe("useTrack StrictMode safety", () => {
+    it("does not double-count impressions in StrictMode", async () => {
+        const fetchMock = global.fetch as ReturnType<typeof vi.fn>;
+
+        render(
+            <StrictMode>
+                <ProbatProviderClient customerId="test-customer-id" host="https://api.test.com">
+                    <TrackedContent experimentId="strict-exp" variantKey="control">
+                        <div>Strict Content</div>
+                    </TrackedContent>
+                </ProbatProviderClient>
+            </StrictMode>
+        );
+
+        await act(async () => {
+            await vi.runAllTimersAsync();
+        });
+
+        for (const obs of MockIntersectionObserver._instances) {
+            act(() => obs._trigger(true));
+        }
+
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(300);
+        });
+
+        const impressionCalls = fetchMock.mock.calls.filter((c: any[]) => {
+            if (typeof c[0] !== "string" || !c[0].includes("/experiment/metrics")) return false;
+            const body = JSON.parse(c[1]?.body || "{}");
+            return body.event === "$experiment_exposure";
+        });
+
+        expect(impressionCalls.length).toBe(1);
+    });
+});