Update testing framework to Vitest (#4)

.vscode/settings.json

@@ -0,0 +1,17 @@
+{
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "editor.defaultFormatter": "biomejs.biome",
+  "editor.formatOnSave": true,
+  "editor.formatOnPaste": true,
+  "emmet.showExpandedAbbreviation": "never",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.biome": "explicit",
+    "source.organizeImports.biome": "explicit"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  }
+}

README.md

@@ -155,9 +155,11 @@ Timeouts are enforced per request using a simple race against `timeoutMs` (defau
 ## Development
 
 - Build: `npm run build`
-- Test: `npm test`
+- Test: `npm test` (Vitest)
   - By default, tests are offline/deterministic.
-  - Smoke tests that hit the network are gated by `SMOKE=1`, e.g. `SMOKE=1 npm test`.
+  - Watch mode: `npm run test:watch`
+  - Coverage: `npm run test:coverage`
+  - Smoke tests that hit the network are gated by `SMOKE=1`, e.g. `SMOKE=1 npm run test:smoke`.
 - Lint/format: `npm run lint` (Biome)
 
 Project layout:

package.json

@@ -28,7 +28,10 @@
   "scripts": {
     "clean": "rm -rf dist",
     "build": "npm run clean && tsc -p tsconfig.build.json",
-    "test": "npm run clean && tsc -p tsconfig.json && node --test dist/**/*.test.js",
+    "test": "npm run clean && tsc -p tsconfig.json && vitest run",
+    "test:watch": "npm run clean && tsc -p tsconfig.json && vitest",
+    "test:coverage": "npm run clean && tsc -p tsconfig.json && vitest run --coverage",
+    "test:smoke": "SMOKE=1 npm run test",
     "lint": "biome check --write",
     "prepublishOnly": "npm run build"
   },
@@ -39,7 +42,9 @@
     "@biomejs/biome": "2.2.4",
     "@types/node": "24.5.2",
     "@types/psl": "1.1.3",
-    "typescript": "5.9.2"
+    "@vitest/coverage-v8": "^3.2.4",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4"
   },
   "engines": {
     "node": ">=18.17"

src/index.smoke.test.ts

@@ -1,8 +1,7 @@
 /** biome-ignore-all lint/style/noNonNullAssertion: this is fine for tests */
 
-import assert from "node:assert/strict";
-import test from "node:test";
-import { isAvailable, isRegistered, lookupDomain } from "../index.js";
+import { expect, test } from "vitest";
+import { isAvailable, isRegistered, lookupDomain } from "./index.js";
 
 // Run only when SMOKE=1 to avoid flakiness and network in CI by default
 const shouldRun = process.env.SMOKE === "1";
@@ -15,10 +14,12 @@ const shouldRun = process.env.SMOKE === "1";
       timeoutMs: 12000,
       followWhoisReferral: true,
     });
-    assert.equal(res.ok, true, res.error);
-    assert.ok(res.record?.domain);
-    assert.ok(res.record?.tld);
-    assert.ok(res.record?.source === "rdap" || res.record?.source === "whois");
+    expect(res.ok, res.error).toBe(true);
+    expect(Boolean(res.record?.domain)).toBe(true);
+    expect(Boolean(res.record?.tld)).toBe(true);
+    expect(
+      res.record?.source === "rdap" || res.record?.source === "whois",
+    ).toBe(true);
   },
 );
 
@@ -37,28 +38,28 @@ for (const c of rdapCases) {
         timeoutMs: 15000,
         rdapOnly: true,
       });
-      assert.equal(res.ok, true, res.error);
+      expect(res.ok, res.error).toBe(true);
       const rec = res.record!;
-      assert.equal(rec.tld, c.tld);
-      assert.equal(rec.source, "rdap");
+      expect(rec.tld).toBe(c.tld);
+      expect(rec.source).toBe("rdap");
       // Registrar ID is IANA (376) for example domains
-      assert.equal(rec.registrar?.ianaId, "376");
+      expect(rec.registrar?.ianaId).toBe("376");
       if (c.tld !== "org") {
         // .com/.net often include the IANA reserved name explicitly
-        assert.ok(
+        expect(
           (rec.registrar?.name || "")
             .toLowerCase()
             .includes("internet assigned numbers authority"),
-        );
+        ).toBe(true);
       }
       // IANA nameservers
       const ns = (rec.nameservers || []).map((n) => n.host.toLowerCase());
-      assert.ok(ns.includes("a.iana-servers.net"));
-      assert.ok(ns.includes("b.iana-servers.net"));
+      expect(ns.includes("a.iana-servers.net")).toBe(true);
+      expect(ns.includes("b.iana-servers.net")).toBe(true);
       if (c.expectDs) {
         // DS records typically present for .com/.net
-        assert.equal(rec.dnssec?.enabled, true);
-        assert.ok((rec.dnssec?.dsRecords || []).length > 0);
+        expect(rec.dnssec?.enabled).toBe(true);
+        expect((rec.dnssec?.dsRecords || []).length > 0).toBe(true);
       }
     },
   );
@@ -72,7 +73,7 @@ for (const c of rdapCases) {
       timeoutMs: 15000,
       rdapOnly: true,
     });
-    assert.equal(res.ok, false);
+    expect(res.ok).toBe(false);
   },
 );
 
@@ -85,18 +86,17 @@ for (const c of rdapCases) {
       whoisOnly: true,
       followWhoisReferral: true,
     });
-    assert.equal(res.ok, true, res.error);
-    assert.equal(res.record?.tld, "com");
-    assert.equal(res.record?.source, "whois");
+    expect(res.ok, res.error).toBe(true);
+    expect(res.record?.tld).toBe("com");
+    expect(res.record?.source).toBe("whois");
     // Invariants for example.com
-    assert.equal(
-      res.record?.whoisServer?.toLowerCase(),
+    expect(res.record?.whoisServer?.toLowerCase()).toBe(
       "whois.verisign-grs.com",
     );
-    assert.equal(res.record?.registrar?.ianaId, "376");
+    expect(res.record?.registrar?.ianaId).toBe("376");
     const ns = (res.record?.nameservers || []).map((n) => n.host.toLowerCase());
-    assert.ok(ns.includes("a.iana-servers.net"));
-    assert.ok(ns.includes("b.iana-servers.net"));
+    expect(ns.includes("a.iana-servers.net")).toBe(true);
+    expect(ns.includes("b.iana-servers.net")).toBe(true);
   },
 );
 
@@ -107,28 +107,30 @@ for (const c of rdapCases) {
     whoisOnly: true,
     followWhoisReferral: true,
   });
-  assert.equal(res.ok, true, res.error);
+  expect(res.ok, res.error).toBe(true);
   const rec = res.record!;
-  assert.equal(rec.tld, "io");
-  assert.equal(rec.source, "whois");
+  expect(rec.tld).toBe("io");
+  expect(rec.source).toBe("whois");
   // Accept either TLD WHOIS or registrar WHOIS as the final server
   const server = (rec.whoisServer || "").toLowerCase();
-  assert.ok(["whois.nic.io", "whois.namecheap.com"].includes(server));
+  expect(["whois.nic.io", "whois.namecheap.com"].includes(server)).toBe(true);
   // Registrar ID may only be present on registrar WHOIS responses
   if (rec.registrar?.ianaId) {
-    assert.equal(rec.registrar.ianaId, "1068");
+    expect(rec.registrar.ianaId).toBe("1068");
   }
   // Nameservers commonly set for example.io (DigitalOcean)
   const ns = (rec.nameservers || []).map((n) => n.host.toLowerCase());
-  assert.ok(ns.includes("ns1.digitalocean.com"));
-  assert.ok(ns.includes("ns2.digitalocean.com"));
-  assert.ok(ns.includes("ns3.digitalocean.com"));
+  expect(ns.includes("ns1.digitalocean.com")).toBe(true);
+  expect(ns.includes("ns2.digitalocean.com")).toBe(true);
+  expect(ns.includes("ns3.digitalocean.com")).toBe(true);
 });
 
 (shouldRun ? test : test.skip)(
   "isRegistered true for example.com",
   async () => {
-    assert.equal(await isRegistered("example.com", { timeoutMs: 15000 }), true);
+    await expect(
+      isRegistered("example.com", { timeoutMs: 15000 }),
+    ).resolves.toBe(true);
   },
 );
 
@@ -136,6 +138,8 @@ for (const c of rdapCases) {
   "isAvailable true for an unlikely .com",
   async () => {
     const unlikely = `nonexistent-${Date.now()}-smoke-example.com`;
-    assert.equal(await isAvailable(unlikely, { timeoutMs: 15000 }), true);
+    await expect(isAvailable(unlikely, { timeoutMs: 15000 })).resolves.toBe(
+      true,
+    );
   },
 );

src/index.test.ts

@@ -0,0 +1,190 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// Shared, safe default mocks. Individual describes override implementations as needed.
+vi.mock("./rdap/bootstrap.js", () => ({
+  getRdapBaseUrlsForTld: vi.fn(async () => ["https://rdap.example/"]),
+}));
+
+vi.mock("./rdap/client.js", () => ({
+  fetchRdapDomain: vi.fn(async () => ({
+    url: "https://rdap.example/domain/example.com",
+    json: { ldhName: "example.com" },
+  })),
+}));
+
+vi.mock("./whois/client.js", () => ({
+  whoisQuery: vi.fn(async () => ({
+    text: "Domain Name: EXAMPLE.COM",
+    serverQueried: "whois.verisign-grs.com",
+  })),
+}));
+
+vi.mock("./whois/discovery.js", async () => {
+  const actual = await vi.importActual("./whois/discovery.js");
+  return {
+    ...actual,
+    ianaWhoisServerForTld: vi.fn(async () => "whois.verisign-grs.com"),
+  };
+});
+
+vi.mock("./lib/domain.js", async () => {
+  const actual =
+    await vi.importActual<typeof import("./lib/domain.js")>("./lib/domain.js");
+  return {
+    ...actual,
+    // Default to actual behavior; specific tests can override
+    getDomainParts: vi.fn((domain: string) => actual.getDomainParts(domain)),
+  };
+});
+
+import { lookupDomain } from "./index.js";
+import * as domain from "./lib/domain.js";
+import * as rdapClient from "./rdap/client.js";
+import type { WhoisQueryResult } from "./whois/client.js";
+import * as whoisClient from "./whois/client.js";
+import * as discovery from "./whois/discovery.js";
+
+// 1) Orchestration tests (RDAP path, fallback, whoisOnly)
+describe("lookupDomain orchestration", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(discovery.ianaWhoisServerForTld).mockResolvedValue(
+      "whois.verisign-grs.com",
+    );
+  });
+
+  it("uses RDAP when available and does not call WHOIS", async () => {
+    const res = await lookupDomain("example.com", { timeoutMs: 200 });
+    expect(res.ok, res.error).toBe(true);
+    expect(res.record?.source).toBe("rdap");
+    expect(vi.mocked(rdapClient.fetchRdapDomain)).toHaveBeenCalledOnce();
+    expect(vi.mocked(whoisClient.whoisQuery)).not.toHaveBeenCalled();
+  });
+
+  it("falls back to WHOIS when RDAP fails", async () => {
+    vi.mocked(rdapClient.fetchRdapDomain).mockRejectedValueOnce(
+      new Error("rdap down"),
+    );
+    const res = await lookupDomain("example.com", { timeoutMs: 200 });
+    expect(res.ok, res.error).toBe(true);
+    expect(res.record?.source).toBe("whois");
+    expect(vi.mocked(whoisClient.whoisQuery)).toHaveBeenCalledOnce();
+  });
+
+  it("respects whoisOnly to skip RDAP entirely", async () => {
+    const res = await lookupDomain("example.com", {
+      timeoutMs: 200,
+      whoisOnly: true,
+    });
+    expect(res.ok, res.error).toBe(true);
+    expect(res.record?.source).toBe("whois");
+    expect(vi.mocked(rdapClient.fetchRdapDomain)).not.toHaveBeenCalled();
+    expect(vi.mocked(whoisClient.whoisQuery)).toHaveBeenCalled();
+  });
+});
+
+// 2) WHOIS referral toggle and includeRaw behavior
+describe("WHOIS referral & includeRaw", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(discovery.ianaWhoisServerForTld).mockResolvedValue(
+      "whois.verisign-grs.com",
+    );
+  });
+
+  it("does not follow referral when followWhoisReferral is false", async () => {
+    vi.mocked(whoisClient.whoisQuery).mockImplementation(
+      async (server: string): Promise<WhoisQueryResult> => {
+        if (server === "whois.verisign-grs.com") {
+          return {
+            text: "Registrar WHOIS Server: whois.registrar.test\nDomain Name: EXAMPLE.COM",
+            serverQueried: "whois.verisign-grs.com",
+          };
+        }
+        return {
+          text: "Domain Name: EXAMPLE.COM\nRegistrar: Registrar LLC",
+          serverQueried: "whois.registrar.test",
+        };
+      },
+    );
+
+    const res = await lookupDomain("example.com", {
+      timeoutMs: 200,
+      whoisOnly: true,
+      followWhoisReferral: false,
+    });
+    expect(res.ok, res.error).toBe(true);
+    expect(vi.mocked(whoisClient.whoisQuery)).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(whoisClient.whoisQuery).mock.calls[0][0]).toBe(
+      "whois.verisign-grs.com",
+    );
+  });
+
+  it("includes rawWhois when includeRaw is true", async () => {
+    vi.mocked(whoisClient.whoisQuery).mockImplementation(
+      async (server: string): Promise<WhoisQueryResult> => {
+        if (server === "whois.verisign-grs.com") {
+          return {
+            text: "Registrar WHOIS Server: whois.registrar.test\nDomain Name: EXAMPLE.COM",
+            serverQueried: "whois.verisign-grs.com",
+          };
+        }
+        return {
+          text: "Domain Name: EXAMPLE.COM\nRegistrar: Registrar LLC",
+          serverQueried: "whois.registrar.test",
+        };
+      },
+    );
+
+    const res = await lookupDomain("example.com", {
+      timeoutMs: 200,
+      whoisOnly: true,
+      followWhoisReferral: true,
+      includeRaw: true,
+    });
+    expect(res.ok, res.error).toBe(true);
+    expect(res.record?.source).toBe("whois");
+    expect(Boolean(res.record?.rawWhois)).toBe(true);
+  });
+});
+
+// 3) Multi-label public suffix fallback via exceptions (e.g., uk.com)
+describe("WHOIS multi-label public suffix fallback", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(discovery.ianaWhoisServerForTld).mockResolvedValue(
+      "whois.centralnic.tld",
+    );
+    vi.mocked(domain.getDomainParts).mockReturnValue({
+      publicSuffix: "uk.com",
+      tld: "com",
+    });
+  });
+
+  it("tries exception server for multi-label public suffix when TLD says no match", async () => {
+    const whois = vi.mocked(whoisClient.whoisQuery);
+    whois.mockReset();
+    whois
+      .mockImplementationOnce(
+        async (): Promise<WhoisQueryResult> => ({
+          text: "No match for domain",
+          serverQueried: "whois.centralnic.tld",
+        }),
+      )
+      .mockImplementationOnce(
+        async (): Promise<WhoisQueryResult> => ({
+          text: "Domain Name: EXAMPLE.UK.COM\nRegistrar: Registrar LLC",
+          serverQueried: "whois.centralnic.com",
+        }),
+      );
+
+    const res = await lookupDomain("example.uk.com", {
+      timeoutMs: 200,
+      whoisOnly: true,
+    });
+    expect(res.ok, res.error).toBe(true);
+    expect(res.record?.source).toBe("whois");
+    expect(res.record?.tld).toBe("com");
+    expect(res.record?.whoisServer).toBe("whois.centralnic.com");
+  });
+});

src/lib/__tests__/domain.test.ts

@@ -1,13 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import { extractTld, isLikelyDomain } from "../domain.js";
-
-test("extractTld basic", () => {
-  assert.equal(extractTld("example.com"), "com");
-  assert.equal(extractTld("sub.example.co.uk"), "uk");
-});
-
-test("isLikelyDomain", () => {
-  assert.equal(isLikelyDomain("example.com"), true);
-  assert.equal(isLikelyDomain("not a domain"), false);
-});

src/lib/dates.test.ts

@@ -1,22 +1,21 @@
 /** biome-ignore-all lint/style/noNonNullAssertion: this is fine for tests */
 
-import assert from "node:assert/strict";
-import test from "node:test";
-import { toISO } from "../dates.js";
+import { expect, test } from "vitest";
+import { toISO } from "./dates.js";
 
 test("toISO parses ISO and common whois formats", () => {
   const iso = toISO("2023-01-02T03:04:05Z");
-  assert.equal(iso, "2023-01-02T03:04:05Z");
+  expect(iso).toBe("2023-01-02T03:04:05Z");
 
   const noZ = toISO("2023-01-02 03:04:05");
-  assert.match(noZ!, /^2023-01-02T03:04:05Z$/);
+  expect(noZ!).toMatch(/^2023-01-02T03:04:05Z$/);
 
   const slash = toISO("2023/01/02 03:04:05");
-  assert.match(slash!, /^2023-01-02T03:04:05Z$/);
+  expect(slash!).toMatch(/^2023-01-02T03:04:05Z$/);
 
   const dmy = toISO("02-Jan-2023");
-  assert.equal(dmy, "2023-01-02T00:00:00Z");
+  expect(dmy).toBe("2023-01-02T00:00:00Z");
 
   const mdy = toISO("Jan 02 2023");
-  assert.equal(mdy, "2023-01-02T00:00:00Z");
+  expect(mdy).toBe("2023-01-02T00:00:00Z");
 });

src/lib/domain.test.ts

@@ -0,0 +1,12 @@
+import { expect, test } from "vitest";
+import { extractTld, isLikelyDomain } from "./domain.js";
+
+test("extractTld basic", () => {
+  expect(extractTld("example.com")).toBe("com");
+  expect(extractTld("sub.example.co.uk")).toBe("uk");
+});
+
+test("isLikelyDomain", () => {
+  expect(isLikelyDomain("example.com")).toBe(true);
+  expect(isLikelyDomain("not a domain")).toBe(false);
+});

src/rdap/normalize.test.ts

@@ -1,6 +1,5 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import { normalizeRdap } from "../normalize.js";
+import { expect, test } from "vitest";
+import { normalizeRdap } from "./normalize.js";
 
 test("normalizeRdap maps registrar, contacts, nameservers, events, dnssec", () => {
   const rdap = {
@@ -67,17 +66,17 @@ test("normalizeRdap maps registrar, contacts, nameservers, events, dnssec", () =
     ["https://rdap.example/"],
     "2025-01-01T00:00:00Z",
   );
-  assert.equal(rec.domain, "example.com");
-  assert.equal(rec.tld, "com");
-  assert.equal(rec.registrar?.name, "Registrar LLC");
-  assert.equal(rec.registrar?.ianaId, "9999");
-  assert.ok(rec.contacts && rec.contacts.length >= 3);
-  assert.ok(rec.nameservers && rec.nameservers.length === 2);
-  assert.equal(rec.nameservers?.[0].host, "ns1.example.com");
-  assert.ok(rec.dnssec?.enabled);
-  assert.equal(rec.creationDate, "2020-01-02T03:04:05Z");
-  assert.equal(rec.expirationDate, "2030-01-02T03:04:05Z");
-  assert.equal(rec.transferLock, true);
-  assert.equal(rec.whoisServer, "whois.example-registrar.test");
-  assert.equal(rec.source, "rdap");
+  expect(rec.domain).toBe("example.com");
+  expect(rec.tld).toBe("com");
+  expect(rec.registrar?.name).toBe("Registrar LLC");
+  expect(rec.registrar?.ianaId).toBe("9999");
+  expect(rec.contacts && rec.contacts.length >= 3).toBe(true);
+  expect(rec.nameservers && rec.nameservers.length === 2).toBe(true);
+  expect(rec.nameservers?.[0].host).toBe("ns1.example.com");
+  expect(rec.dnssec?.enabled).toBeTruthy();
+  expect(rec.creationDate).toBe("2020-01-02T03:04:05Z");
+  expect(rec.expirationDate).toBe("2030-01-02T03:04:05Z");
+  expect(rec.transferLock).toBe(true);
+  expect(rec.whoisServer).toBe("whois.example-registrar.test");
+  expect(rec.source).toBe("rdap");
 });

src/whois/normalize.test.ts

@@ -1,6 +1,5 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import { normalizeWhois } from "../normalize.js";
+import { expect, test } from "vitest";
+import { normalizeWhois } from "./normalize.js";
 
 test("WHOIS .de (DENIC-like) nserver lines", () => {
   const text = `
@@ -17,8 +16,8 @@ Changed: 2020-01-02
     "whois.denic.de",
     "2025-01-01T00:00:00Z",
   );
-  assert.ok(rec.nameservers && rec.nameservers.length === 2);
-  assert.equal(rec.nameservers?.[0].host, "ns1.example.net");
+  expect(rec.nameservers && rec.nameservers.length === 2).toBe(true);
+  expect(rec.nameservers?.[0].host).toBe("ns1.example.net");
 });
 
 test("WHOIS .uk Nominet style", () => {
@@ -44,9 +43,9 @@ Name servers:
     "whois.nic.uk",
     "2025-01-01T00:00:00Z",
   );
-  assert.ok(rec.nameservers && rec.nameservers.length === 2);
-  assert.ok(rec.creationDate);
-  assert.ok(rec.expirationDate);
+  expect(rec.nameservers && rec.nameservers.length === 2).toBe(true);
+  expect(Boolean(rec.creationDate)).toBe(true);
+  expect(Boolean(rec.expirationDate)).toBe(true);
 });
 
 test("WHOIS .jp JPRS style privacy redacted", () => {
@@ -66,9 +65,9 @@ test("WHOIS .jp JPRS style privacy redacted", () => {
     "whois.jprs.jp",
     "2025-01-01T00:00:00Z",
   );
-  assert.ok(rec.creationDate);
-  assert.ok(rec.expirationDate);
-  assert.ok(rec.statuses);
+  expect(Boolean(rec.creationDate)).toBe(true);
+  expect(Boolean(rec.expirationDate)).toBe(true);
+  expect(Boolean(rec.statuses)).toBe(true);
 });
 
 test("WHOIS .io NIC.IO style", () => {
@@ -92,9 +91,9 @@ DNSSEC: unsigned
     "whois.nic.io",
     "2025-01-01T00:00:00Z",
   );
-  assert.ok(rec.creationDate);
-  assert.ok(rec.expirationDate);
-  assert.ok(rec.nameservers && rec.nameservers.length === 2);
+  expect(Boolean(rec.creationDate)).toBe(true);
+  expect(Boolean(rec.expirationDate)).toBe(true);
+  expect(rec.nameservers && rec.nameservers.length === 2).toBe(true);
 });
 
 test("Privacy redacted WHOIS normalizes without contacts", () => {
@@ -123,7 +122,7 @@ Domain Status: clientTransferProhibited https://icann.org/epp#clientTransferProh
     "whois.verisign-grs.com",
     "2025-01-01T00:00:00Z",
   );
-  assert.ok(rec.creationDate);
-  assert.ok(rec.expirationDate);
-  assert.equal(rec.source, "whois");
+  expect(Boolean(rec.creationDate)).toBe(true);
+  expect(Boolean(rec.expirationDate)).toBe(true);
+  expect(rec.source).toBe("whois");
 });

vitest.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+    exclude: ["dist/**", "node_modules/**"],
+    sequence: { hooks: "list" },
+    globals: false,
+    testTimeout: process.env.SMOKE === "1" ? 30000 : 5000,
+    coverage: {
+      provider: "v8",
+      reportsDirectory: "coverage",
+      reporter: ["text", "lcov"],
+    },
+  },
+});