Skip to content

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

9.1 KB
Raw Blame
import { describe, expect, it } from "vitest";
import { normalizeUserAgentForIdentity } from "./normalizeUserAgent.js";

/**
 * Every fixture below is a real user agent captured off production ingestion
 * (op.gg's Rybbit instance, 2026-08-18), so the pairs that must collapse are
 * pairs that actually did split a visitor in two.
 */
const UA = {
  opggElectron251:
    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) opgg-electron-app/2.5.1 Chrome/132.0.6834.210 Electron/34.5.7 Safari/537.36",
  opggElectron253:
    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) opgg-electron-app/2.5.3 Chrome/142.0.7444.265 Electron/39.8.13 Safari/537.36",
  chromeWin150:
    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/150.0.0.0 Safari/537.36",
  chromeWin151:
    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36",
  edgeWin151:
    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36 Edg/151.0.0.0",
  safariIos1857:
    "Mozilla/5.0 (iPhone; CPU iPhone OS 18_7 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.7 Mobile/15E148 Safari/604.1",
  safariIos266:
    "Mozilla/5.0 (iPhone; CPU iPhone OS 26_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.6 Mobile/15E148 Safari/604.1",
  safariIpad266:
    "Mozilla/5.0 (iPad; CPU OS 26_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.6 Mobile/15E148 Safari/604.1",
  chromeIos:
    "Mozilla/5.0 (iPhone; CPU iPhone OS 26_0_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/151.0.7922.112 Mobile/15E148 Safari/604.1",
  chromeIosPatched:
    "Mozilla/5.0 (iPhone; CPU iPhone OS 26_0_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/151.0.7922.140 Mobile/15E148 Safari/604.1",
  macSafari:
    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15",
  androidS928N:
    "Mozilla/5.0 (Linux; Android 15; SM-S928N Build/AP3A.240905.015) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Mobile Safari/537.36",
  androidA536N:
    "Mozilla/5.0 (Linux; Android 15; SM-A536N Build/AP3A.240905.015) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Mobile Safari/537.36",
  reactNative:
    "Mozilla/5.0 (iPhone; CPU iPhone OS 26_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) RybbitReactNative/0.1.1 8.0.14",
  reactNativeBumped:
    "Mozilla/5.0 (iPhone; CPU iPhone OS 26_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) RybbitReactNative/0.2.0 8.1.0",
  firefox: "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:153.0) Gecko/20100101 Firefox/153.0",
  firefoxNext: "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:154.0) Gecko/20100101 Firefox/154.0",
  // In-app browsers put hardware identifiers in the same slash-delimited slot a
  // version normally occupies, which an over-eager rule will happily destroy.
  fbIosPhone12:
    "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 [FBAN/FBIOS;FBDV/iPhone12,8;FBAV/440.0.0.32.108]",
  fbIosPhone14:
    "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 [FBAN/FBIOS;FBDV/iPhone14,8;FBAV/440.0.0.32.108]",
  fbIosPhone12Updated:
    "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 [FBAN/FBIOS;FBDV/iPhone12,8;FBAV/441.0.0.28.90]",
  fbAndroidJ320F:
    "Mozilla/5.0 (Linux; Android 9; SM-J320F) AppleWebKit/537.36 [FBAN/EMA;FBDV/SM-J320F;FBCA/armeabi-v7a:armeabi;FBAV/239.0.0.10.109]",
  fbAndroidG930F:
    "Mozilla/5.0 (Linux; Android 9; SM-G930F) AppleWebKit/537.36 [FBAN/EMA;FBDV/SM-G930F;FBCA/armeabi-v7a:armeabi;FBAV/239.0.0.10.109]",
  // Two different handsets whose *model names* contain a dotted number.
  nokia61Plus:
    "Mozilla/5.0 (Linux; Android 10; Nokia 6.1 Plus Build/QKQ1.190828.002; wv) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.7778.178 Mobile Safari/537.36",
  nokia83Plus:
    "Mozilla/5.0 (Linux; Android 10; Nokia 8.3 Plus Build/QKQ1.190828.002; wv) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.7778.178 Mobile Safari/537.36",
};

const same = (a: string, b: string) => expect(normalizeUserAgentForIdentity(a)).toBe(normalizeUserAgentForIdentity(b));
const differs = (a: string, b: string) =>
  expect(normalizeUserAgentForIdentity(a)).not.toBe(normalizeUserAgentForIdentity(b));

describe("normalizeUserAgentForIdentity", () => {
  describe("survives updates", () => {
    // The regression this exists for: op.gg's auto-updater flipped the whole
    // install base to 2.5.3 inside a day (the diagnosed boundary was 2.5.2 β†’
    // 2.5.3), re-minting every id. The captured pair below spans the same
    // three-token move β€” app, Chromium and Electron versions all at once.
    it("collapses an Electron app update (app, Chromium and Electron all bumped)", () => {
      same(UA.opggElectron251, UA.opggElectron253);
    });

    it("collapses a Chrome major bump", () => same(UA.chromeWin150, UA.chromeWin151));

    it("collapses an iOS point release, which moves both the OS and Safari tokens", () => {
      same(UA.safariIos1857, UA.safariIos266);
    });

    // Chrome on iOS does not do UA reduction, so every patch used to reset it.
    it("collapses a Chrome-on-iOS patch", () => same(UA.chromeIos, UA.chromeIosPatched));

    it("collapses a Firefox bump, including the rv: revision", () => same(UA.firefox, UA.firefoxNext));

    it("collapses a React Native app bump, including the bare trailing version", () => {
      same(UA.reactNative, UA.reactNativeBumped);
    });
  });

  describe("keeps distinct devices distinct", () => {
    it("separates browser families on the same OS", () => differs(UA.chromeWin151, UA.edgeWin151));
    it("separates Firefox from Chrome", () => differs(UA.chromeWin151, UA.firefox));
    it("separates operating systems", () => differs(UA.chromeWin151, UA.macSafari));
    it("separates iPhone from iPad", () => differs(UA.safariIos266, UA.safariIpad266));
    it("separates Safari from Chrome on the same iPhone", () => differs(UA.safariIos266, UA.chromeIos));
    it("separates a native app from the browser on the same OS", () => {
      differs(UA.reactNative, UA.safariIos266);
    });

    // Android model strings carry digits but never change under the user, so
    // they are entropy worth keeping.
    it("keeps Android device models apart", () => differs(UA.androidS928N, UA.androidA536N));
  });

  describe("keeps hardware identifiers, which never change under the user", () => {
    // Regression: an earlier rule elided any slash value containing a digit,
    // turning `FBDV/iPhone12,8` into `FBDV/#,8` and fusing every iPhone model
    // that shared a point release.
    it("keeps the iOS device model in a Facebook in-app user agent", () => {
      expect(normalizeUserAgentForIdentity(UA.fbIosPhone12)).toContain("FBDV/iPhone12,8");
    });

    it("separates two iPhone models behind the same in-app browser", () => {
      differs(UA.fbIosPhone12, UA.fbIosPhone14);
    });

    it("still collapses the in-app browser's own version bump", () => {
      same(UA.fbIosPhone12, UA.fbIosPhone12Updated);
    });

    it("keeps the Android model and CPU ABI in a Facebook in-app user agent", () => {
      const normalized = normalizeUserAgentForIdentity(UA.fbAndroidJ320F);
      expect(normalized).toContain("FBDV/SM-J320F");
      expect(normalized).toContain("FBCA/armeabi-v7a:armeabi");
    });

    it("separates two Android models behind the same in-app browser", () => {
      differs(UA.fbAndroidJ320F, UA.fbAndroidG930F);
    });

    // Regression: a two-group bare-version rule read the `6.1` in `Nokia 6.1
    // Plus` as a version and merged it with every other dotted Nokia.
    it("keeps a dotted marketing model name", () => {
      expect(normalizeUserAgentForIdentity(UA.nokia61Plus)).toContain("Nokia 6.1 Plus");
    });

    it("separates two handsets whose model names differ only in their digits", () => {
      differs(UA.nokia61Plus, UA.nokia83Plus);
    });
  });

  describe("mechanics", () => {
    it("elides every version token in a representative desktop UA", () => {
      expect(normalizeUserAgentForIdentity(UA.chromeWin151)).toBe(
        "Mozilla/# (Windows NT #; Win64; x64) AppleWebKit/# (KHTML, like Gecko) Chrome/# Safari/#"
      );
    });

    it("keeps the Android model while eliding the OS and build", () => {
      expect(normalizeUserAgentForIdentity(UA.androidS928N)).toBe(
        "Mozilla/# (Linux; Android #; SM-S928N Build/#) AppleWebKit/# (KHTML, like Gecko) Chrome/# Mobile Safari/#"
      );
    });

    it("is idempotent, so a normalized value re-normalizes to itself", () => {
      for (const ua of Object.values(UA)) {
        const once = normalizeUserAgentForIdentity(ua);
        expect(normalizeUserAgentForIdentity(once)).toBe(once);
      }
    });

    it("passes an empty user agent through untouched", () => {
      expect(normalizeUserAgentForIdentity("")).toBe("");
    });

    it("leaves a version-free user agent alone", () => {
      expect(normalizeUserAgentForIdentity("Mediapartners-Google")).toBe("Mediapartners-Google");
    });
  });
});