@checkstack/test-utils-backend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,89 @@
+# @checkstack/test-utils-backend
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/backend-api@0.0.2
+  - @checkstack/common@0.0.2
+  - @checkstack/queue-api@0.0.2
+  - @checkstack/signal-common@0.0.2
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [b4eb432]
+- Updated dependencies [a65e002]
+  - @checkstack/backend-api@1.1.0
+  - @checkstack/common@0.2.0
+  - @checkstack/queue-api@1.0.1
+  - @checkstack/signal-common@0.1.1
+
+## 0.1.0
+
+### Minor Changes
+
+- b55fae6: Added realtime Signal Service for backend-to-frontend push notifications via WebSockets.
+
+  ## New Packages
+
+  - **@checkstack/signal-common**: Shared types including `Signal`, `SignalService`, `createSignal()`, and WebSocket protocol messages
+  - **@checkstack/signal-backend**: `SignalServiceImpl` with EventBus integration and Bun WebSocket handler using native pub/sub
+  - **@checkstack/signal-frontend**: React `SignalProvider` and `useSignal()` hook for consuming typed signals
+
+  ## Changes
+
+  - **@checkstack/backend-api**: Added `coreServices.signalService` reference for plugins to emit signals
+  - **@checkstack/backend**: Integrated WebSocket server at `/api/signals/ws` with session-based authentication
+
+  ## Usage
+
+  Backend plugins can emit signals:
+
+  ```typescript
+  import { coreServices } from "@checkstack/backend-api";
+  import { NOTIFICATION_RECEIVED } from "@checkstack/notification-common";
+
+  const signalService = context.signalService;
+  await signalService.sendToUser(NOTIFICATION_RECEIVED, userId, { ... });
+  ```
+
+  Frontend components subscribe to signals:
+
+  ```tsx
+  import { useSignal } from "@checkstack/signal-frontend";
+  import { NOTIFICATION_RECEIVED } from "@checkstack/notification-common";
+
+  useSignal(NOTIFICATION_RECEIVED, (payload) => {
+    // Handle realtime notification
+  });
+  ```
+
+### Patch Changes
+
+- e4d83fc: Add BullMQ queue plugin with orphaned job cleanup
+
+  - **queue-api**: Added `listRecurringJobs()` method to Queue interface for detecting orphaned jobs
+  - **queue-bullmq-backend**: New plugin implementing BullMQ (Redis) queue backend with job schedulers, consumer groups, and distributed job persistence
+  - **queue-bullmq-common**: New common package with queue permissions
+  - **queue-memory-backend**: Implemented `listRecurringJobs()` for in-memory queue
+  - **healthcheck-backend**: Enhanced `bootstrapHealthChecks` to clean up orphaned job schedulers using `listRecurringJobs()`
+  - **test-utils-backend**: Added `listRecurringJobs()` to mock queue factory
+
+  This enables production-ready distributed queue processing with Redis persistence and automatic cleanup of orphaned jobs when health checks are deleted.
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [e4d83fc]
+- Updated dependencies [71275dd]
+- Updated dependencies [ae19ff6]
+- Updated dependencies [b55fae6]
+- Updated dependencies [b354ab3]
+- Updated dependencies [8e889b4]
+- Updated dependencies [81f3f85]
+  - @checkstack/common@0.1.0
+  - @checkstack/backend-api@1.0.0
+  - @checkstack/queue-api@1.0.0
+  - @checkstack/signal-common@0.1.0

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@checkstack/test-utils-backend",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "@checkstack/queue-api": "workspace:*",
+    "@checkstack/signal-common": "workspace:*"
+  },
+  "devDependencies": {
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*",
+    "@types/bun": "latest",
+    "zod": "^4.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+export { createMockLogger, createMockLoggerModule } from "./mock-logger";
+export {
+  createMockQueueManager,
+  createMockQueueFactory,
+} from "./mock-queue-factory";
+export { createMockDb, createMockDbModule } from "./mock-db";
+export { createMockFetch } from "./mock-fetch";
+export {
+  createMockSignalService,
+  type MockSignalService,
+  type RecordedSignal,
+} from "./mock-signal-service";
+export {
+  createMockEventBus,
+  type MockEventBus,
+  type EmittedEvent,
+} from "./mock-event-bus";
+export {
+  createMockPluginInstaller,
+  type MockPluginInstaller,
+  type InstallResult,
+} from "./mock-plugin-installer";

package/src/mock-db.ts

@@ -0,0 +1,90 @@
+import { mock } from "bun:test";
+
+/**
+ * Creates a mock Drizzle database instance suitable for unit testing.
+ * This mock supports the most common query patterns:
+ * - select().from()
+ * - select().from().where()
+ * - select().from().where().limit()
+ * - insert().values()
+ * - insert().values().onConflictDoUpdate()
+ * - update().set().where()
+ *
+ * @returns A mock database object that can be used in place of a real Drizzle database
+ *
+ * @example
+ * ```typescript
+ * const mockDb = createMockDb();
+ * const service = new MyService(mockDb);
+ * ```
+ */
+export function createMockDb() {
+  const createSelectChain = () => {
+    const whereResult = Object.assign(Promise.resolve([]), {
+      limit: mock(() => Promise.resolve([])),
+      orderBy: mock(function () {
+        return Object.assign(Promise.resolve([]), {
+          limit: mock(() => Promise.resolve([])),
+        });
+      }),
+    });
+    const innerJoinResult = Object.assign(Promise.resolve([]), {
+      where: mock(() => whereResult),
+      leftJoin: mock(function () {
+        return Object.assign(Promise.resolve([]), {
+          where: mock(() => whereResult),
+        });
+      }),
+    });
+    const fromResult = Object.assign(Promise.resolve([]), {
+      where: mock(() => whereResult),
+      innerJoin: mock(() => innerJoinResult),
+      leftJoin: mock(() => innerJoinResult),
+      groupBy: mock(function () {
+        return Object.assign(Promise.resolve([]), {
+          as: mock(() => ({})), // For subquery aliasing
+        });
+      }),
+    });
+    return {
+      from: mock(() => fromResult),
+    };
+  };
+
+  return {
+    select: mock(() => createSelectChain()),
+    insert: mock(() => ({
+      values: mock(() => ({
+        onConflictDoUpdate: mock(() => Promise.resolve()),
+        returning: mock(() => Promise.resolve([])),
+      })),
+    })),
+    update: mock(() => ({
+      set: mock(() => ({
+        where: mock(() => Promise.resolve()),
+        returning: mock(() => Promise.resolve([])),
+      })),
+    })),
+    delete: mock(() => ({
+      where: mock(() => Promise.resolve()),
+    })),
+  };
+}
+
+/**
+ * Creates a mock database module export suitable for use with Bun's mock.module().
+ * This includes both the database instance and the admin pool.
+ *
+ * @returns An object with adminPool and db properties
+ *
+ * @example
+ * ```typescript
+ * mock.module("./db", () => createMockDbModule());
+ * ```
+ */
+export function createMockDbModule() {
+  return {
+    adminPool: { query: mock(() => Promise.resolve()) },
+    db: createMockDb(),
+  };
+}

package/src/mock-event-bus.ts

@@ -0,0 +1,109 @@
+/**
+ * Mock EventBus for testing plugin lifecycle and hook emissions.
+ * Tracks all emitted events and allows triggering broadcasts for multi-instance simulation.
+ */
+
+export interface MockEventBusOptions {
+  /** If true, auto-resolves all subscriptions */
+  autoResolve?: boolean;
+}
+
+export interface EmittedEvent {
+  hook: string;
+  payload: unknown;
+}
+
+export interface MockEventBus {
+  emit: (hook: { id: string }, payload: unknown) => Promise<void>;
+  emitLocal: (hook: { id: string }, payload: unknown) => Promise<void>;
+  subscribe: (
+    pluginId: string,
+    hook: { id: string },
+    listener: (payload: unknown) => Promise<void>
+  ) => Promise<() => void>;
+  subscribeLocal: (
+    hook: { id: string },
+    listener: (payload: unknown) => Promise<void>
+  ) => () => void;
+  unsubscribe: () => Promise<void>;
+
+  // Test helpers
+  _emittedEvents: EmittedEvent[];
+  _localEmittedEvents: EmittedEvent[];
+  _triggerBroadcast: (hook: { id: string }, payload: unknown) => Promise<void>;
+  _clear: () => void;
+}
+
+export function createMockEventBus(
+  _options?: MockEventBusOptions
+): MockEventBus {
+  const subscriptions = new Map<
+    string,
+    ((payload: unknown) => Promise<void>)[]
+  >();
+  const localSubscriptions = new Map<
+    string,
+    ((payload: unknown) => Promise<void>)[]
+  >();
+  const emittedEvents: EmittedEvent[] = [];
+  const localEmittedEvents: EmittedEvent[] = [];
+
+  return {
+    emit: async (hook: { id: string }, payload: unknown) => {
+      emittedEvents.push({ hook: hook.id, payload });
+      const listeners = subscriptions.get(hook.id) || [];
+      await Promise.all(listeners.map((l) => l(payload)));
+    },
+
+    emitLocal: async (hook: { id: string }, payload: unknown) => {
+      localEmittedEvents.push({ hook: hook.id, payload });
+      const listeners = localSubscriptions.get(hook.id) || [];
+      await Promise.all(listeners.map((l) => l(payload)));
+    },
+
+    subscribe: async (
+      _pluginId: string,
+      hook: { id: string },
+      listener: (payload: unknown) => Promise<void>
+    ) => {
+      const listeners = subscriptions.get(hook.id) || [];
+      listeners.push(listener);
+      subscriptions.set(hook.id, listeners);
+      return () => {
+        const idx = listeners.indexOf(listener);
+        if (idx !== -1) listeners.splice(idx, 1);
+      };
+    },
+
+    subscribeLocal: (
+      hook: { id: string },
+      listener: (payload: unknown) => Promise<void>
+    ) => {
+      const listeners = localSubscriptions.get(hook.id) || [];
+      listeners.push(listener);
+      localSubscriptions.set(hook.id, listeners);
+      return () => {
+        const idx = listeners.indexOf(listener);
+        if (idx !== -1) listeners.splice(idx, 1);
+      };
+    },
+
+    unsubscribe: async () => {},
+
+    // Test helpers
+    _emittedEvents: emittedEvents,
+    _localEmittedEvents: localEmittedEvents,
+
+    _triggerBroadcast: async (hook: { id: string }, payload: unknown) => {
+      const listeners = subscriptions.get(hook.id) || [];
+      await Promise.all(listeners.map((l) => l(payload)));
+    },
+
+    _clear: () => {
+      emittedEvents.length = 0;
+      localEmittedEvents.length = 0;
+      subscriptions.clear();
+      localSubscriptions.clear();
+    },
+  };
+}

package/src/mock-fetch.ts

@@ -0,0 +1,37 @@
+import { mock } from "bun:test";
+import type { Fetch } from "@checkstack/backend-api";
+
+/**
+ * Creates a mock Fetch instance suitable for unit testing.
+ * This mock provides the fetch method and forPlugin helper for plugin-scoped requests.
+ *
+ * @returns A mock Fetch object
+ *
+ * @example
+ * ```typescript
+ * const mockFetch = createMockFetch();
+ * const response = await mockFetch.forPlugin("catalog-backend").get("/entities");
+ * ```
+ */
+export function createMockFetch(): Fetch {
+  return {
+    fetch: mock(() => Promise.resolve({ ok: true, text: () => "" })),
+    forPlugin: mock(() => ({
+      get: mock(() =>
+        Promise.resolve({ ok: true, json: () => Promise.resolve({}) })
+      ),
+      post: mock(() =>
+        Promise.resolve({ ok: true, json: () => Promise.resolve({}) })
+      ),
+      put: mock(() =>
+        Promise.resolve({ ok: true, json: () => Promise.resolve({}) })
+      ),
+      patch: mock(() =>
+        Promise.resolve({ ok: true, json: () => Promise.resolve({}) })
+      ),
+      delete: mock(() =>
+        Promise.resolve({ ok: true, json: () => Promise.resolve({}) })
+      ),
+    })),
+  } as unknown as Fetch;
+}

package/src/mock-logger.ts

@@ -0,0 +1,40 @@
+import { mock } from "bun:test";
+
+/**
+ * Creates a mock logger instance suitable for unit testing.
+ * This mock provides all standard logger methods (info, debug, warn, error)
+ * and a child() method that returns another mock logger.
+ *
+ * @returns A mock logger object
+ *
+ * @example
+ * ```typescript
+ * const mockLogger = createMockLogger();
+ * myService.setLogger(mockLogger);
+ * ```
+ */
+export function createMockLogger() {
+  return {
+    info: mock(),
+    debug: mock(),
+    warn: mock(),
+    error: mock(),
+    child: mock(() => createMockLogger()),
+  };
+}
+
+/**
+ * Creates a mock logger module export suitable for use with Bun's mock.module().
+ *
+ * @returns An object with rootLogger property
+ *
+ * @example
+ * ```typescript
+ * mock.module("./logger", () => createMockLoggerModule());
+ * ```
+ */
+export function createMockLoggerModule() {
+  return {
+    rootLogger: createMockLogger(),
+  };
+}

package/src/mock-plugin-installer.ts

@@ -0,0 +1,69 @@
+/**
+ * Mock PluginInstaller for testing plugin installation flows.
+ * Tracks all install calls and allows configuring responses.
+ */
+
+export interface InstallResult {
+  name: string;
+  path: string;
+}
+
+export interface MockPluginInstallerOptions {
+  /** Custom install result generator */
+  installResult?: (packageName: string) => InstallResult;
+  /** If true, install will throw an error */
+  shouldFail?: boolean;
+  /** Error message to throw when shouldFail is true */
+  errorMessage?: string;
+}
+
+export interface MockPluginInstaller {
+  install: (packageName: string) => Promise<InstallResult>;
+
+  // Test helpers
+  _installCalls: string[];
+  _setInstallResult: (fn: (packageName: string) => InstallResult) => void;
+  _setShouldFail: (shouldFail: boolean, errorMessage?: string) => void;
+  _clear: () => void;
+}
+
+export function createMockPluginInstaller(
+  options?: MockPluginInstallerOptions
+): MockPluginInstaller {
+  const installCalls: string[] = [];
+  let installResultFn =
+    options?.installResult ||
+    ((packageName: string) => ({
+      name: packageName,
+      path: `/runtime_plugins/node_modules/${packageName}`,
+    }));
+  let shouldFail = options?.shouldFail || false;
+  let errorMessage = options?.errorMessage || "Mock install failed";
+
+  return {
+    install: async (packageName: string) => {
+      installCalls.push(packageName);
+      if (shouldFail) {
+        throw new Error(errorMessage);
+      }
+      return installResultFn(packageName);
+    },
+
+    // Test helpers
+    _installCalls: installCalls,
+
+    _setInstallResult: (fn: (packageName: string) => InstallResult) => {
+      installResultFn = fn;
+    },
+
+    _setShouldFail: (fail: boolean, msg?: string) => {
+      shouldFail = fail;
+      if (msg) errorMessage = msg;
+    },
+
+    _clear: () => {
+      installCalls.length = 0;
+      shouldFail = false;
+    },
+  };
+}

package/src/mock-queue-factory.ts

@@ -0,0 +1,140 @@
+import type {
+  Queue,
+  QueueManager,
+  QueueJob,
+  SwitchResult,
+  RecurringJobInfo,
+  RecurringJobDetails,
+} from "@checkstack/queue-api";
+
+/**
+ * Creates a mock QueueManager for testing.
+ * This manager creates simple in-memory mock queues for testing purposes.
+ *
+ * @returns A mock QueueManager
+ *
+ * @example
+ * ```typescript
+ * const mockQueueManager = createMockQueueManager();
+ * const queue = mockQueueManager.getQueue("test-channel");
+ * ```
+ */
+export function createMockQueueManager(): QueueManager {
+  const queues = new Map<string, Queue<unknown>>();
+  let activePluginId = "mock";
+
+  function createMockQueue<T>(_channelId: string): Queue<T> {
+    const consumers = new Map<
+      string,
+      {
+        handler: (job: QueueJob<T>) => Promise<void>;
+        maxRetries: number;
+      }
+    >();
+    const jobs: T[] = [];
+    const recurringJobs = new Map<
+      string,
+      { data: T; intervalSeconds: number }
+    >();
+
+    const mockQueue: Queue<T> = {
+      enqueue: async (data) => {
+        jobs.push(data);
+        // Trigger all consumers (with error handling like real queue)
+        for (const [_group, consumer] of consumers.entries()) {
+          try {
+            await consumer.handler({
+              id: `job-${Date.now()}`,
+              data,
+              timestamp: new Date(),
+              attempts: 0,
+            });
+          } catch (error) {
+            // Mock queue catches errors like real implementation
+            console.error("Mock queue caught error:", error);
+          }
+        }
+        return `job-${Date.now()}`;
+      },
+      consume: async (handler, options) => {
+        consumers.set(options.consumerGroup, {
+          handler: async (job: QueueJob<T>) => await handler(job),
+          maxRetries: options.maxRetries ?? 3,
+        });
+      },
+      scheduleRecurring: async (data, options) => {
+        recurringJobs.set(options.jobId, {
+          data,
+          intervalSeconds: options.intervalSeconds,
+        });
+        return options.jobId;
+      },
+      cancelRecurring: async (jobId) => {
+        recurringJobs.delete(jobId);
+      },
+      listRecurringJobs: async () => {
+        return [...recurringJobs.keys()];
+      },
+      getRecurringJobDetails: async (
+        jobId
+      ): Promise<RecurringJobDetails<T> | undefined> => {
+        const job = recurringJobs.get(jobId);
+        if (!job) return undefined;
+        return {
+          jobId,
+          data: job.data,
+          intervalSeconds: job.intervalSeconds,
+        };
+      },
+      getInFlightCount: async () => 0,
+      testConnection: async () => {
+        // Mock implementation - always succeeds
+      },
+      stop: async () => {
+        consumers.clear();
+      },
+      getStats: async () => ({
+        pending: jobs.length,
+        processing: 0,
+        completed: 0,
+        failed: 0,
+        consumerGroups: consumers.size,
+      }),
+    };
+
+    return mockQueue;
+  }
+
+  return {
+    getQueue: <T>(name: string): Queue<T> => {
+      // Return existing queue if already created
+      if (queues.has(name)) {
+        return queues.get(name)! as Queue<T>;
+      }
+
+      const mockQueue = createMockQueue<T>(name);
+      queues.set(name, mockQueue as Queue<unknown>);
+      return mockQueue;
+    },
+    getActivePlugin: () => activePluginId,
+    getActiveConfig: () => ({}),
+    setActiveBackend: async (pluginId: string): Promise<SwitchResult> => {
+      activePluginId = pluginId;
+      return { success: true, migratedRecurringJobs: 0, warnings: [] };
+    },
+    getInFlightJobCount: async () => 0,
+    listAllRecurringJobs: async (): Promise<RecurringJobInfo[]> => [],
+    startPolling: () => {},
+    shutdown: async () => {
+      for (const queue of queues.values()) {
+        await queue.stop();
+      }
+      queues.clear();
+    },
+  };
+}
+
+/**
+ * @deprecated Use createMockQueueManager instead
+ */
+export const createMockQueueFactory = createMockQueueManager;

package/src/mock-signal-service.test.ts

@@ -0,0 +1,206 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import {
+  createMockSignalService,
+  type MockSignalService,
+} from "../src/mock-signal-service";
+import { createSignal } from "@checkstack/signal-common";
+import { z } from "zod";
+
+// Test signals
+const TEST_SIGNAL_A = createSignal(
+  "test.signalA",
+  z.object({ value: z.string() })
+);
+
+const TEST_SIGNAL_B = createSignal(
+  "test.signalB",
+  z.object({ count: z.number() })
+);
+
+describe("createMockSignalService", () => {
+  let mockService: MockSignalService;
+
+  beforeEach(() => {
+    mockService = createMockSignalService();
+  });
+
+  describe("broadcast", () => {
+    it("should record broadcast signals", async () => {
+      await mockService.broadcast(TEST_SIGNAL_A, { value: "hello" });
+
+      const recorded = mockService.getRecordedSignals();
+      expect(recorded).toHaveLength(1);
+      expect(recorded[0].targetType).toBe("broadcast");
+      expect(recorded[0].signal.id).toBe("test.signalA");
+      expect(recorded[0].payload).toEqual({ value: "hello" });
+    });
+
+    it("should record timestamp", async () => {
+      const before = new Date();
+      await mockService.broadcast(TEST_SIGNAL_A, { value: "test" });
+      const after = new Date();
+
+      const recorded = mockService.getRecordedSignals()[0];
+      expect(recorded.timestamp.getTime()).toBeGreaterThanOrEqual(
+        before.getTime()
+      );
+      expect(recorded.timestamp.getTime()).toBeLessThanOrEqual(after.getTime());
+    });
+  });
+
+  describe("sendToUser", () => {
+    it("should record user-targeted signals with userId", async () => {
+      await mockService.sendToUser(TEST_SIGNAL_B, "user-123", { count: 42 });
+
+      const recorded = mockService.getRecordedSignals();
+      expect(recorded).toHaveLength(1);
+      expect(recorded[0].targetType).toBe("user");
+      expect(recorded[0].userIds).toEqual(["user-123"]);
+      expect(recorded[0].payload).toEqual({ count: 42 });
+    });
+  });
+
+  describe("sendToUsers", () => {
+    it("should record multi-user signals with all userIds", async () => {
+      const userIds = ["user-1", "user-2", "user-3"];
+      await mockService.sendToUsers(TEST_SIGNAL_A, userIds, { value: "multi" });
+
+      const recorded = mockService.getRecordedSignals();
+      expect(recorded).toHaveLength(1);
+      expect(recorded[0].targetType).toBe("users");
+      expect(recorded[0].userIds).toEqual(userIds);
+    });
+  });
+
+  describe("getRecordedSignalsById", () => {
+    it("should filter signals by ID", async () => {
+      await mockService.broadcast(TEST_SIGNAL_A, { value: "a1" });
+      await mockService.broadcast(TEST_SIGNAL_B, { count: 1 });
+      await mockService.broadcast(TEST_SIGNAL_A, { value: "a2" });
+
+      const signalARecords = mockService.getRecordedSignalsById("test.signalA");
+      expect(signalARecords).toHaveLength(2);
+      expect(signalARecords[0].payload).toEqual({ value: "a1" });
+      expect(signalARecords[1].payload).toEqual({ value: "a2" });
+    });
+
+    it("should return empty array for non-existent signal ID", () => {
+      const records = mockService.getRecordedSignalsById("non.existent");
+      expect(records).toHaveLength(0);
+    });
+  });
+
+  describe("getRecordedSignalsForUser", () => {
+    it("should return broadcasts and user-specific signals", async () => {
+      await mockService.broadcast(TEST_SIGNAL_A, { value: "broadcast" });
+      await mockService.sendToUser(TEST_SIGNAL_B, "user-1", { count: 10 });
+      await mockService.sendToUser(TEST_SIGNAL_B, "user-2", { count: 20 });
+
+      const user1Signals = mockService.getRecordedSignalsForUser("user-1");
+      expect(user1Signals).toHaveLength(2); // broadcast + user-specific
+
+      const user2Signals = mockService.getRecordedSignalsForUser("user-2");
+      expect(user2Signals).toHaveLength(2); // broadcast + user-specific
+    });
+
+    it("should include multi-user signals", async () => {
+      await mockService.sendToUsers(TEST_SIGNAL_A, ["user-1", "user-2"], {
+        value: "multi",
+      });
+
+      const user1Signals = mockService.getRecordedSignalsForUser("user-1");
+      expect(user1Signals).toHaveLength(1);
+
+      const user3Signals = mockService.getRecordedSignalsForUser("user-3");
+      expect(user3Signals).toHaveLength(0); // Not included in multi-user
+    });
+  });
+
+  describe("clearRecordedSignals", () => {
+    it("should clear all recorded signals", async () => {
+      await mockService.broadcast(TEST_SIGNAL_A, { value: "test" });
+      await mockService.sendToUser(TEST_SIGNAL_B, "user-1", { count: 1 });
+
+      expect(mockService.getRecordedSignals()).toHaveLength(2);
+
+      mockService.clearRecordedSignals();
+
+      expect(mockService.getRecordedSignals()).toHaveLength(0);
+    });
+  });
+
+  describe("wasSignalEmitted", () => {
+    it("should return true if signal was emitted", async () => {
+      await mockService.broadcast(TEST_SIGNAL_A, { value: "test" });
+
+      expect(mockService.wasSignalEmitted("test.signalA")).toBe(true);
+      expect(mockService.wasSignalEmitted("test.signalB")).toBe(false);
+    });
+  });
+
+  describe("wasSignalSentToUser", () => {
+    it("should return true if signal was sent to specific user", async () => {
+      await mockService.sendToUser(TEST_SIGNAL_A, "user-123", { value: "hi" });
+
+      expect(mockService.wasSignalSentToUser("test.signalA", "user-123")).toBe(
+        true
+      );
+      expect(mockService.wasSignalSentToUser("test.signalA", "user-456")).toBe(
+        false
+      );
+      expect(mockService.wasSignalSentToUser("test.signalB", "user-123")).toBe(
+        false
+      );
+    });
+
+    it("should work with sendToUsers", async () => {
+      await mockService.sendToUsers(TEST_SIGNAL_B, ["user-1", "user-2"], {
+        count: 5,
+      });
+
+      expect(mockService.wasSignalSentToUser("test.signalB", "user-1")).toBe(
+        true
+      );
+      expect(mockService.wasSignalSentToUser("test.signalB", "user-2")).toBe(
+        true
+      );
+      expect(mockService.wasSignalSentToUser("test.signalB", "user-3")).toBe(
+        false
+      );
+    });
+  });
+
+  describe("multiple signal mixtures", () => {
+    it("should correctly track complex emission patterns", async () => {
+      // Simulate realistic notification scenario
+      await mockService.broadcast(TEST_SIGNAL_A, { value: "system-alert" });
+      await mockService.sendToUser(TEST_SIGNAL_B, "admin-1", { count: 5 });
+      await mockService.sendToUser(TEST_SIGNAL_B, "admin-2", { count: 3 });
+      await mockService.sendToUsers(TEST_SIGNAL_A, ["user-1", "user-2"], {
+        value: "team-update",
+      });
+      await mockService.broadcast(TEST_SIGNAL_B, { count: 100 });
+
+      // Total signals
+      expect(mockService.getRecordedSignals()).toHaveLength(5);
+
+      // By signal ID
+      expect(mockService.getRecordedSignalsById("test.signalA")).toHaveLength(
+        2
+      );
+      expect(mockService.getRecordedSignalsById("test.signalB")).toHaveLength(
+        3
+      );
+
+      // For specific users
+      expect(mockService.getRecordedSignalsForUser("admin-1")).toHaveLength(3); // 2 broadcast + 1 user
+      expect(mockService.getRecordedSignalsForUser("user-1")).toHaveLength(3); // 2 broadcast + 1 multi
+
+      // Emission checks
+      expect(mockService.wasSignalEmitted("test.signalA")).toBe(true);
+      expect(mockService.wasSignalSentToUser("test.signalB", "admin-1")).toBe(
+        true
+      );
+    });
+  });
+});

package/src/mock-signal-service.ts

@@ -0,0 +1,189 @@
+import { qualifyPermissionId } from "@checkstack/common";
+import type { SignalService, Signal } from "@checkstack/signal-common";
+
+/**
+ * Recorded signal emission for testing assertions.
+ */
+export interface RecordedSignal<T = unknown> {
+  signal: Signal<T>;
+  payload: T;
+  targetType: "broadcast" | "user" | "users" | "authorized";
+  userIds?: string[];
+  permission?: string; // For authorized signals
+  timestamp: Date;
+}
+
+/**
+ * Mock SignalService for testing with recording and assertion capabilities.
+ */
+export interface MockSignalService extends SignalService {
+  /**
+   * Get all recorded signal emissions.
+   */
+  getRecordedSignals(): RecordedSignal[];
+
+  /**
+   * Get recorded signals filtered by signal ID.
+   */
+  getRecordedSignalsById(signalId: string): RecordedSignal[];
+
+  /**
+   * Get recorded signals sent to a specific user.
+   */
+  getRecordedSignalsForUser(userId: string): RecordedSignal[];
+
+  /**
+   * Clear all recorded signals.
+   */
+  clearRecordedSignals(): void;
+
+  /**
+   * Check if a specific signal was emitted.
+   */
+  wasSignalEmitted(signalId: string): boolean;
+
+  /**
+   * Check if a specific signal was sent to a user.
+   */
+  wasSignalSentToUser(signalId: string, userId: string): boolean;
+
+  /**
+   * Set a permission filter function for sendToAuthorizedUsers testing.
+   * If not set, sendToAuthorizedUsers will pass through all users.
+   */
+  setPermissionFilter(
+    filter: (userIds: string[], permission: string) => string[]
+  ): void;
+}
+
+/**
+ * Creates a mock SignalService for testing.
+ * Records all signal emissions for later assertions.
+ *
+ * @returns A mock SignalService with recording capabilities
+ *
+ * @example
+ * ```typescript
+ * import { createMockSignalService } from "@checkstack/test-utils-backend";
+ * import { NOTIFICATION_RECEIVED } from "@checkstack/notification-common";
+ *
+ * const mockSignalService = createMockSignalService();
+ *
+ * // In your code under test
+ * await mockSignalService.sendToUser(NOTIFICATION_RECEIVED, "user-123", { ... });
+ *
+ * // Assertions
+ * expect(mockSignalService.wasSignalSentToUser("notification.received", "user-123")).toBe(true);
+ * expect(mockSignalService.getRecordedSignalsForUser("user-123")).toHaveLength(1);
+ * ```
+ */
+export function createMockSignalService(): MockSignalService {
+  const recordedSignals: RecordedSignal[] = [];
+  let permissionFilter:
+    | ((userIds: string[], permission: string) => string[])
+    | undefined;
+
+  return {
+    async broadcast<T>(signal: Signal<T>, payload: T): Promise<void> {
+      recordedSignals.push({
+        signal: signal as Signal<unknown>,
+        payload,
+        targetType: "broadcast",
+        timestamp: new Date(),
+      });
+    },
+
+    async sendToUser<T>(
+      signal: Signal<T>,
+      userId: string,
+      payload: T
+    ): Promise<void> {
+      recordedSignals.push({
+        signal: signal as Signal<unknown>,
+        payload,
+        targetType: "user",
+        userIds: [userId],
+        timestamp: new Date(),
+      });
+    },
+
+    async sendToUsers<T>(
+      signal: Signal<T>,
+      userIds: string[],
+      payload: T
+    ): Promise<void> {
+      recordedSignals.push({
+        signal: signal as Signal<unknown>,
+        payload,
+        targetType: "users",
+        userIds,
+        timestamp: new Date(),
+      });
+    },
+
+    getRecordedSignals(): RecordedSignal[] {
+      return [...recordedSignals];
+    },
+
+    getRecordedSignalsById(signalId: string): RecordedSignal[] {
+      return recordedSignals.filter((r) => r.signal.id === signalId);
+    },
+
+    getRecordedSignalsForUser(userId: string): RecordedSignal[] {
+      return recordedSignals.filter(
+        (r) =>
+          r.targetType === "broadcast" ||
+          (r.userIds && r.userIds.includes(userId))
+      );
+    },
+
+    clearRecordedSignals(): void {
+      recordedSignals.length = 0;
+    },
+
+    wasSignalEmitted(signalId: string): boolean {
+      return recordedSignals.some((r) => r.signal.id === signalId);
+    },
+
+    wasSignalSentToUser(signalId: string, userId: string): boolean {
+      return recordedSignals.some(
+        (r) =>
+          r.signal.id === signalId && r.userIds && r.userIds.includes(userId)
+      );
+    },
+
+    async sendToAuthorizedUsers<T>(
+      signal: Signal<T>,
+      userIds: string[],
+      payload: T,
+      pluginMetadata: { pluginId: string },
+      permission: { id: string }
+    ): Promise<void> {
+      // Construct fully-qualified permission ID
+      const qualifiedPermission = qualifyPermissionId(
+        pluginMetadata,
+        permission
+      );
+
+      // Apply permission filter if set
+      const filteredUserIds = permissionFilter
+        ? permissionFilter(userIds, qualifiedPermission)
+        : userIds;
+
+      recordedSignals.push({
+        signal: signal as Signal<unknown>,
+        payload,
+        targetType: "authorized",
+        userIds: filteredUserIds,
+        permission: qualifiedPermission,
+        timestamp: new Date(),
+      });
+    },
+
+    setPermissionFilter(
+      filter: (userIds: string[], permission: string) => string[]
+    ): void {
+      permissionFilter = filter;
+    },
+  };
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "@checkstack/tsconfig/base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": [
+    "src/**/*"
+  ]
+}