@solhun/feedback-kit-core 0.1.0

package/src/context.test.ts

@@ -0,0 +1,427 @@
+// DP-253 컨텍스트 수집 검증(통합).
+//
+// 여기 통합 테스트는 "제보를 만들어 → 큐에 넣고 → 어댑터가 전송"까지 실제 경로를 태운
+// 다음, **전송된 페이로드**(JSON 왕복본)를 본다. 내부 객체를 들여다보지 않는 이유는,
+// 받는 쪽에 실제로 도착하는 값이 검증 대상이기 때문이다(직렬화에서 사라지는 필드가 있으면
+// 그것도 여기서 잡힌다).
+//
+// 담당 TC:
+// - TC1  요청이 오간 세션의 제보에는 network 가 담긴다
+// - TC2  경고·에러가 난 세션의 제보에는 logs 가 담긴다
+// - TC5  빈 배열을 상수로 보내지 않는다(수집 미배선 = diagnostics 자체가 null)
+// - TC6  앱 제보에 기기·앱·사용자 컨텍스트가 모두 담긴다
+// - TC7  게스트 사용자도 user 가 식별 가능하게 담긴다
+// - TC10 매핑이 없어도 나머지 컨텍스트는 수집된다(screenPath 만 null)
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { DiagnosticsCollector } from "./diagnostics.js";
+import { FeedbackQueue } from "./queue.js";
+import { buildReport } from "./report.js";
+import type { BuildReportOpts, ReportParts } from "./report.js";
+import type {
+  FeedbackAdapter,
+  FeedbackReport,
+  FeedbackStorage,
+  SubmitResult,
+  FeedbackUser,} from "./types.js";
+
+// ────────────────────────────────────────────────────────────────────────────
+// 테스트 도구
+// ────────────────────────────────────────────────────────────────────────────
+
+const START_TIME = 1_700_000_000_000;
+let clockNow = START_TIME;
+const clock = (): number => clockNow;
+const iso = (n: number): string => new Date(n).toISOString();
+
+type G = Record<string, unknown>;
+const g = globalThis as unknown as G;
+
+function memoryStorage(): FeedbackStorage {
+  const map = new Map<string, string>();
+  return {
+    async get(key) {
+      return map.get(key) ?? null;
+    },
+    async set(key, value) {
+      map.set(key, value);
+    },
+    async remove(key) {
+      map.delete(key);
+    },
+  };
+}
+
+/**
+ * 전송된 페이로드를 그대로 잡아두는 어댑터.
+ * 실제 어댑터와 같이 JSON 직렬화를 거치므로, 여기 잡힌 값이 곧 서버가 받는 값이다.
+ */
+function captureAdapter(): { sent: FeedbackReport[]; adapter: FeedbackAdapter } {
+  const sent: FeedbackReport[] = [];
+  return {
+    sent,
+    adapter: {
+      async submit(report): Promise<SubmitResult> {
+        sent.push(JSON.parse(JSON.stringify(report)) as FeedbackReport);
+        return { ok: true, id: "ann-1", retryable: false, retryAfterMs: null };
+      },
+    },
+  };
+}
+
+const PARTS: ReportParts = {
+  kind: "report",
+  comment: "여기서 버튼이 안 눌린다",
+  priority: "unset",
+  screenshot: null,
+  pin: null,
+  element: null,
+};
+
+/** 제보 하나를 만들어 큐로 전송하고, 서버가 받은 페이로드를 돌려준다. */
+async function sendOnce(
+  opts: Omit<BuildReportOpts, "app" | "sessionId" | "storage" | "now" | "iso"> & {
+    storage?: FeedbackStorage;
+  }
+): Promise<FeedbackReport> {
+  const storage = opts.storage ?? memoryStorage();
+  const { sent, adapter } = captureAdapter();
+  const queue = new FeedbackQueue({ storage, adapter, now: clock, warn: () => {} });
+
+  const report = await buildReport(PARTS, {
+    ...opts,
+    app: "test-app",
+    sessionId: "session-1",
+    storage,
+    now: clock,
+    iso,
+  });
+  const outcome = await queue.submit(report);
+
+  expect(outcome.delivered).toBe(true);
+  expect(sent).toHaveLength(1);
+  return sent[0] as FeedbackReport;
+}
+
+// 진단 수집기가 글로벌을 패치하므로 매 테스트마다 원복한다.
+let originals: { fetch: unknown; warn: unknown; error: unknown };
+let collector: DiagnosticsCollector;
+
+beforeEach(() => {
+  clockNow = START_TIME;
+  originals = {
+    fetch: g.fetch,
+    warn: (g.console as G).warn,
+    error: (g.console as G).error,
+  };
+  collector = new DiagnosticsCollector({ now: clock, iso });
+});
+
+afterEach(() => {
+  collector.uninstall();
+  g.fetch = originals.fetch;
+  (g.console as G).warn = originals.warn;
+  (g.console as G).error = originals.error;
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// TC1 / TC2 — 세션 중 오간 요청과 로그가 제보에 실린다
+// ────────────────────────────────────────────────────────────────────────────
+
+describe("진단이 제보에 실린다 (TC1, TC2)", () => {
+  it("요청이 오간 세션의 제보에는 network 가 담긴다", async () => {
+    g.fetch = (): Promise<unknown> => {
+      clockNow += 15;
+      return Promise.resolve({ status: 500 });
+    };
+    collector.install();
+
+    await (g.fetch as (u: string, i?: unknown) => Promise<unknown>)(
+      "https://api.example/orders",
+      { method: "post" }
+    );
+
+    const received = await sendOnce({
+      platform: "web",
+      getDiagnostics: () => collector.snapshot(),
+    });
+
+    const network = received.context.diagnostics?.network ?? [];
+    expect(network.length).toBeGreaterThanOrEqual(1);
+    // 각 항목에 메서드·URL·상태코드·소요시간이 있다.
+    for (const entry of network) {
+      expect(typeof entry.method).toBe("string");
+      expect(typeof entry.url).toBe("string");
+      expect(typeof entry.durationMs).toBe("number");
+      expect(entry).toHaveProperty("status");
+      expect(typeof entry.at).toBe("string");
+    }
+    expect(network[0]).toMatchObject({
+      method: "POST",
+      url: "https://api.example/orders",
+      status: 500,
+      durationMs: 15,
+    });
+  });
+
+  it("경고·에러가 난 세션의 제보에는 logs 가 담긴다", async () => {
+    g.fetch = (): Promise<unknown> => Promise.resolve({ status: 200 });
+    (g.console as G).warn = (): void => {};
+    (g.console as G).error = (): void => {};
+    collector.install();
+
+    (g.console as { warn: (m: string) => void }).warn("응답이 느리다");
+    (g.console as { error: (m: string, e: unknown) => void }).error(
+      "결제 실패",
+      new Error("카드 거절")
+    );
+
+    const received = await sendOnce({
+      platform: "web",
+      getDiagnostics: () => collector.snapshot(),
+    });
+
+    const logs = received.context.diagnostics?.logs ?? [];
+    expect(logs.length).toBeGreaterThanOrEqual(2);
+    expect(logs.map((l) => l.level)).toEqual(["warn", "error"]);
+    expect(logs[0]?.message).toContain("응답이 느리다");
+    expect(logs[1]?.message).toContain("결제 실패");
+    expect(logs[1]?.message).toContain("카드 거절");
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// TC5 — 빈 배열을 상수로 보내지 않는다
+// ────────────────────────────────────────────────────────────────────────────
+
+describe("빈 배열을 상수로 보내지 않는다 (TC5)", () => {
+  it("수집이 배선되지 않았으면 diagnostics 자체가 null 이다", async () => {
+    const received = await sendOnce({ platform: "web" });
+
+    expect(received.context.diagnostics).toBeNull();
+    // 하드코딩된 빈 배열이 아니라는 뜻: 배열 자체가 존재하지 않는다.
+    expect(JSON.stringify(received.context.diagnostics)).toBe("null");
+  });
+
+  it("수집이 배선됐는데 아무 일도 없었으면 빈 배열이고, 일이 있었으면 채워진다", async () => {
+    g.fetch = (): Promise<unknown> => {
+      clockNow += 2;
+      return Promise.resolve({ status: 200 });
+    };
+    collector.install();
+
+    const quiet = await sendOnce({
+      platform: "web",
+      getDiagnostics: () => collector.snapshot(),
+    });
+    expect(quiet.context.diagnostics).toEqual({ network: [], logs: [] });
+
+    await (g.fetch as (u: string) => Promise<unknown>)("https://api.example/ping");
+
+    const busy = await sendOnce({
+      platform: "web",
+      getDiagnostics: () => collector.snapshot(),
+    });
+    expect(busy.context.diagnostics?.network).toHaveLength(1);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// TC6 / TC10 — 앱 컨텍스트 전체 수집, 매핑 없어도 나머지는 온전
+// ────────────────────────────────────────────────────────────────────────────
+
+const nativeProviders = {
+  platform: "native" as const,
+  getCurrentScreen: (): string => "OrderDetail",
+  getNavPath: (): string[] => ["Root", "Orders", "OrderDetail"],
+  getRouteParams: (): unknown => ({ orderId: "A-1", onDone: (): void => {} }),
+  getAppInfo: () => ({
+    version: "1.4.2",
+    channel: "preview",
+    updateId: "upd-9",
+    runtimeVersion: "56.0.0",
+  }),
+  getDevice: () => ({
+    model: "iPhone 15",
+    osName: "iOS",
+    osVersion: "18.2",
+    deviceType: "phone",
+  }),
+  getDisplay: () => ({ width: 393, height: 852, pixelRatio: 3, fontScale: 1 }),
+  getTimezone: (): string => "Asia/Seoul",
+};
+
+describe("앱 컨텍스트 (TC6, TC10)", () => {
+  it("기기·앱·사용자 컨텍스트가 모두 담긴다", async () => {
+    const received = await sendOnce({
+      ...nativeProviders,
+      screenSourceMap: { OrderDetail: "src/screens/OrderDetail.tsx" },
+      getUser: () => ({ id: "u-77", email: "a@example.com", name: "정경훈" }),
+    });
+
+    const ctx = received.context;
+    expect(ctx.screen).toBe("OrderDetail");
+    expect(ctx.platform).toBe("native");
+    expect(ctx.timezone).toBe("Asia/Seoul");
+    expect(ctx.clientTimestamp).toBe(iso(START_TIME));
+    expect(ctx.user).toMatchObject({ id: "u-77", email: "a@example.com", isGuest: false });
+
+    const native = ctx.native;
+    expect(native).not.toBeNull();
+    expect(native?.navPath).toEqual(["Root", "Orders", "OrderDetail"]);
+    expect(native?.screenPath).toBe("src/screens/OrderDetail.tsx");
+    // 함수는 직렬화에서 떨어져 나가고 값만 남는다.
+    expect(native?.routeParams).toEqual({ orderId: "A-1" });
+    expect(native?.appInfo).toEqual({
+      version: "1.4.2",
+      channel: "preview",
+      updateId: "upd-9",
+      runtimeVersion: "56.0.0",
+    });
+    expect(native?.device).toEqual({
+      model: "iPhone 15",
+      osName: "iOS",
+      osVersion: "18.2",
+      deviceType: "phone",
+    });
+    expect(native?.display).toEqual({
+      width: 393,
+      height: 852,
+      pixelRatio: 3,
+      fontScale: 1,
+    });
+
+    // 어느 하나라도 비어 있으면 안 된다.
+    for (const group of [native?.appInfo, native?.device, native?.display]) {
+      for (const value of Object.values(group ?? {})) {
+        expect(value).not.toBeNull();
+      }
+    }
+  });
+
+  it("매핑이 없으면 screenPath 만 null 이고 나머지는 그대로 수집된다", async () => {
+    const received = await sendOnce({
+      ...nativeProviders,
+      // screenSourceMap 없음(빌드 플러그인 미사용)
+      getUser: () => ({ id: "u-77" }),
+    });
+
+    const native = received.context.native;
+    expect(native?.screenPath).toBeNull();
+    expect(received.context.source).toEqual({ screenId: null, sourceFile: null });
+
+    // 나머지는 TC6 과 동일하게 살아 있다.
+    expect(received.context.screen).toBe("OrderDetail");
+    expect(native?.navPath).toEqual(["Root", "Orders", "OrderDetail"]);
+    expect(native?.appInfo.version).toBe("1.4.2");
+    expect(native?.device.model).toBe("iPhone 15");
+    expect(native?.display.width).toBe(393);
+    expect(received.context.timezone).toBe("Asia/Seoul");
+    expect(received.context.user?.id).toBe("u-77");
+  });
+
+  it("매핑에 현재 화면이 없어도(누락) 다른 화면 매핑 때문에 틀린 경로를 넣지 않는다", async () => {
+    const received = await sendOnce({
+      ...nativeProviders,
+      screenSourceMap: { Home: "src/screens/Home.tsx" },
+      getUser: () => ({ id: "u-77" }),
+    });
+
+    expect(received.context.native?.screenPath).toBeNull();
+    expect(received.context.screen).toBe("OrderDetail");
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// TC7 — 게스트도 식별 가능하게
+// ────────────────────────────────────────────────────────────────────────────
+
+describe("게스트 신원 (TC7)", () => {
+  it("getUser 가 없으면 게스트 식별자를 채우고 isGuest 를 true 로 보낸다", async () => {
+    const received = await sendOnce({ platform: "web" });
+
+    const user = received.context.user;
+    expect(user).not.toBeNull();
+    expect(user?.isGuest).toBe(true);
+    expect(typeof user?.id).toBe("string");
+    expect((user?.id ?? "").length).toBeGreaterThan(0);
+    expect(user?.id).toMatch(/^guest_/);
+  });
+
+  it("같은 저장소를 쓰면 다시 제보해도 같은 게스트 식별자다", async () => {
+    const storage = memoryStorage();
+    const first = await sendOnce({ platform: "web", storage });
+    const second = await sendOnce({ platform: "web", storage });
+
+    expect(second.context.user?.id).toBe(first.context.user?.id);
+  });
+
+  // getUser 를 "값"이 아니라 "함수"로 받는 이유가 여기 있다. 위젯을 마운트한 뒤
+  // 사용자가 로그인하거나 로그아웃하므로, 마운트 시점 값을 캐싱하면 제보에 옛 신원이
+  // 실린다(로그아웃한 사람 이름으로 제보가 올라가는 쪽이 더 나쁘다).
+  it("getUser 는 마운트가 아니라 제출 시점에 불린다(그 사이 로그인이 반영된다)", async () => {
+    const storage = memoryStorage();
+    // 세션 복구 전에는 호스트가 빈 id 를 준다(기존 TC 와 같은 관례). 복구되면 실제 id.
+    let session: FeedbackUser = { id: "" };
+    const getUser = vi.fn((): FeedbackUser => session);
+
+    // 1) 아직 로그인 전 — 게스트로 나가야 한다.
+    const before = await sendOnce({ platform: "web", storage, getUser });
+    expect(before.context.user?.isGuest).toBe(true);
+
+    // 2) 그 사이 로그인.
+    session = { id: "u-77" };
+
+    // 3) 같은 getUser 함수인데 이번엔 로그인 신원이 실려야 한다.
+    const after = await sendOnce({ platform: "web", storage, getUser });
+    expect(after.context.user?.id).toBe("u-77");
+    expect(after.context.user?.isGuest).toBe(false);
+
+    // 제보 1건당 정확히 1회. 캐싱도 아니고 중복 호출도 아니다.
+    expect(getUser).toHaveBeenCalledTimes(2);
+  });
+
+  it("getUser 가 던지거나 빈 id 를 주면 게스트로 떨어진다(제보를 버리지 않는다)", async () => {
+    const thrown = await sendOnce({
+      platform: "web",
+      getUser: () => {
+        throw new Error("아직 세션 복구 전");
+      },
+    });
+    expect(thrown.context.user?.isGuest).toBe(true);
+    expect(thrown.context.user?.id).toMatch(/^guest_/);
+
+    const empty = await sendOnce({
+      platform: "web",
+      getUser: () => ({ id: "" }),
+    });
+    expect(empty.context.user?.isGuest).toBe(true);
+    expect(empty.context.user?.id).toMatch(/^guest_/);
+  });
+
+  it("저장소가 아예 못 쓰는 상황에서만 user 가 null 이 된다", async () => {
+    const broken: FeedbackStorage = {
+      async get() {
+        throw new Error("storage unavailable");
+      },
+      async set() {
+        throw new Error("storage unavailable");
+      },
+      async remove() {
+        /* 큐 쪽은 조용히 넘어가야 한다 */
+      },
+    };
+
+    const report = await buildReport(PARTS, {
+      app: "test-app",
+      sessionId: "session-1",
+      storage: broken,
+      platform: "web",
+      now: clock,
+      iso,
+    });
+
+    expect(report.context.user).toBeNull();
+  });
+});