clean-architecture-frontend-template/tests/unit/telemetry.test.js

import { describe, expect, it, vi } from "vitest";

import {
  createTelemetryAdapter,
  safeTraceparent,
} from "../../src/adapters/telemetry/best-effort-telemetry.js";
import {
  TELEMETRY_REGISTRY,
  projectTelemetryEvent,
} from "../../src/contracts/telemetry.js";

const validAttributes = {
  error_kind: "SERVER_FAILURE",
  http_status_group: "5xx",
  attempt_count_bucket: "3",
  route_id: "TEST_ROUTE",
};

describe("telemetry registry and redaction", () => {
  it("defines all event contract fields", () => {
    for (const definition of Object.values(TELEMETRY_REGISTRY)) {
      expect(definition).toEqual(
        expect.objectContaining({
          eventName: expect.any(String),
          trigger: expect.any(String),
          requiredAttributes: expect.any(Array),
          optionalAttributes: expect.any(Array),
          forbiddenAttributes: expect.any(Array),
          sampling: expect.any(String),
          delivery: "best-effort",
        }),
      );
    }
  });

  it("redacts forbidden attributes and rejects unknown context", () => {
    const projected = projectTelemetryEvent("api.request.failed", {
      ...validAttributes,
      raw_url: "https://api.test/path?token=secret",
    });

    expect(projected.success).toBe(true);
    expect(JSON.stringify(projected)).not.toMatch(/raw_url|token|secret/);
    expect(
      projectTelemetryEvent("api.request.failed", {
        ...validAttributes,
        unregistered: "private",
      }),
    ).toEqual({ success: false, reason: "unknown-attributes" });
    expect(
      projectTelemetryEvent("api.request.failed", {
        ...validAttributes,
        route_id: "/users/actual-user-id",
      }),
    ).toEqual({ success: false, reason: "invalid-attribute-value" });
  });

  it("validates traceparent without exposing invalid values", () => {
    expect(
      safeTraceparent(
        "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
      ),
    ).toBe("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01");
    expect(safeTraceparent("Bearer secret")).toBeNull();
  });
});

describe("best-effort telemetry adapter", () => {
  it("bounds the queue using oldest-drop without blocking callers", () => {
    const scheduled = /** @type {Array<() => void>} */ ([]);
    const adapter = createTelemetryAdapter({
      enabled: true,
      endpoint: "https://telemetry.test/events",
      maxQueue: 2,
      schedule: (callback) => scheduled.push(callback),
      fetcher: vi.fn(),
    });

    adapter.emit("api.request.failed", validAttributes);
    adapter.emit("api.request.failed", validAttributes);
    adapter.emit("api.request.failed", validAttributes);

    expect(adapter.pendingCount()).toBe(2);
    expect(adapter.droppedCount()).toBe(1);
    expect(adapter.dropReasons()).toEqual({ "queue-full": 1 });
    expect(adapter.deliveryEvidence()).toMatchObject({
      eventName: "telemetry.delivery.dropped",
      attributes: { reason: "queue-full", queue_size_bucket: "1-10" },
    });
    expect(scheduled).toHaveLength(1);
  });

  it("degrades on sink failure without throwing or recursive events", async () => {
    const onDrop = vi.fn(() => {
      throw new Error("observer unavailable");
    });
    const adapter = createTelemetryAdapter({
      enabled: true,
      endpoint: "https://telemetry.test/events",
      schedule: () => {},
      fetcher: async () => {
        throw new Error("sink unavailable");
      },
      onDrop,
    });
    expect(() => adapter.emit("api.request.failed", validAttributes)).not.toThrow();
    await expect(adapter.flush()).resolves.toBeUndefined();
    expect(adapter.droppedCount()).toBe(1);
    expect(adapter.dropReasons()).toEqual({ "sink-failure": 1 });
    expect(onDrop).toHaveBeenCalledOnce();
    expect(adapter.pendingCount()).toBe(0);
  });

  it("never serializes circular or unbounded event context", () => {
    const adapter = createTelemetryAdapter({
      enabled: true,
      endpoint: "https://telemetry.test/events",
      schedule: () => {},
    });
    const circular = {};
    circular.self = circular;
    const hostile = new Proxy(
      {},
      {
        ownKeys() {
          throw new Error("private proxy value");
        },
      },
    );

    expect(() =>
      adapter.emit("api.request.failed", {
        ...validAttributes,
        unregistered: circular,
      }),
    ).not.toThrow();
    expect(adapter.pendingCount()).toBe(0);
    expect(adapter.dropReasons()).toEqual({ "invalid-context": 1 });
    expect(() =>
      adapter.emit("api.request.failed", hostile),
    ).not.toThrow();
    expect(adapter.dropReasons()).toEqual({
      "invalid-context": 1,
      "serialization-failure": 1,
    });
  });

  it("performs no network or queue work when disabled", async () => {
    const fetcher = vi.fn();
    const adapter = createTelemetryAdapter({
      enabled: false,
      endpoint: "https://telemetry.test/events",
      fetcher,
    });
    adapter.emit("api.request.failed", validAttributes);
    await adapter.flush();

    expect(fetcher).not.toHaveBeenCalled();
    expect(adapter.pendingCount()).toBe(0);
  });

  it("flushes on page exit and removes the lifecycle listener", async () => {
    const lifecycle = new EventTarget();
    const remove = vi.spyOn(lifecycle, "removeEventListener");
    const fetcher = vi.fn(async () => new Response(null, { status: 204 }));
    const adapter = createTelemetryAdapter({
      enabled: true,
      endpoint: "https://telemetry.test/events",
      schedule: () => {},
      lifecycle,
      fetcher,
    });
    adapter.emit("api.request.failed", validAttributes);

    lifecycle.dispatchEvent(new Event("pagehide"));
    await vi.waitFor(() => expect(fetcher).toHaveBeenCalledOnce());
    adapter.dispose();

    expect(adapter.pendingCount()).toBe(0);
    expect(remove).toHaveBeenCalledWith("pagehide", expect.any(Function));
  });
});