Testing

Two halves. First, every one of the 676 cases the NotifKit repository already runs, grouped by what it defends — so you know which failures are covered and do not spend your budget re-proving them. Then how to test the part nobody else can: your templates, your consent data, and your own transports.

What is already covered

The suite that ships with the repository is 676 test cases across 31 files — 673 unit and integration cases plus the three chaos scenarios below. Vitest runs them with a coverage floor of 80% on lines, functions, branches and statements; the build fails below that. Everything in this section already runs on every commit.

Grouped by what they defend, rather than by filename. Counts are cases, not assertions — most cases 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 do not assert on logic at all — they assert that messages survive things going wrong. All three need Docker, and they 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 locks down, so a failure tells you which old bug came back:

What the suite does not cover

Worth being explicit, because these are exactly the gaps your own tests should fill:

• Real provider APIs. Resend and FCM are mocked at the SDK boundary. Nothing here proves your API key works or that 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 is a property of your data, not the engine.
• Transports you write. The registry is tested; your send() is not.
• The dashboard. The Next.js app under dashboard/ has no suite in this count.
• The MCP server. packages/mcp has no suite either. The endpoints it calls are covered; the tool definitions wrapping them are not.
• Live quiet-hours and scheduling. The release instant is computed and asserted, but no test sleeps until it arrives — that the scheduler fires on the wall clock is what the chaos and integration runs exercise, not a unit case.

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 answer "is this behaviour already covered?" — the case names in this suite are written as sentences about behaviour, so grepping them usually settles it without opening a file.

The rest of this page is how to cover what the suite above cannot.

Writing your own tests

Notification code is awkward to test because the interesting outcome happens somewhere else, later, and often the correct behaviour is that nothing was sent. NotifKit gives you a seam at the transport, which is where nearly all of your assertions belong.

The order to build it in

The three sections after this one give you the pieces, and they only make sense in order. Build them once and every later test is four lines:

1. A capturing transport — 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 — because notify() returns long before anything is delivered, so a bare assertion after the call always fails.

With those in place, the single highest-value assertion you can write is that no placeholder survived rendering:

it("leaves no unrendered placeholder", async () => {
  email.reset();
  await client.addUser({ id: "usr_1", email: "a@example.com" });

  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 should sit at the first level. The second is where you verify the parts of the system you did not write, and it is worth having a handful of those.

A capturing transport

The whole test double is a class that records instead of sending. Because the Delivery worker only knows the Transport interface, this 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

NotifkitServer starts throwaway Postgres and Redis containers when you do not give it URLs, so an end-to-end test needs no fixture of your own. Two prerequisites, though. The first: the testcontainers packages have to be installed. NotifKit keeps them as dev dependencies and marks them external so they stay out of the published bundle — installing notifkit does not bring them with it.

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

The second: the container path is gated on NODE_ENV. Anything other than production gets containers; production throws Missing required configuration instead. Set it explicitly with the server's nodeEnv option rather than trusting the ambient value, which CI often pins to production. Docker has to 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 anything is delivered, so a bare assertion after the call always fails. Wait on the server's events rather than on 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({ id: "usr_1", email: "a@example.com" });

  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("a@example.com");
  expect(email.contents[0]).toMatchObject({
    subject: "Hi Alice",
    text: "Welcome, Alice.",
  });
});

Asserting that nothing was sent

Half of what you want to prove is a negative — the opt-out worked, the quiet hours held. Those have no delivery event to wait on, so listen for the skip instead:

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({
    id: "usr_2",
    email: "b@example.com",
    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({ id: "usr_3", email: "c@example.com", pushToken: "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 than single-channel ones. Rollover re-enters the pipeline at the enriched stream, so it goes through the Engine a second time.

Testing time-dependent behaviour

Fake timers do not help here — the deferral lives in Redis and is released by a poller in another part of the system. Assert on the decision rather than on the eventual send:

it("defers a normal-priority send during quiet hours", async () => {
  await client.addUser({
    id: "usr_4",
    email: "d@example.com",
    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 — no server, no containers, no 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 for slow tests. Use short waits, and assert on step outputs rather than on 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

• Unique user ids per test. Idempotency guards run for 24 hours; reusing an id across tests makes the second one mysteriously do nothing.
• logLevel: "silent". The pipeline is chatty, and useful failures get buried.
• One server per file. Container startup dominates the runtime; beforeAll, not beforeEach.
• Reset transports between tests rather than recreating the server.
• Never assert immediately after notify(). Wait on an event, or poll with vi.waitFor. A bare setTimeout is the flakiest thing you can write here.
• Keep the throttle in mind. A hundred sends to one user in a single test hits the hourly cap and the rest vanish.