Testing

The notifkit repository already runs 676 test cases. The first half of this page groups them by what they defend, so you don't re-prove covered failures. The second half covers what only you can test: your templates, consent data and transports.

What is already covered

The repository ships 676 test cases across 31 files: 673 unit and integration cases plus the three chaos scenarios below. Vitest enforces a 80% coverage floor on lines, functions, branches and statements, failing the build below it. All of it runs on every commit.

Grouped by what the tests defend, not by filename. Counts are cases; most assert several things.

The HTTP surface: 180 cases

The pipeline workers: 158 cases

Queue, delivery and shared primitives: 131 cases

Data, templates and compliance: 95 cases

The SDK and the contracts: 109 cases

The chaos suite

Three tests that assert not on logic but that messages survive failures. All need Docker and are slow on purpose.

npx vitest run \
  --exclude "tests/chaos/**" \
  --exclude "tests/api.integration.test.ts" \
  --exclude "tests/repositories.test.ts"

Regressions, pinned to the bug

regressions.test.ts names each case after the defect it pins, so a failure tells you which old bug came back:

What the suite does not cover

These are the gaps your own tests should fill:

• Real provider APIs. Resend and FCM are mocked at the SDK boundary, so nothing proves your API key works or your domain is verified.
• Your templates. No test knows whether {{trackingUrl}} is a key you actually send.
• Your consent data. Whether the right users are opted out of the right topics depends on your data, not the engine.
• The transports you write. The registry is tested; your send() is not.
• The dashboard. The Vite SPA under dashboard/ has no suite in this count.
• packages/mcp, also without a suite. The endpoints it calls are covered; its tool definitions aren't.
• Quiet hours and scheduling on a live clock. The release instant is computed and asserted, but no test sleeps until it arrives; the chaos and integration runs exercise the scheduler firing on the wall clock.

Running it yourself

git clone https://github.com/devkitshq/notifkit.git
cd notifkit
npm install

npm test                                  # everything, with coverage
npx vitest run tests/workers.test.ts      # one file, no Docker needed
npx vitest run tests/chaos                # the slow ones, Docker required
npx vitest                                # watch mode
npx vitest list                           # print all 676 case names without running them
npx vitest run -t "suppression gate"      # every case whose full name matches

vitest list is the fastest way to check "is this already covered?". Case names are sentences about behaviour, so grepping them usually settles it.

The rest of this page covers what the suite can't.

Writing your own tests

Notification code is awkward to test: the outcome happens elsewhere, later, and often the right behaviour is that nothing was sent. notifkit gives you a seam at the transport, where nearly all your assertions belong.

The order to build it in

The next three sections give you the pieces, in order. Build them once and every later test is four lines:

1. A capturing transport, which records instead of sending. No Docker, no provider account.
2. A server fixture: one NotifkitServer per test file, with a project bootstrapped and a client pointed at it.
3. A wait helper, since notify() returns long before delivery and a bare assertion after the call always fails.

Then the most valuable assertion you can write is that no placeholder survived rendering:

it("leaves no unrendered placeholder", async () => {
  email.reset();
  await client.addUser("usr_1", [{ channel: "email", target: "[email protected]" }]);

  const delivered = waitForDelivery(server);
  await client.notify({
    user: "usr_1",
    template: "welcome",
    channels: ["email"],
    data: { name: "Alice", company: "Acme" },
  });
  await delivered;

  expect(JSON.stringify(email.contents[0])).not.toContain("{{");
});

Three levels

Most of your suite belongs at the first level. The second verifies parts you didn't write; a handful is worth having.

A capturing transport

The test double is a class that records instead of sending. The Delivery worker only knows the Transport interface, so it substitutes cleanly for a real provider.

import type {
  Transport, NotificationDispatchedPayload, DeliveryResult, NotificationChannel,
} from "notifkit";

export class CapturingTransport implements Transport {
  readonly sent: NotificationDispatchedPayload[] = [];

  constructor(
    readonly channel: NotificationChannel = "email",
    private readonly outcome: DeliveryResult = { success: true, providerMessageId: "test-1" },
  ) {}

  async send(task: NotificationDispatchedPayload): Promise<DeliveryResult> {
    this.sent.push(task);
    return this.outcome;
  }

  // Convenience for assertions
  get contents() {
    return this.sent.map((t) => t.renderedContent.content as Record<string, string>);
  }
  reset() { this.sent.length = 0; }
}

Failure is one constructor argument away:

const flakyPush = new CapturingTransport("push", { success: false, error: "provider down" });
const deadToken = new CapturingTransport("push", { success: false, invalidToken: true });

Testing the whole pipeline

Without URLs, NotifkitServer starts throwaway Postgres and Redis containers, so an end-to-end test needs no fixture of your own. Two prerequisites. First, install the testcontainers packages: notifkit keeps them as external dev dependencies, out of the published bundle, so installing notifkit doesn't bring them.

npm install -D @testcontainers/postgresql @testcontainers/redis

Second, containers depend on NODE_ENV: anything but production gets them; production throws Missing required configuration. Set the server's nodeEnv option explicitly, since CI often pins the ambient value to production. Docker must be running either way.

import { describe, it, expect, beforeAll, afterAll } from "vitest";
import { NotifkitServer, NotifkitClient } from "notifkit";
import { CapturingTransport } from "./capturing-transport.js";

const PORT = 34567;
const email = new CapturingTransport("email");

let server: NotifkitServer;
let client: NotifkitClient;

beforeAll(async () => {
  process.env.ADMIN_API_KEY = "test-admin-key";

  server = new NotifkitServer({
    services: ["all"],
    nodeEnv: "development",
    port: PORT,
    logLevel: "silent",
    providers: [email],
  });
  await server.start();

  // Bootstrap a project and take its key.
  const res = await fetch(`http://localhost:${PORT}/v1/projects`, {
    method: "POST",
    headers: { "Content-Type": "application/json", Authorization: "Bearer test-admin-key" },
    body: JSON.stringify({ name: "test" }),
  });
  const { apiKey } = await res.json();

  client = new NotifkitClient({ baseUrl: `http://localhost:${PORT}`, apiKey });

  await client.syncTemplates({
    templates: [{
      id: "welcome",
      channel: "email",
      topic: ["transactional"],
      content: { subject: "Hi {{name}}", text: "Welcome, {{name}}." },
    }],
  });
}, 120_000);

afterAll(async () => { await server.stop(); });

Waiting for something asynchronous

notify() returns before delivery, so a bare assertion after it always fails. Wait on the server's events, not a sleep:

export function waitForDelivery(server: NotifkitServer, timeoutMs = 10_000) {
  return new Promise<{ taskId: string; channel: string }>((resolve, reject) => {
    const timer = setTimeout(() => {
      server.off("delivery:delivered", onDone);
      reject(new Error("no delivery within timeout"));
    }, timeoutMs);

    function onDone(taskId: string, _providerMessageId: string, channel: string) {
      clearTimeout(timer);
      server.off("delivery:delivered", onDone);
      resolve({ taskId, channel });
    }

    server.on("delivery:delivered", onDone);
  });
}

it("renders the template and delivers it", async () => {
  await client.addUser("usr_1", [{ channel: "email", target: "[email protected]" }]);

  const delivered = waitForDelivery(server);
  await client.notify({
    user: "usr_1",
    template: "welcome",
    channels: ["email"],
    data: { name: "Alice" },
  });
  await delivered;

  expect(email.sent).toHaveLength(1);
  expect(email.sent[0]!.destination).toBe("[email protected]");
  expect(email.contents[0]).toMatchObject({
    subject: "Hi Alice",
    text: "Welcome, Alice.",
  });
});

Asserting that nothing was sent

Half of what you'll prove is a negative: the opt-out worked, quiet hours held. There's no delivery event to wait on, so listen for the skip:

function waitForSkip(server: NotifkitServer, timeoutMs = 10_000) {
  return new Promise<{ reason: string }>((resolve, reject) => {
    const timer = setTimeout(() => reject(new Error("no skip event")), timeoutMs);
    server.once("notification:skipped", (payload: any) => {
      clearTimeout(timer);
      resolve(payload);
    });
  });
}

it("does not send to a user who opted out of the topic", async () => {
  await client.addUser("usr_2", [{ channel: "email", target: "[email protected]" }], {
    preferences: { topics: { transactional: false } },
  });

  email.reset();
  const skipped = waitForSkip(server);
  await client.notify({ user: "usr_2", template: "welcome", channels: ["email"] });

  expect((await skipped).reason).toBe("user_opted_out");
  expect(email.sent).toHaveLength(0);
});

Testing a fallback chain

const push = new CapturingTransport("push", { success: false, error: "device unreachable" });
const email = new CapturingTransport("email");

// server started with providers: [push, email]

it("rolls over to email when push fails", async () => {
  await client.addUser("usr_3", [
    { channel: "email", target: "[email protected]" },
    { channel: "push", target: "tok_dead" }
  ]);

  const delivered = waitForDelivery(server, 20_000);
  await client.notify({
    user: "usr_3",
    template: "welcome",
    channels: ["push", "email"],
    fallback: true,
  });

  expect((await delivered).channel).toBe("email");
  expect(push.sent).toHaveLength(1);    // tried first
  expect(email.sent).toHaveLength(1);   // then rolled over
});

Give fallback tests a longer timeout: rollover re-enters the pipeline at the enriched stream and passes through the Engine again.

Testing time-dependent behaviour

Fake timers don't help: the deferral lives in Redis and a poller elsewhere releases it. Assert on the decision, not the eventual send:

it("defers a normal-priority send during quiet hours", async () => {
  await client.addUser("usr_4", [{ channel: "email", target: "[email protected]" }], {
    timezone: "UTC",
    // A window that certainly contains "now".
    preferences: { quietHours: [{ start: "00:00", end: "23:59" }] },
  });

  email.reset();
  await client.notify({ user: "usr_4", template: "welcome", channels: ["email"] });

  await new Promise((r) => setTimeout(r, 2000));
  expect(email.sent).toHaveLength(0);                       // held, not sent

  const { scheduled } = await fetch(`${base}/v1/notifications/scheduled`, { headers })
    .then((r) => r.json());
  expect(scheduled.length).toBeGreaterThan(0);              // parked for later
});

it("lets a critical send through quiet hours", async () => {
  const delivered = waitForDelivery(server);
  await client.notify({
    user: "usr_4", template: "welcome", channels: ["email"], priority: "critical",
  });
  await expect(delivered).resolves.toBeTruthy();
});

Testing your own transport in isolation

A transport is a plain class. Give it a payload and assert on what it does, with no server, containers or Docker.

import type { NotificationDispatchedPayload } from "notifkit";

const task = {
  projectId: "p_1",
  taskId: "t_1",
  enrichedEventId: "e_1",
  recipientId: "usr_1",
  channel: "webhook",
  priority: "normal",
  templateId: "welcome",
  templateVariables: { name: "Alice" },
  recipient: { id: "usr_1", locale: "en", timezone: "UTC", preferences: {} },
  renderedContent: { content: { text: "Welcome, Alice." } },
  destination: "https://hooks.example.com/abc",
  deliveryOptions: { maxAttempts: 3, timeoutMs: 10_000 },
} as unknown as NotificationDispatchedPayload;

it("posts the rendered text and reports the provider id", async () => {
  const fetchMock = vi.fn().mockResolvedValue(
    new Response(null, { status: 200, headers: { "x-slack-req-id": "req_9" } }),
  );
  vi.stubGlobal("fetch", fetchMock);

  const result = await new SlackTransport().send(task);

  expect(result).toEqual({ success: true, providerMessageId: "req_9" });
  expect(JSON.parse(fetchMock.mock.calls[0]![1].body)).toEqual({ text: "Welcome, Alice." });
});

Testing workflows

Workflows suspend on wait and the wake-up poller runs every five seconds, so real durations make slow tests. Use short waits and assert on step outputs, not elapsed time.

workflow("test-flow", async ({ step, event }) => {
  await step.notify({ template: "welcome", channels: ["email"] });
  await step.wait(process.env.NODE_ENV === "test" ? "1s" : "3d");
  await step.notify({ template: "follow-up", channels: ["email"] });
});

it("sends both messages across the wait", async () => {
  const { instanceId } = await client.triggerWorkflow({
    name: "test-flow",
    input: { user: { id: "usr_5" } },
  });

  await vi.waitFor(async () => {
    const instance = await client.getWorkflow(instanceId);
    expect(instance.status).toBe("completed");
  }, { timeout: 30_000, interval: 1000 });

  expect(email.sent).toHaveLength(2);
});

Habits that keep the suite honest

• Give every test its own user id and idempotency key. Markers last an hour (24 hours for an x-idempotency-key), so reusing one makes the second test silently do nothing.
• Run with logLevel: "silent"; the chatty pipeline buries useful failures.
• Start one server per file in beforeAll, never beforeEach; container startup dominates runtime.
• Reset transports between tests instead of recreating the server.
• Never assert right after notify(). Wait on an event or poll with vi.waitFor; a bare setTimeout is the flakiest option.
• Mind the throttle: a hundred sends to one user in a test hits the hourly cap, and the rest vanish.