fangke/sdk/test/stay.test.ts

import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
import { Transport } from "../src/transport";
import { mergeConfig } from "../src/config";
import { PageSession } from "../src/page";
import { startStayTracking } from "../src/stay";

// 停留区间制（spec §1.4 / 设计 1.4）：一条 page_stay = 一段连续有效活动的不重叠区间。
// 时钟模型：区间长度只用单调时钟（performance.now——整体 stub 为受控 perfNow，与
// fake 墙钟锁步：step() 每秒先把 perf 拨到当秒再走 fake timer，tick 在 fake 第 N 秒
// 触发时读到 N*1000）；active_from/active_to 为展示 epoch ms（cut 时单一墙钟读数换算，
// from/to 同基 → to-from 恒等于 active_ms，墙钟中途回拨不产生倒置区间）。
// 活动判定沿用 events.ts 冻结语义：可见 + Date.now() 距最近交互 <30s。
// 注意：startStayTracking 安装的监听/interval 跨用例存留（匿名无法摘除），每用例
// 独立 siteId 并按 site 过滤批次（沿 events.test.ts / page.test.ts 模式）；
// happy-dom 的 navigator.sendBeacon 会发真实网络请求——beforeEach 整体 stubGlobal。

const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
/** fake 墙钟基点：perf 0 对应的 epoch ms（setSystemTime 同值 → active_from/to 断言 = TO+perf） */
const TO = Date.UTC(2026, 8, 18, 10, 0, 0);

let fetchMock: ReturnType<typeof vi.fn>;
let beacon: ReturnType<typeof vi.fn>;
let perfNow = 0;

function stubEnv() {
  beacon = vi.fn().mockReturnValue(true);
  vi.stubGlobal("navigator", {
    userAgent:
      "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
    language: "zh-CN",
    sendBeacon: beacon,
  });
  // performance 整体受控：now=perfNow（由 step 锁步推进，单调不受墙钟回拨影响）；
  // timeOrigin=TO 备查——实现按 cut 时 Date.now()-performance.now() 偏移换算 epoch
  vi.stubGlobal("performance", {
    now: () => perfNow,
    timeOrigin: TO,
    getEntriesByType: () => [],
  });
}

function mkTransport(siteId: string) {
  // flushMs 拉大到 24h：区间结算只入队，flush 全部由用例显式驱动
  return new Transport(
    mergeConfig({ siteId, endpoint: "/api/collect/batch", batchSize: 50, flushMs: 86_400_000 })
  );
}

/** 锁步推进 1 秒：先把 perfNow 拨到当秒（perf 单调，独立于墙钟），再走 1s fake
 *  timer——tick 在 fake 第 N 秒触发时 performance.now() 恰为 N*1000。
 *  必须逐秒走：一次跳 N 秒会让沿途所有 tick 读到跳表后的 perfNow，回溯开区出错。 */
function step() {
  perfNow += 1000;
  vi.advanceTimersByTime(1000);
}
function advance(ms: number) {
  for (let i = 0; i < ms / 1000; i++) step();
}

/** beacon 路径（hidden/pagehide 结算的 flush(true)）事件汇总 */
async function beaconEvents(siteId: string) {
  const out: Record<string, any>[] = [];
  for (const [, blob] of beacon.mock.calls as unknown as [string, Blob][]) {
    const body = JSON.parse(await blob.text());
    if (body.site_id === siteId) out.push(...body.events);
  }
  return out;
}

/** fetch 路径（显式 t.flush()）事件汇总 */
function fetchedEvents(siteId: string) {
  const out: Record<string, any>[] = [];
  for (const call of fetchMock.mock.calls as unknown as [string, RequestInit][]) {
    const body = JSON.parse(call[1].body as string);
    if (body.site_id === siteId) out.push(...body.events);
  }
  return out;
}

function staysOf(events: Record<string, any>[]) {
  return events.filter((e) => e.event_name === "page_stay");
}

describe("stay / startStayTracking", () => {
  beforeEach(() => {
    localStorage.clear();
    vi.useFakeTimers();
    vi.setSystemTime(new Date(TO));
    perfNow = 0;
    fetchMock = vi.fn().mockResolvedValue({ ok: true, status: 200 } as Response);
    vi.stubGlobal("fetch", fetchMock);
    stubEnv();
  });
  afterEach(() => {
    vi.unstubAllGlobals();
    vi.useRealTimers(); // 旧 tracker 的 1s/15s interval 挂在各自 fake clock 上，随钟一起废弃
    delete (document as { hidden?: boolean }).hidden; // 还原 happy-dom 原型 getter
  });

  it("15s 连续活动切 4 条相邻区间：[from,to] 不重叠、flush_reason=periodic", () => {
    window.history.pushState({}, "", "/stay-60s");
    const t = mkTransport("stay-cut");
    const ps = new PageSession(t);
    startStayTracking(t, ps);

    for (let s = 1; s <= 60; s++) {
      // 每 10s 一次交互维持 30s 活动窗（加载本身计一次活动）
      if (s % 10 === 0) document.dispatchEvent(new Event("pointerdown"));
      step();
    }

    t.flush();
    const stays = staysOf(fetchedEvents("stay-cut"));
    expect(stays).toHaveLength(4); // 60s / 15s = 4 条
    expect(stays.map((e) => e.properties.active_ms)).toEqual([15000, 15000, 15000, 15000]);
    expect(stays.map((e) => [e.properties.active_from, e.properties.active_to])).toEqual([
      [TO, TO + 15_000],
      [TO + 15_000, TO + 30_000],
      [TO + 30_000, TO + 45_000],
      [TO + 45_000, TO + 60_000],
    ]); // 相邻区间首尾相接不重叠（服务端按 page_id 并集拼回总时长）
    expect(stays.every((e) => e.properties.flush_reason === "periodic")).toBe(true);
  });

  it("hidden 结算当前区间；pagehide 紧随不重发（共享结算状态）", async () => {
    const t = mkTransport("stay-hidden");
    const ps = new PageSession(t);
    startStayTracking(t, ps);
    advance(10_000); // 区间 [0,10s)

    Object.defineProperty(document, "hidden", { value: true, configurable: true });
    document.dispatchEvent(new Event("visibilitychange")); // cut(hidden) + flush(true)
    advance(5_000); // hidden 期间无活动 tick
    window.dispatchEvent(new Event("pagehide")); // 紧随其后：幂等，不重发

    const stays = staysOf(await beaconEvents("stay-hidden"));
    expect(stays).toHaveLength(1);
    expect(stays[0].properties.active_ms).toBe(10_000);
    expect(stays[0].properties.active_from).toBe(TO);
    expect(stays[0].properties.active_to).toBe(TO + 10_000);
    expect(stays[0].properties.flush_reason).toBe("hidden");
  });

  it("hidden 期间不累计；恢复 visible 后活动从恢复点开新区间", async () => {
    const t = mkTransport("stay-resume");
    const ps = new PageSession(t);
    startStayTracking(t, ps, { stayIntervalMs: 60_000 }); // 观察 single 恢复区间（15s 切分另测）
    advance(8_000); // 段 1：[0,8s)
    Object.defineProperty(document, "hidden", { value: true, configurable: true });
    document.dispatchEvent(new Event("visibilitychange"));

    advance(22_000); // hidden 至 t=30s：不计入
    delete (document as { hidden?: boolean }).hidden;
    document.dispatchEvent(new Event("visibilitychange")); // 恢复可见（本身不开区间）
    advance(9_000); // t=39s：可见但距上次交互 39s ≥30s → 仍不累计
    document.dispatchEvent(new Event("pointerdown")); // 活动恢复
    advance(11_000); // t=50s：新区间自恢复点起
    Object.defineProperty(document, "hidden", { value: true, configurable: true });
    document.dispatchEvent(new Event("visibilitychange")); // 段 2 结算

    const stays = staysOf(await beaconEvents("stay-resume"));
    expect(stays).toHaveLength(2);
    expect(stays[0].properties.active_ms).toBe(8_000); // 恰为隐藏前区间
    expect(stays[1].properties.active_ms).toBe(11_000); // [39s,50s]，从恢复点重新起算
    expect(stays[1].properties.active_from).toBe(TO + 39_000); // 起点=活动恢复时刻
    // 隐藏/空闲跨度 [8s,39s] 不落入任何区间
  });

  it("单调时钟：墙钟回拨不影响区间长度（active_ms 恒为 perf 差）", async () => {
    const t = mkTransport("stay-clock");
    const ps = new PageSession(t);
    startStayTracking(t, ps, { stayIntervalMs: 60_000 }); // 单区间观察（不 15s 切）
    advance(5_000);
    document.dispatchEvent(new Event("pointerdown"));
    advance(15_000); // t=20s，区间 open

    vi.setSystemTime(new Date(TO - 8 * 60_000)); // 系统墙钟回拨 8 分钟
    advance(20_000); // t=40s：perf 照常单调推进
    window.dispatchEvent(new Event("pagehide"));

    const stays = staysOf(await beaconEvents("stay-clock"));
    expect(stays).toHaveLength(1);
    expect(stays[0].properties.active_ms).toBe(40_000); // [0,40s]：回拨不改区间长度
    expect(stays[0].properties.active_to - stays[0].properties.active_from).toBe(40_000); // from/to 同基，恒正不倒置
  });

  it("flush_reason 正确：pagehide（直接离开）与 route_change（SPA 切段）", async () => {
    // pagehide：无 hidden 前置的直接离开
    let t = mkTransport("stay-pagehide");
    let ps = new PageSession(t);
    startStayTracking(t, ps);
    advance(7_000);
    window.dispatchEvent(new Event("pagehide"));
    expect(staysOf(await beaconEvents("stay-pagehide")).map((e) => e.properties.flush_reason)).toEqual([
      "pagehide",
    ]);

    // route_change：SPA 路由切段（PageSession.close → onClose 结算；页面仍在台前，周期 flush 送）
    t = mkTransport("stay-route");
    ps = new PageSession(t);
    startStayTracking(t, ps);
    advance(7_000);
    ps.close();
    t.flush();
    expect(staysOf(fetchedEvents("stay-route")).map((e) => e.properties.flush_reason)).toEqual([
      "route_change",
    ]);
  });

  it("入队事件结构：active_from/active_to/active_ms/path/measurement_version=2 + 顶层归属", () => {
    window.history.pushState({}, "", "/stay-shape");
    const t = mkTransport("stay-shape");
    const ps = new PageSession(t);
    startStayTracking(t, ps);
    advance(16_000); // 一次周期切分 [0,15s]

    t.flush();
    const stay = staysOf(fetchedEvents("stay-shape"))[0];
    expect(stay.event_id).toMatch(UUID_RE);
    expect(stay.event_name).toBe("page_stay");
    expect(stay.occurred_at).toMatch(/^\d{4}-\d{2}-\d{2}T/);
    expect(stay.path).toBe("/stay-shape");
    expect(stay.title).toBe(document.title);
    // properties 恰为服务端 page_stay 白名单六键（constants.py EVENT_PROP_WHITELIST）
    expect(stay.properties).toEqual({
      active_ms: 15_000,
      path: "/stay-shape", // 供服务端"page_stay 合并进相邻 page_view"
      active_from: TO,
      active_to: TO + 15_000,
      flush_reason: "periodic",
      measurement_version: "2",
    });
    // 顶层归属（events 形态 + Attribution 展开，同 PageSession.push）
    expect(stay.site_id).toBe("stay-shape");
    expect(stay.visitor_id).toMatch(UUID_RE);
    expect(stay.session_id).toMatch(UUID_RE);
    expect(stay.page_id).toBe(ps.pageId);
    expect(stay.seq).toBe(1); // 直接构造的段内首事件
    expect(stay.purpose).toBe(null); // V1.1 预留从快照展开
    expect(stay.epoch).toBe(null);
    expect(stay.grant_ref).toBe(null);
  });

  it("失活悬置：单次交互后空闲 → 区间在 30s 活动窗末端 cut(periodic)，之后不再累计", async () => {
    const t = mkTransport("stay-idle");
    const ps = new PageSession(t);
    startStayTracking(t, ps, { stayIntervalMs: 60_000 });
    document.dispatchEvent(new Event("pointerdown")); // 仅此一次交互（t=0）
    advance(35_000); // tick 于 t=30s 起 Date.now()-lastAct≥30s → 悬置
    window.dispatchEvent(new Event("pagehide")); // 已悬置：无新区间，只补 flush

    const stays = staysOf(await beaconEvents("stay-idle"));
    expect(stays).toHaveLength(1);
    expect(stays[0].properties.active_ms).toBe(30_000); // 活动窗 [0,30s] 整段
    expect(stays[0].properties.flush_reason).toBe("periodic"); // 失活悬置属周期结算
  });

  it("stayIntervalMs 边界守卫：NaN 回落默认 15s；0 钳制下限 ≥1s（防高频 cut 灌入）", () => {
    // NaN：非 nullish，绕过 ?? 默认值——须回落 15s 语义（16s 恰一条 [0,15s] periodic）
    let t = mkTransport("stay-nan");
    let ps = new PageSession(t);
    startStayTracking(t, ps, { stayIntervalMs: NaN });
    advance(16_000);
    t.flush();
    let stays = staysOf(fetchedEvents("stay-nan"));
    expect(stays).toHaveLength(1);
    expect(stays[0].properties.active_ms).toBe(15_000);
    expect(stays[0].properties.flush_reason).toBe("periodic");

    // 0：无守卫时 setInterval(0) 每毫秒 cut 灌入事件；钳到下限后 5s 内切分有界。
    // 首秒 tick/cut 同瞬触发顺序不定——断言保持顺序无关：条数有界、区间 ≥1s、相邻不重叠
    t = mkTransport("stay-zero");
    ps = new PageSession(t);
    startStayTracking(t, ps, { stayIntervalMs: 0 });
    advance(5_000);
    t.flush();
    stays = staysOf(fetchedEvents("stay-zero")).sort(
      (a, b) => a.properties.active_from - b.properties.active_from
    );
    expect(stays.length).toBeGreaterThanOrEqual(1);
    expect(stays.length).toBeLessThanOrEqual(5); // 下限 1s 一刀 → 至多 5 条
    for (const s of stays) expect(s.properties.active_ms).toBeGreaterThanOrEqual(1_000);
    for (let i = 1; i < stays.length; i++) {
      expect(stays[i].properties.active_from).toBeGreaterThanOrEqual(stays[i - 1].properties.active_to); // lastCutEnd 钳制不重叠
    }
  });
});