🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
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]);
});
});
});