The testing pyramid: unit, integration, e2e

npm init -y && npm pkg set type=module
npm install --save-exact express@5.3.0
npm install -D --save-exact vitest@5.0.3 typescript@7.0.2 @types/express@5.0.6 @types/node@24

export type LeadInput = { name?: unknown; phone?: unknown; consent?: unknown };
export type Lead = { name: string; phone: string };
export type Validation =
  | { ok: true; lead: Lead }
  | { ok: false; errors: Record<string, string> };

// "8 (707) 123-45-67", "+7 707 123 45 67", "7071234567" -> "+77071234567"
export function normalizePhone(raw: string): string | null {
  const digits = raw.replace(/\D/g, "");
  if (digits.length === 10) return `+7${digits}`;
  if (digits.length === 11 && (digits[0] === "7" || digits[0] === "8")) return `+7${digits.slice(1)}`;
  return null;
}

export function validateLead(input: LeadInput): Validation {
  const errors: Record<string, string> = {};
  const name = typeof input.name === "string" ? input.name.trim() : "";
  const phone = typeof input.phone === "string" ? normalizePhone(input.phone) : null;
  if (name.length < 2) errors.name = "name_too_short";
  if (!phone) errors.phone = "phone_invalid";
  if (input.consent !== true) errors.consent = "consent_required";
  if (!phone || Object.keys(errors).length > 0) return { ok: false, errors };
  return { ok: true, lead: { name, phone } };
}

import { validateLead, type Lead, type LeadInput } from "./lead";

export interface LeadRepo {
  findRecentByPhone(phone: string, since: Date): Promise<{ id: number } | null>;
  insert(lead: Lead, createdAt: Date): Promise<number>;
}
export type Notify = (lead: Lead & { id: number }) => Promise<void>;

export type SubmitResult =
  | { status: "created"; id: number }
  | { status: "duplicate"; id: number }
  | { status: "invalid"; errors: Record<string, string> };

const DAY_MS = 24 * 60 * 60 * 1000;

export function createLeadService(deps: { repo: LeadRepo; notify: Notify; now?: () => Date }) {
  const now = deps.now ?? (() => new Date());

  return {
    async submit(input: LeadInput): Promise<SubmitResult> {
      const checked = validateLead(input);
      if (!checked.ok) return { status: "invalid", errors: checked.errors };

      const at = now();
      const since = new Date(at.getTime() - DAY_MS);
      const recent = await deps.repo.findRecentByPhone(checked.lead.phone, since);
      if (recent) return { status: "duplicate", id: recent.id };

      const id = await deps.repo.insert(checked.lead, at);
      try {
        await deps.notify({ ...checked.lead, id });
      } catch {
        // the lead is already saved: a failed notification must not lose it
      }
      return { status: "created", id };
    },
  };
}

export type LeadService = ReturnType<typeof createLeadService>;

import { DatabaseSync } from "node:sqlite";
import type { LeadRepo } from "./lead-service";

export function openDb(path = ":memory:"): DatabaseSync {
  const db = new DatabaseSync(path);
  db.exec(`CREATE TABLE IF NOT EXISTS leads (
    id         INTEGER PRIMARY KEY AUTOINCREMENT,
    name       TEXT NOT NULL,
    phone      TEXT NOT NULL,
    created_at TEXT NOT NULL
  )`);
  return db;
}

export function createSqliteRepo(db: DatabaseSync): LeadRepo {
  const findRecent = db.prepare(
    "SELECT id FROM leads WHERE phone = ? AND created_at >= ? ORDER BY id DESC LIMIT 1",
  );
  const insert = db.prepare("INSERT INTO leads (name, phone, created_at) VALUES (?, ?, ?)");

  return {
    async findRecentByPhone(phone, since) {
      const row = findRecent.get(phone, since.toISOString());
      return row ? { id: Number(row.id) } : null;
    },
    async insert(lead, createdAt) {
      const result = insert.run(lead.name, lead.phone, createdAt.toISOString());
      return Number(result.lastInsertRowid);
    },
  };
}

import express from "express";
import type { LeadService } from "./lead-service";

export function createApp(leads: LeadService) {
  const app = express();
  app.use(express.json());

  app.post("/api/leads", async (req, res) => {
    const result = await leads.submit(req.body ?? {});
    if (result.status === "invalid") return res.status(422).json({ errors: result.errors });
    if (result.status === "duplicate") return res.status(409).json({ error: "duplicate", id: result.id });
    res.status(201).json({ id: result.id });
  });

  return app;
}

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    projects: [
      { test: { name: "unit", include: ["tests/unit/**/*.test.ts"] } },
      { test: { name: "integration", include: ["tests/integration/**/*.test.ts"] } },
    ],
  },
});

import { describe, expect, it } from "vitest";
import { normalizePhone, validateLead } from "../../src/lead";

describe("normalizePhone", () => {
  it.each([
    ["8 (707) 123-45-67", "+77071234567"],
    ["+7 707 123 45 67", "+77071234567"],
    ["7071234567", "+77071234567"],
    ["87071234567", "+77071234567"],
  ])("%s -> %s", (raw, expected) => {
    expect(normalizePhone(raw)).toBe(expected);
  });

  it.each(["", "12345", "9 707 123 45 67", "+1 202 555 0100 1"])("rejects %j", (raw) => {
    expect(normalizePhone(raw)).toBeNull();
  });
});

describe("validateLead", () => {
  it("returns a normalized lead", () => {
    expect(validateLead({ name: "  Aigerim ", phone: "8 707 123 45 67", consent: true })).toEqual({
      ok: true,
      lead: { name: "Aigerim", phone: "+77071234567" },
    });
  });

  it("collects every error at once", () => {
    expect(validateLead({ name: "A", phone: "123", consent: false })).toEqual({
      ok: false,
      errors: { name: "name_too_short", phone: "phone_invalid", consent: "consent_required" },
    });
  });
});

import { describe, expect, it, vi } from "vitest";
import { createLeadService, type LeadRepo } from "../../src/lead-service";

type Row = { id: number; phone: string; createdAt: Date };

// a fake repository: a plain array instead of a database
function fakeRepo(): LeadRepo & { rows: Row[] } {
  const rows: Row[] = [];
  return {
    rows,
    async findRecentByPhone(phone, since) {
      const row = rows.findLast((r) => r.phone === phone && r.createdAt >= since);
      return row ? { id: row.id } : null;
    },
    async insert(lead, createdAt) {
      rows.push({ id: rows.length + 1, phone: lead.phone, createdAt });
      return rows.length;
    },
  };
}

const valid = { name: "Aigerim", phone: "+7 707 123 45 67", consent: true };

describe("lead service", () => {
  it("rejects a repeat within 24 hours and accepts it after", async () => {
    let now = new Date("2026-10-11T09:00:00Z");
    const service = createLeadService({ repo: fakeRepo(), notify: vi.fn(), now: () => now });

    expect(await service.submit(valid)).toEqual({ status: "created", id: 1 });
    now = new Date("2026-10-12T08:59:00Z"); // 23 h 59 min later
    expect(await service.submit(valid)).toEqual({ status: "duplicate", id: 1 });
    now = new Date("2026-10-12T09:01:00Z"); // 24 h 1 min later
    expect(await service.submit(valid)).toEqual({ status: "created", id: 2 });
  });

  it("keeps the lead when the notification fails", async () => {
    const repo = fakeRepo();
    const notify = vi.fn().mockRejectedValue(new Error("telegram is down"));
    const service = createLeadService({ repo, notify });

    expect(await service.submit(valid)).toEqual({ status: "created", id: 1 });
    expect(repo.rows).toHaveLength(1);
    expect(notify).toHaveBeenCalledOnce();
  });

  it("does not touch the repository for invalid input", async () => {
    const repo = fakeRepo();
    const insert = vi.spyOn(repo, "insert");
    const service = createLeadService({ repo, notify: vi.fn() });

    const result = await service.submit({ name: "Aigerim", phone: "123", consent: true });
    expect(result.status).toBe("invalid");
    expect(insert).not.toHaveBeenCalled();
  });
});

import type { Server } from "node:http";
import type { AddressInfo } from "node:net";
import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
import { createApp } from "../../src/app";
import { createLeadService } from "../../src/lead-service";
import { createSqliteRepo, openDb } from "../../src/sqlite-repo";

// real HTTP, routing, JSON parsing and SQL; only the external notifier is a double
const db = openDb(":memory:");
const notify = vi.fn().mockResolvedValue(undefined);
let now = new Date("2026-10-11T09:00:00Z");
const app = createApp(createLeadService({ repo: createSqliteRepo(db), notify, now: () => now }));

let server: Server;
let base: string;

beforeAll(async () => {
  server = app.listen(0); // port 0: the OS picks a free port
  await new Promise((resolve) => server.once("listening", resolve));
  base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
});
afterAll(() => new Promise((resolve) => server.close(resolve)));

beforeEach(() => {
  db.exec("DELETE FROM leads"); // every test starts from an empty table
  notify.mockClear();
  now = new Date("2026-10-11T09:00:00Z");
});

const post = (body: unknown) =>
  fetch(`${base}/api/leads`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(body),
  });

describe("POST /api/leads", () => {
  it("201: saves a normalized phone and notifies once", async () => {
    const res = await post({ name: "Aigerim", phone: "8 (707) 123-45-67", consent: true });

    expect(res.status).toBe(201);
    const { id } = await res.json();
    expect(db.prepare("SELECT name, phone FROM leads WHERE id = ?").get(id)).toEqual({
      name: "Aigerim",
      phone: "+77071234567",
    });
    expect(notify).toHaveBeenCalledOnce();
  });

  it("422: returns field errors and writes nothing", async () => {
    const res = await post({ name: "Aigerim", phone: "123" });

    expect(res.status).toBe(422);
    expect(await res.json()).toEqual({ errors: { phone: "phone_invalid", consent: "consent_required" } });
    expect(db.prepare("SELECT count(*) AS n FROM leads").get()).toEqual({ n: 0 });
  });

  it("409: the same phone in another format within 24 hours", async () => {
    await post({ name: "Aigerim", phone: "+7 707 123 45 67", consent: true });
    now = new Date("2026-10-11T20:00:00Z");
    const res = await post({ name: "Aigerim", phone: "87071234567", consent: true });

    expect(res.status).toBe(409);
    expect(db.prepare("SELECT count(*) AS n FROM leads").get()).toEqual({ n: 1 });
  });
});

$ npx tsc -p .
$ npx vitest run --project unit
 Test Files  2 passed (2)
      Tests  13 passed (13)
   Duration  183ms (transform 54%, import 27%, worker 9%, tests 9%)

$ npx vitest run --project integration --reporter verbose
 ✓ |integration| tests/integration/leads.api.test.ts > POST /api/leads > 201: saves a normalized phone and notifies once 32ms
 ✓ |integration| tests/integration/leads.api.test.ts > POST /api/leads > 422: returns field errors and writes nothing 3ms
 ✓ |integration| tests/integration/leads.api.test.ts > POST /api/leads > 409: the same phone in another format within 24 hours 18ms
 Test Files  1 passed (1)
      Tests  3 passed (3)
   Duration  315ms (import 46%, tests 30%, transform 22%, worker 2%)

--- a/src/sqlite-repo.ts
+++ b/src/sqlite-repo.ts
   const findRecent = db.prepare(
-    "SELECT id FROM leads WHERE phone = ? AND created_at >= ? ORDER BY id DESC LIMIT 1",
+    "SELECT id FROM leads WHERE phone = ? AND created_at <= ? ORDER BY id DESC LIMIT 1",
   );

$ npx vitest run
 ❯ |integration| tests/integration/leads.api.test.ts (3 tests | 1 failed) 72ms
   ❯ POST /api/leads (3)
     × 409: the same phone in another format within 24 hours 31ms

 FAIL  |integration| tests/integration/leads.api.test.ts > POST /api/leads > 409: the same phone in another format within 24 hours
AssertionError: expected 201 to be 409 // Object.is equality
 ❯ tests/integration/leads.api.test.ts:63:24

 Test Files  1 failed | 2 passed (3)
      Tests  1 failed | 15 passed (16)

$ npx vitest run --sequence.shuffle
 Test Files  3 passed (3)
      Tests  16 passed (16)