Skip to content

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

10.8 KB
Raw Blame
import { describe, it, expect } from "vitest";
import { UmamiImportMapper } from "./umami.js";

// Valid RFC4122 v4 UUID (variant nibble 8) — zod v3's .uuid() is lax, but
// stricter validators must still accept the happy-path fixtures.
const TEST_SESSION_ID = "9e3779b1-3c6e-4362-8a4f-81b88c81f013";

function makeEvent(overrides: Record<string, string> = {}) {
  return {
    session_id: TEST_SESSION_ID,
    hostname: "example.com",
    browser: "chrome",
    os: "Windows 10",
    device: "desktop",
    screen: "1920x1080",
    language: "en-US",
    country: "US",
    region: "US-CA",
    city: "San Francisco",
    url_path: "/blog/post-1",
    url_query: "utm_source=google",
    referrer_path: "/search",
    referrer_domain: "google.com",
    page_title: "Post 1",
    event_type: "1",
    event_name: "",
    distinct_id: "visitor-1",
    created_at: "2024-06-15 14:30:00",
    ...overrides,
  };
}

describe("UmamiImportMapper", () => {
  describe("transform", () => {
    it("should transform a valid pageview event", () => {
      const events = [makeEvent()];
      const result = UmamiImportMapper.transform(events, 1, "import-1");

      expect(result).toHaveLength(1);
      expect(result[0]).toMatchObject({
        site_id: 1,
        timestamp: "2024-06-15T14:30:00.000Z",
        session_id: TEST_SESSION_ID,
        user_id: "visitor-1",
        hostname: "example.com",
        pathname: "/blog/post-1",
        querystring: "?utm_source=google",
        url_parameters: { utm_source: "google" },
        page_title: "Post 1",
        referrer: "https://google.com/search",
        browser: "Chrome",
        browser_version: "",
        operating_system: "Windows",
        operating_system_version: "10",
        language: "en-US",
        country: "US",
        region: "US-CA",
        city: "San Francisco",
        lat: 0,
        lon: 0,
        screen_width: 1920,
        screen_height: 1080,
        device_type: "Desktop",
        type: "pageview",
        event_name: "",
        props: {},
        import_id: "import-1",
      });
      expect(result[0].channel).toBeTruthy();
    });

    it("should transform a custom event", () => {
      const events = [makeEvent({ event_type: "2", event_name: "SignUp" })];
      const result = UmamiImportMapper.transform(events, 2, "import-2");

      expect(result).toHaveLength(1);
      expect(result[0].type).toBe("custom_event");
      expect(result[0].event_name).toBe("SignUp");
    });

    it("should clear the event name for pageviews", () => {
      const events = [makeEvent({ event_type: "1", event_name: "ShouldBeDropped" })];
      const result = UmamiImportMapper.transform(events, 1, "import-1");
      expect(result).toHaveLength(1);
      expect(result[0].event_name).toBe("");
    });

    describe("browser/os/device normalization", () => {
      it("should map known browser keys case-insensitively", () => {
        const cases: Array<[string, string]> = [
          ["chrome", "Chrome"],
          ["Chrome", "Chrome"],
          ["crios", "Mobile Chrome"],
          ["edge-chromium", "Edge"],
          ["ios", "Mobile Safari"],
          ["samsung", "Samsung Internet"],
        ];
        for (const [input, expected] of cases) {
          const result = UmamiImportMapper.transform([makeEvent({ browser: input })], 1, "i");
          expect(result[0].browser).toBe(expected);
        }
      });

      it("should pass through unknown browsers unchanged", () => {
        const result = UmamiImportMapper.transform([makeEvent({ browser: "brave" })], 1, "i");
        expect(result[0].browser).toBe("brave");
      });

      it("should map known operating systems", () => {
        const cases: Array<[string, string]> = [
          ["Windows 10", "Windows"],
          ["Mac OS", "macOS"],
          ["iOS", "iOS"],
          ["Android OS", "Android"],
          ["Linux", "Linux"],
          ["Chrome OS", "Chrome OS"],
        ];
        for (const [input, expected] of cases) {
          const result = UmamiImportMapper.transform([makeEvent({ os: input })], 1, "i");
          expect(result[0].operating_system).toBe(expected);
        }
      });

      it("should map device types to Desktop/Mobile", () => {
        const cases: Array<[string, string]> = [
          ["desktop", "Desktop"],
          ["laptop", "Desktop"],
          ["mobile", "Mobile"],
          ["tablet", "Mobile"],
        ];
        for (const [input, expected] of cases) {
          const result = UmamiImportMapper.transform([makeEvent({ device: input })], 1, "i");
          expect(result[0].device_type).toBe(expected);
        }
      });
    });

    describe("operating_system_version derivation", () => {
      // Regression test: deriveOsVersion must match case-insensitively like the
      // os map does — raw umami exports vary in casing.
      it("should derive version 10 from any casing of Windows 10", () => {
        for (const os of ["Windows 10", "windows 10", "WINDOWS 10"]) {
          const result = UmamiImportMapper.transform([makeEvent({ os })], 1, "i");
          expect(result).toHaveLength(1);
          expect(result[0].operating_system_version).toBe("10");
          expect(result[0].operating_system).toBe("Windows");
        }
      });

      it("should derive version 7 from any casing of Windows 7", () => {
        for (const os of ["Windows 7", "windows 7", "wInDoWs 7"]) {
          const result = UmamiImportMapper.transform([makeEvent({ os })], 1, "i");
          expect(result).toHaveLength(1);
          expect(result[0].operating_system_version).toBe("7");
        }
      });

      it("should derive an empty version for all other operating systems", () => {
        for (const os of ["Mac OS", "Linux", "Android OS", "Windows Server 2003", "iOS"]) {
          const result = UmamiImportMapper.transform([makeEvent({ os })], 1, "i");
          expect(result[0].operating_system_version).toBe("");
        }
      });
    });

    describe("screen parsing", () => {
      it("should split screen into width and height", () => {
        const result = UmamiImportMapper.transform([makeEvent({ screen: "390x844" })], 1, "i");
        expect(result[0].screen_width).toBe(390);
        expect(result[0].screen_height).toBe(844);
      });

      it("should default to 0x0 for an empty screen", () => {
        const result = UmamiImportMapper.transform([makeEvent({ screen: "" })], 1, "i");
        expect(result[0].screen_width).toBe(0);
        expect(result[0].screen_height).toBe(0);
      });
    });

    describe("querystring handling", () => {
      it("should prefix a non-empty url_query with ?", () => {
        const result = UmamiImportMapper.transform([makeEvent({ url_query: "a=1&b=2" })], 1, "i");
        expect(result[0].querystring).toBe("?a=1&b=2");
        expect(result[0].url_parameters).toEqual({ a: "1", b: "2" });
      });

      it("should leave an empty url_query empty", () => {
        const result = UmamiImportMapper.transform([makeEvent({ url_query: "" })], 1, "i");
        expect(result[0].querystring).toBe("");
        expect(result[0].url_parameters).toEqual({});
      });
    });

    describe("referrer handling", () => {
      it("should prefix the referrer domain with https:// and append the path", () => {
        const result = UmamiImportMapper.transform(
          [makeEvent({ referrer_domain: "news.ycombinator.com", referrer_path: "/item" })],
          1,
          "i"
        );
        expect(result[0].referrer).toBe("https://news.ycombinator.com/item");
      });

      it("should clear self-referrers", () => {
        const result = UmamiImportMapper.transform(
          [makeEvent({ referrer_domain: "example.com", referrer_path: "/previous" })],
          1,
          "i"
        );
        expect(result[0].referrer).toBe("");
      });

      it("should clear self-referrers when the hostname has a www prefix", () => {
        const result = UmamiImportMapper.transform(
          [
            makeEvent({
              hostname: "www.example.com",
              referrer_domain: "example.com",
              referrer_path: "/previous",
            }),
          ],
          1,
          "i"
        );
        expect(result[0].referrer).toBe("");
      });

      it("should leave the referrer empty when domain and path are empty", () => {
        const result = UmamiImportMapper.transform([makeEvent({ referrer_domain: "", referrer_path: "" })], 1, "i");
        expect(result[0].referrer).toBe("");
      });
    });

    describe("invalid rows", () => {
      it("should drop rows with an invalid session uuid", () => {
        const result = UmamiImportMapper.transform([makeEvent({ session_id: "not-a-uuid" })], 1, "i");
        expect(result).toHaveLength(0);
      });

      it("should drop rows with an invalid country code", () => {
        for (const country of ["USA", "us", "1A"]) {
          const result = UmamiImportMapper.transform([makeEvent({ country })], 1, "i");
          expect(result).toHaveLength(0);
        }
      });

      it("should allow an empty country code", () => {
        const result = UmamiImportMapper.transform([makeEvent({ country: "" })], 1, "i");
        expect(result).toHaveLength(1);
        expect(result[0].country).toBe("");
      });

      it("drops a well-shaped impossible date without losing the rest of the batch", () => {
        const result = UmamiImportMapper.transform(
          [
            makeEvent({ created_at: "2024-06-15 14:30:00" }),
            makeEvent({ created_at: "2024-02-31 12:00:00" }),
            makeEvent({ created_at: "2024-06-16 09:00:00" }),
          ],
          1,
          "i"
        );
        expect(result.map(row => row.timestamp)).toEqual(["2024-06-15T14:30:00.000Z", "2024-06-16T09:00:00.000Z"]);
      });

      it("should drop rows with an invalid timestamp format", () => {
        for (const created_at of [
          "2024-06-15T14:30:00", // ISO "T" separator
          "2024-13-01 10:00:00", // invalid month
          "2024-06-15 24:30:00", // invalid hour
          "not-a-date",
          "",
        ]) {
          const result = UmamiImportMapper.transform([makeEvent({ created_at })], 1, "i");
          expect(result).toHaveLength(0);
        }
      });

      it("should drop rows with a malformed screen value", () => {
        const result = UmamiImportMapper.transform([makeEvent({ screen: "1920*1080" })], 1, "i");
        expect(result).toHaveLength(0);
      });

      it("should keep valid rows when mixed with invalid ones", () => {
        const events = [
          makeEvent({ url_path: "/valid" }),
          makeEvent({ session_id: "bad" }),
          makeEvent({ url_path: "/also-valid" }),
        ];
        const result = UmamiImportMapper.transform(events, 1, "i");
        expect(result).toHaveLength(2);
        expect(result.map(e => e.pathname)).toEqual(["/valid", "/also-valid"]);
      });
    });

    it("should return empty array for empty input", () => {
      expect(UmamiImportMapper.transform([], 1, "i")).toHaveLength(0);
    });
  });
});