Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

22.6 KB
Raw Blame
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
import { Tracker } from "./tracking.js";
import { ScriptConfig } from "./types.js";
import { resetBotScoreCacheForTests } from "./botSignals.js";

// Mock fetch globally
global.fetch = vi.fn();

describe("Tracker", () => {
  let tracker: Tracker;
  let config: ScriptConfig;
  let mockLocation: any;

  beforeEach(() => {
    resetBotScoreCacheForTests();

    // Reset fetch mock
    vi.mocked(global.fetch).mockReset();
    vi.mocked(global.fetch).mockResolvedValue({} as Response);

    // Mock localStorage
    const localStorageMock = {
      getItem: vi.fn(),
      setItem: vi.fn(),
      removeItem: vi.fn(),
    };
    Object.defineProperty(window, "localStorage", {
      value: localStorageMock,
      writable: true,
    });

    // Mock window properties
    mockLocation = {
      href: "https://example.com/page?query=test",
      hostname: "example.com",
      pathname: "/page",
      search: "?query=test",
      hash: "",
    };

    Object.defineProperty(window, "location", {
      value: mockLocation,
      configurable: true,
      writable: true,
    });

    // Mock URL constructor to use our mockLocation
    global.URL = vi.fn().mockImplementation(() => ({
      hostname: mockLocation.hostname,
      pathname: mockLocation.pathname,
      search: mockLocation.search,
      hash: mockLocation.hash,
      searchParams: { entries: () => [["query", "test"]] },
    })) as any;

    Object.defineProperty(screen, "width", {
      value: 1920,
      writable: true,
    });

    Object.defineProperty(screen, "height", {
      value: 1080,
      writable: true,
    });

    Object.defineProperty(navigator, "language", {
      value: "en-US",
      writable: true,
    });

    Object.defineProperty(document, "title", {
      value: "Test Page",
      writable: true,
    });

    Object.defineProperty(document, "referrer", {
      value: "https://google.com",
      writable: true,
    });

    Object.defineProperty(HTMLCanvasElement.prototype, "getContext", {
      value: vi.fn(() => null),
      configurable: true,
    });

    config = {
      namespace: "rybbit",
      analyticsHost: "https://analytics.example.com",
      siteId: "123",
      visitorId: "visitor-123",
      debounceDuration: 0,
      autoTrackPageview: true,
      autoTrackSpa: true,
      trackQuerystring: true,
      trackUrlFragments: false,
      trackOutbound: true,
      trackErrors: false,
      enableWebVitals: false,
      enableSessionReplay: false,
      sessionReplayBatchSize: 50,
      sessionReplayBatchInterval: 5000,
      sessionReplayMaskTextSelectors: [],
      skipPatterns: [],
      maskPatterns: [],
      trackButtonClicks: false,
      trackCopy: false,
      trackFormInteractions: false,
      tag: "",
      featureFlagsEnabled: false,
      featureFlags: {},
    };

    tracker = new Tracker(config);
  });

  afterEach(() => {
    vi.clearAllMocks();
  });

  describe("createBasePayload", () => {
    it("should create base payload with all required fields", () => {
      const payload = tracker.createBasePayload();

      expect(payload).toEqual({
        site_id: "123",
        hostname: "example.com",
        pathname: "/page",
        querystring: "?query=test",
        screenWidth: 1920,
        screenHeight: 1080,
        language: "en-US",
        page_title: "Test Page",
        referrer: "https://google.com",
        _bs: expect.any(Number),
        _bsm: expect.any(Number),
      });
    });

    it("should handle hash-based routing", () => {
      mockLocation.hash = "#/dashboard/users";
      const payload = tracker.createBasePayload();
      expect(payload?.pathname).toBe("/dashboard/users");
    });

    it("handles hashbang routes without changing slash-prefixed hash routes", () => {
      mockLocation.hash = "#!/shipping";
      expect(tracker.createBasePayload()?.pathname).toBe("/shipping");
    });

    it("ignores ordinary fragments by default", () => {
      mockLocation.pathname = "/checkout/";
      mockLocation.hash = "#shipping";
      expect(tracker.createBasePayload()?.pathname).toBe("/checkout/");
    });

    it("preserves checkout stages when URL fragment tracking is enabled", () => {
      config.trackUrlFragments = true;
      tracker = new Tracker(config);
      mockLocation.pathname = "/checkout/";
      mockLocation.hash = "#shipping";
      expect(tracker.createBasePayload()?.pathname).toBe("/checkout/#shipping");
      mockLocation.hash = "#payment";
      expect(tracker.createBasePayload()?.pathname).toBe("/checkout/#payment");
    });

    it("should skip tracking for matching skip patterns", () => {
      config.skipPatterns = ["/admin/**", "/api/**"];
      tracker = new Tracker(config);

      mockLocation.pathname = "/admin/settings";
      const payload = tracker.createBasePayload();
      expect(payload).toBeNull();
    });

    it("should apply mask patterns", () => {
      config.maskPatterns = ["/user/*/profile"];
      tracker = new Tracker(config);

      mockLocation.pathname = "/user/123/profile";
      const payload = tracker.createBasePayload();
      expect(payload?.pathname).toBe("/user/*/profile");
    });

    it("should support regex skip and mask patterns", () => {
      config.skipPatterns = ["re:^/private/.*$"];
      config.maskPatterns = ["re:^/user/\\d+/profile$"];
      tracker = new Tracker(config);

      mockLocation.pathname = "/private/settings";
      expect(tracker.createBasePayload()).toBeNull();

      mockLocation.pathname = "/user/123/profile";
      const payload = tracker.createBasePayload();
      expect(payload?.pathname).toBe("re:^/user/\\d+/profile$");
    });

    it("should exclude querystring when disabled", () => {
      config.trackQuerystring = false;
      tracker = new Tracker(config);

      const payload = tracker.createBasePayload();
      expect(payload?.querystring).toBe("");
    });

    it("cuts a long title and referrer to the server's limits without splitting a character", () => {
      Object.defineProperty(document, "title", { value: `${"t".repeat(511)}😀`, writable: true });
      Object.defineProperty(document, "referrer", { value: `https://google.com/${"r".repeat(3000)}`, writable: true });

      const payload = tracker.createBasePayload()!;

      expect(payload.referrer).toHaveLength(2048);
      expect(payload.page_title).toBe("t".repeat(511));
    });

    it("sends a long path and query string whole, for the server's exclusions to see", () => {
      // The server cuts them for storage only after matching Site Exclusions.
      mockLocation.pathname = `/${"p".repeat(3000)}`;
      mockLocation.search = `?padding=${"q".repeat(3000)}&preview=1`;

      const payload = tracker.createBasePayload()!;

      expect(payload.pathname).toBe(mockLocation.pathname);
      expect(payload.querystring).toBe(mockLocation.search);
    });

    it("should include user ID when set", () => {
      vi.mocked(window.localStorage.getItem).mockReturnValue("user-123");
      tracker = new Tracker(config);

      const payload = tracker.createBasePayload();
      expect(payload?.user_id).toBe("user-123");
    });

    it("should include evaluated feature flags in payloads", () => {
      config.featureFlags = {
        new_checkout: {
          key: "new_checkout",
          value: true,
          flagType: "boolean",
          payload: { copy: "Try it now" },
          version: 1,
          reason: "rollout",
          matched: true,
          rolloutPercentage: 100,
        },
      };
      tracker = new Tracker(config);

      const payload = tracker.createBasePayload();
      expect(payload?.feature_flags).toEqual({ new_checkout: "true" });
      expect(tracker.getFeatureFlagPayload("new_checkout")).toEqual({ copy: "Try it now" });
    });

    it("should treat an unassigned multivariate flag as absent", () => {
      config.featureFlags = {
        checkout_test: {
          key: "checkout_test",
          value: false,
          flagType: "multivariate",
          version: 2,
          reason: "disabled",
          matched: false,
          rolloutPercentage: 100,
        },
      };
      tracker = new Tracker(config);

      expect(tracker.getFeatureFlag("checkout_test", "control")).toBe("control");
      expect(tracker.getFeatureFlags()).not.toHaveProperty("checkout_test");
      expect(tracker.createBasePayload()?.feature_flags).toBeUndefined();
      expect(global.fetch).not.toHaveBeenCalledWith(
        expect.anything(),
        expect.objectContaining({ body: expect.stringContaining("feature_flag_exposure") })
      );
    });

    it("should keep false as a real value for boolean flags", () => {
      config.featureFlags = {
        dark_mode: {
          key: "dark_mode",
          value: false,
          flagType: "boolean",
          version: 1,
          reason: "fallthrough",
          matched: false,
          rolloutPercentage: 50,
        },
      };
      tracker = new Tracker(config);

      expect(tracker.getFeatureFlag("dark_mode", true)).toBe(false);
      expect(tracker.createBasePayload()?.feature_flags).toEqual({ dark_mode: "false" });
    });

    it("should send the visitor id only when feature flags are enabled", () => {
      expect(tracker.createBasePayload()?.visitor_id).toBeUndefined();

      config.featureFlagsEnabled = true;
      tracker = new Tracker(config);

      expect(tracker.createBasePayload()?.visitor_id).toBe("visitor-123");
    });
  });

  describe("tracking methods", () => {
    it("should track pageview", async () => {
      tracker.trackPageview();

      expect(global.fetch).toHaveBeenCalledWith(
        "https://analytics.example.com/track",
        expect.objectContaining({
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: expect.stringContaining('"type":"pageview"'),
          mode: "cors",
          keepalive: true,
        })
      );
    });

    it("should track custom event", async () => {
      tracker.trackEvent("button_click", { button: "submit" });

      expect(global.fetch).toHaveBeenCalledWith(
        "https://analytics.example.com/track",
        expect.objectContaining({
          body: expect.stringContaining('"type":"custom_event"'),
        })
      );

      const body = JSON.parse(vi.mocked(global.fetch).mock.calls[0][1]!.body as string);
      expect(body.event_name).toBe("button_click");
      expect(body.properties).toBe(JSON.stringify({ button: "submit" }));
    });

    it("should track feature flag exposure once when a flag is read", () => {
      config.featureFlags = {
        new_checkout: {
          key: "new_checkout",
          value: true,
          flagType: "boolean",
          version: 1,
          reason: "rollout",
          matched: true,
          rolloutPercentage: 100,
        },
      };
      tracker = new Tracker(config);
      vi.mocked(global.fetch).mockClear();

      expect(tracker.getFeatureFlag("new_checkout", false)).toBe(true);
      expect(tracker.getFeatureFlag("new_checkout", false)).toBe(true);

      expect(global.fetch).toHaveBeenCalledTimes(1);
      const body = JSON.parse(vi.mocked(global.fetch).mock.calls[0][1]!.body as string);
      expect(body.type).toBe("custom_event");
      expect(body.event_name).toBe("feature_flag_exposure");
      expect(JSON.parse(body.properties)).toMatchObject({
        key: "new_checkout",
        value: "true",
        version: 1,
        reason: "rollout",
      });
    });

    it("should validate custom event name", () => {
      const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});

      tracker.trackEvent("", {});
      expect(global.fetch).not.toHaveBeenCalled();
      expect(consoleSpy).toHaveBeenCalledWith("Event name is required and must be a string for custom events");

      consoleSpy.mockRestore();
    });

    it("should track outbound link", async () => {
      tracker.trackOutbound("https://external.com", "External Link", "_blank");

      const body = JSON.parse(vi.mocked(global.fetch).mock.calls[0][1]!.body as string);
      expect(body.type).toBe("outbound");
      expect(body.properties).toBe(
        JSON.stringify({
          url: "https://external.com",
          text: "External Link",
          target: "_blank",
        })
      );
    });

    it("fits outbound properties within the server's limit", () => {
      const url = `https://external.com/?ref=${"a".repeat(3000)}`;
      tracker.trackOutbound(url, "card text ".repeat(500), "_blank");

      const body = JSON.parse(vi.mocked(global.fetch).mock.calls[0][1]!.body as string);
      const properties = JSON.parse(body.properties);
      expect(body.properties.length).toBeLessThanOrEqual(2048);
      expect(properties.text).toHaveLength(500);
      expect(properties.target).toBe("_blank");
      expect(url.startsWith(properties.url)).toBe(true);
    });

    it("should track web vitals", async () => {
      const vitals = {
        lcp: 2500,
        cls: 0.1,
        inp: 200,
        fcp: 1800,
        ttfb: 800,
      };

      tracker.trackWebVitals(vitals);

      const body = JSON.parse(vi.mocked(global.fetch).mock.calls[0][1]!.body as string);
      expect(body.type).toBe("performance");
      expect(body.event_name).toBe("web-vitals");
      expect(body.lcp).toBe(2500);
      expect(body.cls).toBe(0.1);
    });

    it("should handle fetch errors gracefully", async () => {
      const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
      vi.mocked(global.fetch).mockRejectedValue(new Error("Network error"));

      tracker.trackPageview();

      // Wait for async operation
      await new Promise(resolve => setTimeout(resolve, 0));

      expect(consoleSpy).toHaveBeenCalledWith("Failed to send tracking data:", expect.any(Error));

      consoleSpy.mockRestore();
    });

    describe("error tracking", () => {
      it("should track first-party errors", () => {
        // Enable error tracking for this test
        const errorConfig = { ...config, trackErrors: true };
        const tracker = new Tracker(errorConfig);
        const sendSpy = vi.spyOn(tracker, "sendTrackingData").mockResolvedValue();

        const error = new Error("Test error");
        error.stack = "Error: Test error\n    at https://example.com/app.js:10:5";

        tracker.trackError(error, {
          filename: "https://example.com/app.js",
          lineno: 10,
          colno: 5,
        });

        expect(sendSpy).toHaveBeenCalledWith(
          expect.objectContaining({
            type: "error",
            event_name: "Error",
            properties: expect.stringContaining("Test error"),
          })
        );
      });

      it("should filter out third-party errors by filename", () => {
        const errorConfig = { ...config, trackErrors: true };
        const tracker = new Tracker(errorConfig);
        const sendSpy = vi.spyOn(tracker, "sendTrackingData").mockResolvedValue();

        // Mock window.location.origin to ensure we have a proper origin for comparison
        Object.defineProperty(window, "location", {
          value: {
            ...mockLocation,
            origin: "https://example.com",
          },
          configurable: true,
          writable: true,
        });

        const error = new Error("Third party error");
        // Clear the stack to avoid test environment paths interfering
        error.stack = undefined;

        tracker.trackError(error, {
          filename: "https://ads.google.com/script.js",
          lineno: 1,
          colno: 1,
        });

        expect(sendSpy).not.toHaveBeenCalled();
      });

      it("should filter out third-party errors by stack trace", () => {
        const errorConfig = { ...config, trackErrors: true };
        const tracker = new Tracker(errorConfig);
        const sendSpy = vi.spyOn(tracker, "sendTrackingData").mockResolvedValue();

        const error = new Error("Third party error");
        error.stack = "Error: Third party error\n    at https://ads.google.com/script.js:1:1";

        tracker.trackError(error, {
          lineno: 1,
          colno: 1,
        });

        expect(sendSpy).not.toHaveBeenCalled();
      });

      it("should track errors with unknown origin (e.g., NetworkError)", () => {
        const errorConfig = { ...config, trackErrors: true };
        const tracker = new Tracker(errorConfig);
        const sendSpy = vi.spyOn(tracker, "sendTrackingData").mockResolvedValue();

        const error = new Error("NetworkError when attempting to fetch resource");
        error.name = "TypeError";
        // Clear stack to avoid test environment paths
        error.stack = undefined;

        tracker.trackError(error, {
          type: "unhandledrejection",
        });

        expect(sendSpy).toHaveBeenCalledWith(
          expect.objectContaining({
            type: "error",
            event_name: "TypeError",
            properties: expect.stringContaining("NetworkError"),
          })
        );
      });

      it("should handle invalid filename URLs gracefully", () => {
        const errorConfig = { ...config, trackErrors: true };
        const tracker = new Tracker(errorConfig);
        const sendSpy = vi.spyOn(tracker, "sendTrackingData").mockResolvedValue();

        const error = new Error("Test error");
        error.stack = "Error: Test error\n    at https://example.com/app.js:10:5";

        tracker.trackError(error, {
          filename: "invalid-url",
          lineno: 10,
          colno: 5,
        });

        // Should fall back to stack trace check and track the error
        expect(sendSpy).toHaveBeenCalledWith(
          expect.objectContaining({
            type: "error",
            event_name: "Error",
            properties: expect.stringContaining("Test error"),
          })
        );
      });
    });
  });

  describe("user identification", () => {
    it("should identify user", () => {
      tracker.identify("user-456");

      expect(window.localStorage.setItem).toHaveBeenCalledWith(`${config.namespace}-user-id`, "user-456");
      expect(tracker.getUserId()).toBe("user-456");
    });

    it("should validate user ID", () => {
      const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});

      tracker.identify("");
      expect(window.localStorage.setItem).not.toHaveBeenCalled();
      expect(consoleSpy).toHaveBeenCalledWith("User ID must be a non-empty string");

      consoleSpy.mockRestore();
    });

    it("should clear user ID", () => {
      const updateReplayUserId = vi.fn();
      (
        tracker as unknown as { sessionReplayRecorder: { updateUserId: (userId: string) => void } }
      ).sessionReplayRecorder = {
        updateUserId: updateReplayUserId,
      };

      tracker.identify("user-789");
      tracker.clearUserId();

      expect(window.localStorage.removeItem).toHaveBeenCalledWith(`${config.namespace}-user-id`);
      expect(tracker.getUserId()).toBeNull();
      expect(updateReplayUserId).toHaveBeenLastCalledWith("");
    });

    it("should handle localStorage errors", () => {
      const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
      vi.mocked(window.localStorage.setItem).mockImplementation(() => {
        throw new Error("Storage full");
      });

      tracker.identify("user-123");
      expect(consoleSpy).toHaveBeenCalledWith("Could not persist user ID to localStorage");

      consoleSpy.mockRestore();
    });
  });

  describe("feature flag refresh", () => {
    it("does not evaluate flags on page changes when the site has no flags", () => {
      tracker.onPageChange();

      expect(global.fetch).not.toHaveBeenCalled();
    });

    it("evaluates flags on page changes when feature flags are enabled", () => {
      config.featureFlagsEnabled = true;
      tracker = new Tracker(config);

      tracker.onPageChange();

      expect(global.fetch).toHaveBeenCalledWith(
        "https://analytics.example.com/site/123/feature-flags/evaluate",
        expect.objectContaining({ method: "POST", signal: expect.any(AbortSignal) })
      );
    });
  });

  describe("session replay batches", () => {
    type SendReplayBatch = (batch: unknown) => Promise<unknown>;
    const sendReplayBatch = (batch: unknown) =>
      (tracker as unknown as { sendSessionReplayBatch: SendReplayBatch }).sendSessionReplayBatch(batch);
    const batchOfSize = (bytes: number) => ({
      userId: "",
      events: [{ type: 3, data: "x".repeat(bytes), timestamp: 1 }],
    });

    beforeEach(() => {
      vi.spyOn(console, "error").mockImplementation(() => {});
    });

    it.each([408, 429, 502, 503, 504])(
      "rejects on a %i, which stored nothing, so the recorder retries",
      async status => {
        vi.mocked(global.fetch).mockResolvedValue({ ok: false, status } as Response);

        await expect(sendReplayBatch(batchOfSize(10))).rejects.toThrow(String(status));
      }
    );

    it("does not retry a 500, which may come after the batch's events were stored", async () => {
      vi.mocked(global.fetch).mockResolvedValue({ ok: false, status: 500 } as Response);

      await expect(sendReplayBatch(batchOfSize(10))).resolves.toBeUndefined();
    });

    it("drops a batch the server refuses as invalid instead of retrying it", async () => {
      vi.mocked(global.fetch).mockResolvedValue({ ok: false, status: 400 } as Response);

      await expect(sendReplayBatch(batchOfSize(10))).resolves.toBeUndefined();
    });

    it("passes the server's stop signal back to the recorder", async () => {
      vi.mocked(global.fetch).mockResolvedValue({
        ok: true,
        status: 200,
        json: async () => ({ success: true, stopRecording: true }),
      } as Response);

      await expect(sendReplayBatch(batchOfSize(10))).resolves.toEqual({ success: true, stopRecording: true });
    });

    it("sends every batch that fits the shared keepalive budget with keepalive", async () => {
      vi.mocked(global.fetch).mockResolvedValue({ ok: true, status: 200, json: async () => ({}) } as Response);
      const keepaliveOf = (call: number) => vi.mocked(global.fetch).mock.calls[call][1]!.keepalive;

      // An ordinary batch too: one already in flight when the page hides is
      // past the flush that pagehide makes.
      await sendReplayBatch(batchOfSize(10));
      await sendReplayBatch(batchOfSize(60 * 1024));
      expect([keepaliveOf(0), keepaliveOf(1)]).toEqual([true, false]);

      // Two at once: the second would overrun what the page can hold in flight.
      await Promise.all([sendReplayBatch(batchOfSize(30 * 1024)), sendReplayBatch(batchOfSize(30 * 1024))]);
      expect([keepaliveOf(2), keepaliveOf(3)]).toEqual([true, false]);

      // Measured in UTF-8 bytes: 20k three-byte characters don't fit.
      await sendReplayBatch(batchOfSize(0));
      await sendReplayBatch({ userId: "", events: [{ type: 3, data: "€".repeat(20_000), timestamp: 1 }] });
      expect([keepaliveOf(4), keepaliveOf(5)]).toEqual([true, false]);
    });
  });
});