neon-testing 2.7.0 → 3.0.0-beta.0

package/src/core.ts

@@ -0,0 +1,372 @@
+/**
+ * https://neon.com/docs/reference/typescript-sdk
+ */
+import {
+  createApiClient,
+  EndpointType,
+  type Branch,
+} from "@neondatabase/api-client";
+import { applySslMode } from "./lib/ssl";
+import { validateExpiresIn } from "./lib/expires-in";
+import { neonWsErrorHandler } from "./lib/ws-error";
+import { withRetry } from "./lib/with-retry";
+
+/**
+ * Test-runner lifecycle hooks
+ *
+ * Injected so the core stays runner-agnostic. Most users don't build these by
+ * hand — import the pre-wired factory from `neon-testing/vitest` or
+ * `neon-testing/bun`, which supply them automatically.
+ */
+export interface NeonTestingHooks {
+  beforeAll: (fn: () => void | Promise<void>) => void;
+  afterAll: (fn: () => void | Promise<void>) => void;
+}
+
+/**
+ * Configuration for the Neon test-branch factory.
+ *
+ * `hooks` are injected by the per-runner entry (`neon-testing/vitest` or
+ * `neon-testing/bun`); the remaining fields control how each test branch is
+ * created and torn down.
+ */
+export interface MakeNeonTestingCoreOptions {
+  /**
+   * Test-runner lifecycle hooks (supplied by `neon-testing/vitest` or
+   * `neon-testing/bun`)
+   */
+  hooks: NeonTestingHooks;
+  /**
+   * The Neon API key, this is used to create and teardown test branches (required)
+   *
+   * https://neon.com/docs/manage/api-keys#creating-api-keys
+   */
+  apiKey: string;
+  /**
+   * The Neon project ID to operate on (required)
+   *
+   * https://console.neon.tech/app/projects
+   */
+  projectId: string;
+  /**
+   * The parent branch ID for the new branch (default: undefined)
+   *
+   * If omitted or undefined, test branches will be created from the project's
+   * default branch.
+   */
+  parentBranchId?: string;
+  /**
+   * Whether to create a schema-only branch (default: false)
+   */
+  schemaOnly?: boolean;
+  /**
+   * The type of connection to create (default: "pooler")
+   */
+  endpoint?: "pooler" | "direct";
+  /**
+   * Delete the test branch in afterAll (default: true)
+   *
+   * Disabling this will leave each test branch in the Neon project after the
+   * test suite runs
+   */
+  deleteBranch?: boolean;
+  /**
+   * Automatically close Neon WebSocket connections opened during tests before
+   * deleting the branch (default: false)
+   *
+   * Suppresses the specific Neon WebSocket "Connection terminated unexpectedly"
+   * error that may surface when deleting a branch with open WebSocket
+   * connections
+   *
+   * Vitest only — under Bun the uncaughtException suppression does not
+   * intercept, so close connections explicitly there instead.
+   */
+  autoCloseWebSockets?: boolean;
+  /**
+   * Time in seconds until the branch expires and is automatically deleted
+   * (default: 600 = 10 minutes)
+   *
+   * This provides automatic cleanup for dangling branches from interrupted or
+   * failed test runs. Set to `null` to disable automatic expiration.
+   *
+   * Must be a positive integer. Maximum 30 days (2,592,000 seconds).
+   *
+   * https://neon.com/docs/guides/branch-expiration
+   */
+  expiresIn?: number | null;
+  /**
+   * The database role to connect as (default: project owner role)
+   *
+   * The role must exist in the parent branch. Roles are automatically
+   * copied to test branches when branching.
+   */
+  roleName?: string;
+  /**
+   * The database to connect to (default: project default database)
+   */
+  databaseName?: string;
+  /**
+   * Override the `sslmode` query param on the connection URI (default:
+   * undefined — URI is passed through unchanged)
+   *
+   * Neon's API returns URIs with `sslmode=require`. In pg v9 the meaning of
+   * `require` changes to libpq semantics (encrypt, but don't verify the CA).
+   *
+   * - `"verify-full"` — strict CA verification (silences the pg v9 warning)
+   * - `"require"` — preserves today's effective behavior under pg v9 by also
+   *   setting `uselibpqcompat=true`
+   *
+   * Only affects drivers that parse `sslmode` (e.g. `pg`). The Neon
+   * serverless driver ignores it.
+   */
+  sslMode?: "verify-full" | "require";
+}
+
+/** Options for the `makeNeonTesting` factories — core options minus the injected hooks */
+export type MakeNeonTestingOptions = Omit<MakeNeonTestingCoreOptions, "hooks">;
+
+/** Per-file overrides accepted by the returned `neonTesting()` function */
+export type NeonTestingOptions = Partial<
+  Omit<MakeNeonTestingOptions, "apiKey">
+>;
+
+/**
+ * Low-level factory that creates a Neon test-branch setup/teardown function.
+ * Runner-agnostic — you inject the lifecycle hooks via `options.hooks`.
+ *
+ * Most users want a pre-wired entry instead: `neon-testing/vitest` or
+ * `neon-testing/bun`. Reach for this core factory only for other runners
+ * (jest, node:test, …).
+ *
+ * @param factoryOptions - see {@link MakeNeonTestingCoreOptions}
+ * @returns A setup/teardown function with attached utilities:
+ *  - `deleteAllTestBranches()` - delete all test branches
+ *  - `api` - the Neon API client
+ *
+ * @example
+ * ```ts
+ * import { beforeAll, afterAll } from "vitest"; // or any runner
+ * import { makeNeonTestingCore } from "neon-testing/core";
+ *
+ * export const neonTesting = makeNeonTestingCore({
+ *   apiKey: process.env.NEON_API_KEY!,
+ *   projectId: process.env.NEON_PROJECT_ID!,
+ *   hooks: { beforeAll, afterAll },
+ * });
+ * ```
+ */
+export function makeNeonTestingCore(
+  factoryOptions: MakeNeonTestingCoreOptions,
+) {
+  // Validate factory options
+  validateExpiresIn(factoryOptions.expiresIn);
+
+  const apiClient = createApiClient({ apiKey: factoryOptions.apiKey });
+
+  /**
+   * Delete all test branches (branches with the "integration-test: true" annotation)
+   */
+  async function deleteAllTestBranches() {
+    const { data } = await apiClient.listProjectBranches({
+      projectId: factoryOptions.projectId,
+    });
+
+    for (const branch of data.branches) {
+      const isTestBranch =
+        data.annotations[branch.id]?.value["integration-test"] === "true";
+
+      if (isTestBranch) {
+        await apiClient.deleteProjectBranch(
+          factoryOptions.projectId,
+          branch.id,
+        );
+      }
+    }
+  }
+
+  /**
+   * Setup/teardown function for a test file.
+   *
+   * Registers lifecycle hooks (via the injected `hooks`) that:
+   * - Create an isolated test branch from your parent branch
+   * - Set `DATABASE_URL` environment variable to the test branch connection URI
+   * - Automatically delete the test branch after tests complete (unless `deleteBranch: false`)
+   * - Automatically expire branches after 10 minutes for cleanup (unless `expiresIn: null`)
+   *
+   * @param overrides - Optional per-file overrides for the factory options
+   * @returns A function that provides access to the current Neon branch object
+   */
+  const neonTesting = (
+    /** Override any factory options except apiKey */
+    overrides?: NeonTestingOptions,
+  ) => {
+    // Validate overrides
+    if (overrides?.expiresIn !== undefined) {
+      validateExpiresIn(overrides.expiresIn);
+    }
+
+    // Merge factory options with overrides
+    const options = { ...factoryOptions, ...overrides };
+
+    // Each test file gets its own branch and database client
+    let branch: Branch | undefined;
+
+    // List of tracked Neon WebSocket connections
+    // Lazily initialized when autoCloseWebSockets is enabled (avoids
+    // referencing the WebSocket global on runtimes that lack it, e.g. Node 20)
+    let neonSockets: Set<WebSocket> | undefined;
+
+    /**
+     * Create a new test branch
+     *
+     * @returns The connection URI for the new branch
+     */
+    async function createBranch() {
+      // Calculate expiration timestamp if expiresIn is set
+      const expiresIn =
+        options.expiresIn === undefined ? 600 : options.expiresIn; // Default: 10 minutes
+
+      const expiresAt =
+        expiresIn !== null
+          ? new Date(Date.now() + expiresIn * 1000).toISOString()
+          : undefined;
+
+      const { data } = await apiClient.createProjectBranch(options.projectId, {
+        branch: {
+          name: `test/${crypto.randomUUID()}`,
+          ...(options.parentBranchId
+            ? { parent_id: options.parentBranchId }
+            : {}),
+          ...(options.schemaOnly ? { init_source: "schema-only" } : {}),
+          ...(expiresAt ? { expires_at: expiresAt } : {}),
+        },
+        endpoints: [{ type: EndpointType.ReadWrite }],
+        annotation_value: {
+          "integration-test": "true",
+        },
+      });
+
+      branch = data.branch;
+
+      // Determine role and database (handles multi-role/database projects)
+      const targetRole =
+        options.roleName ??
+        data.roles?.find((r) => r.name === "neondb_owner")?.name ??
+        data.roles?.[0]?.name;
+      const targetDatabase =
+        options.databaseName ??
+        data.databases?.find((d) => d.name === "neondb")?.name ??
+        data.databases?.[0]?.name;
+
+      if (!targetRole) {
+        throw new Error("No role available in branch");
+      }
+      if (!targetDatabase) {
+        throw new Error("No database available in branch");
+      }
+
+      // Validate specified role exists
+      if (
+        options.roleName &&
+        !data.roles?.some((r) => r.name === options.roleName)
+      ) {
+        throw new Error(`Role not found: ${options.roleName}`);
+      }
+
+      // Validate specified database exists
+      if (
+        options.databaseName &&
+        !data.databases?.some((d) => d.name === options.databaseName)
+      ) {
+        throw new Error(`Database not found: ${options.databaseName}`);
+      }
+
+      // Use getConnectionUri API (works for all cases, including multi-role projects)
+      const { data: uriData } = await apiClient.getConnectionUri({
+        projectId: options.projectId,
+        branch_id: branch.id,
+        role_name: targetRole,
+        database_name: targetDatabase,
+        pooled: options.endpoint !== "direct",
+      });
+
+      return applySslMode(uriData.uri, options.sslMode);
+    }
+
+    /**
+     * Delete the test branch
+     */
+    async function deleteBranch() {
+      if (!branch?.id) {
+        throw new Error("No branch to delete");
+      }
+
+      await apiClient.deleteProjectBranch(options.projectId, branch.id);
+      branch = undefined;
+    }
+
+    factoryOptions.hooks.beforeAll(async () => {
+      process.env.DATABASE_URL = await withRetry(createBranch, {
+        maxRetries: 8,
+        baseDelayMs: 1000,
+      });
+
+      if (options.autoCloseWebSockets) {
+        neonSockets = new Set<WebSocket>();
+
+        // Custom WebSocket constructor that tracks Neon WebSocket connections
+        class TrackingWebSocket extends WebSocket {
+          constructor(url: string) {
+            super(url);
+
+            // Only track Neon WebSocket connections
+            if (!url.includes(".neon.tech/")) return;
+
+            neonSockets!.add(this);
+          }
+        }
+
+        // Install a custom WebSocket constructor that tracks Neon WebSocket
+        // connections and closes them before deleting the branch
+        try {
+          const { neonConfig } = await import("@neondatabase/serverless");
+          neonConfig.webSocketConstructor = TrackingWebSocket;
+        } catch {
+          throw new Error(
+            "autoCloseWebSockets requires @neondatabase/serverless to be installed. Run: npm install @neondatabase/serverless",
+          );
+        }
+      }
+    });
+
+    factoryOptions.hooks.afterAll(async () => {
+      delete process.env.DATABASE_URL;
+
+      // Close all tracked Neon WebSocket connections before deleting the branch
+      if (options.autoCloseWebSockets && neonSockets) {
+        // Suppress Neon WebSocket "Connection terminated unexpectedly" error
+        process.prependListener("uncaughtException", neonWsErrorHandler);
+
+        // Close tracked Neon WebSocket connections before deleting the branch
+        neonSockets.forEach((ws) => ws.close());
+      }
+
+      if (options.deleteBranch !== false) {
+        await deleteBranch();
+      }
+    });
+
+    /**
+     * Return the Neon branch object
+     *
+     * @returns The Neon branch object
+     */
+    return () => branch;
+  };
+
+  // Attach utilities
+  neonTesting.deleteAllTestBranches = deleteAllTestBranches;
+  neonTesting.api = apiClient;
+
+  return neonTesting;
+}

package/src/lib/barrier.ts

@@ -0,0 +1,22 @@
+/**
+ * Creates a synchronization barrier that blocks until `count` callers have
+ * arrived, then releases all of them simultaneously
+ */
+export function createBarrier(count: number) {
+  let arrived = 0;
+  let release: () => void;
+
+  const barrier = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+
+  return async () => {
+    arrived++;
+
+    if (arrived === count) {
+      release();
+    }
+
+    await barrier;
+  };
+}

package/src/lib/expires-in.ts

@@ -0,0 +1,24 @@
+/**
+ * Validates the expiresIn option
+ */
+export function validateExpiresIn(expiresIn: number | null | undefined) {
+  if (expiresIn === null) {
+    return;
+  }
+
+  if (expiresIn === undefined) {
+    return;
+  }
+
+  if (!Number.isInteger(expiresIn)) {
+    throw new Error("expiresIn must be an integer");
+  }
+
+  if (expiresIn <= 0) {
+    throw new Error("expiresIn must be a positive integer");
+  }
+
+  if (expiresIn > 2592000) {
+    throw new Error("expiresIn must not exceed 30 days (2,592,000 seconds)");
+  }
+}

package/src/lib/singleton.ts

@@ -0,0 +1,10 @@
+/**
+ * Create a lazy singleton from a factory function
+ */
+export function lazySingleton<T>(factory: () => T): () => T {
+  let instance: T | undefined;
+  return () => {
+    instance ??= factory();
+    return instance;
+  };
+}

package/src/lib/ssl.ts

@@ -0,0 +1,24 @@
+/**
+ * Rewrite the `sslmode` (and related) query params on a Neon connection URI.
+ *
+ * Neon's API returns URIs with `sslmode=require`. In pg v9 /
+ * pg-connection-string v3 this mode will adopt libpq semantics (encrypt
+ * without CA verification) instead of today's effective `verify-full`.
+ */
+export function applySslMode(
+  uri: string,
+  mode: "verify-full" | "require" | undefined,
+): string {
+  if (mode === undefined) return uri;
+
+  const url = new URL(uri);
+  url.searchParams.set("sslmode", mode);
+
+  if (mode === "require") {
+    url.searchParams.set("uselibpqcompat", "true");
+  } else {
+    url.searchParams.delete("uselibpqcompat");
+  }
+
+  return url.toString();
+}

package/src/lib/with-retry.ts

@@ -0,0 +1,55 @@
+/**
+ * Reusable API call wrapper with automatic retry on 423 errors with exponential
+ * backoff
+ *
+ * https://neon.com/docs/reference/typescript-sdk#error-handling
+ * https://neon.com/docs/changelog/2022-07-20
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: {
+    maxRetries: number;
+    baseDelayMs: number;
+  },
+): Promise<T> {
+  if (!Number.isInteger(options.maxRetries) || options.maxRetries <= 0) {
+    throw new Error("maxRetries must be a positive integer");
+  }
+
+  if (!Number.isInteger(options.baseDelayMs) || options.baseDelayMs <= 0) {
+    throw new Error("baseDelayMs must be a positive integer");
+  }
+
+  for (let attempt = 1; attempt <= options.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error: any) {
+      const status = error?.response?.status;
+
+      // Retry on 423 (resource locked) with exponential backoff
+      if (status === 423 && attempt < options.maxRetries) {
+        const delay = options.baseDelayMs * Math.pow(2, attempt - 1);
+
+        console.log(
+          `API call failed with 423, retrying in ${delay}ms (attempt ${attempt}/${options.maxRetries})`,
+        );
+        await new Promise((resolve) => setTimeout(resolve, delay));
+
+        continue;
+      }
+
+      // Surface Neon API error details that are otherwise buried in the Axios error
+      if (error?.response?.data?.code) {
+        const { code, message } = error.response.data;
+        throw new Error(
+          `Neon API error - HTTP ${status} - ${code} - ${message}`,
+          { cause: error },
+        );
+      }
+
+      // Non-API errors (network, timeouts, etc.) pass through as-is
+      throw error;
+    }
+  }
+  throw new Error("apiCallWithRetry reached unexpected end");
+}

package/src/lib/ws-error.ts

@@ -0,0 +1,17 @@
+/**
+ * Error handler: Suppress Neon WebSocket "Connection terminated unexpectedly"
+ * error
+ */
+export const neonWsErrorHandler = (error: Error) => {
+  const isNeonWsClose =
+    error.message.includes("Connection terminated unexpectedly") &&
+    error.stack?.includes("@neondatabase/serverless");
+
+  if (isNeonWsClose) {
+    // Swallow this specific Neon WS termination error
+    return;
+  }
+
+  // For any other error, detach and rethrow
+  throw error;
+};

package/src/setup.ts

@@ -0,0 +1,8 @@
+// Removes any existing DATABASE_URL so a test file that forgot to call
+// `neonTesting()` can't reach the pre-configured database. Loaded as a
+// test-runner preload (Vitest `setupFiles` / Bun `bunfig` `preload`).
+if (process.env.DATABASE_URL && process.env.NEON_TESTING_DEBUG === "true") {
+  console.debug("[neon-testing] Clearing existing DATABASE_URL");
+}
+
+delete process.env.DATABASE_URL;

package/src/utils.ts

@@ -0,0 +1,2 @@
+export { lazySingleton } from "./lib/singleton";
+export { createBarrier } from "./lib/barrier";

package/src/vitest.ts

@@ -0,0 +1,12 @@
+import { beforeAll, afterAll } from "vitest";
+import { makeNeonTestingCore } from "./core";
+import type { MakeNeonTestingOptions } from "./core";
+
+export type { MakeNeonTestingOptions, NeonTestingOptions } from "./core";
+
+/**
+ * Create a Neon test-branch factory wired to Vitest's lifecycle hooks.
+ */
+export function makeNeonTesting(options: MakeNeonTestingOptions) {
+  return makeNeonTestingCore({ ...options, hooks: { beforeAll, afterAll } });
+}

package/dist/barrier.d.ts

@@ -1,6 +0,0 @@
-/**
- * Creates a synchronization barrier that blocks until `count` callers have
- * arrived, then releases all of them simultaneously
- */
-export declare function createBarrier(count: number): () => Promise<void>;
-//# sourceMappingURL=barrier.d.ts.map

package/dist/barrier.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"barrier.d.ts","sourceRoot":"","sources":["../src/barrier.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,uBAiB1C"}

package/dist/barrier.js

@@ -1,19 +0,0 @@
-/**
- * Creates a synchronization barrier that blocks until `count` callers have
- * arrived, then releases all of them simultaneously
- */
-export function createBarrier(count) {
-    let arrived = 0;
-    let release;
-    const barrier = new Promise((resolve) => {
-        release = resolve;
-    });
-    return async () => {
-        arrived++;
-        if (arrived === count) {
-            release();
-        }
-        await barrier;
-    };
-}
-//# sourceMappingURL=barrier.js.map

package/dist/barrier.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"barrier.js","sourceRoot":"","sources":["../src/barrier.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,OAAmB,CAAC;IAExB,MAAM,OAAO,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC5C,OAAO,GAAG,OAAO,CAAC;IACpB,CAAC,CAAC,CAAC;IAEH,OAAO,KAAK,IAAI,EAAE;QAChB,OAAO,EAAE,CAAC;QAEV,IAAI,OAAO,KAAK,KAAK,EAAE,CAAC;YACtB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,OAAO,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Creates a synchronization barrier that blocks until `count` callers have\n * arrived, then releases all of them simultaneously\n */\nexport function createBarrier(count: number) {\n  let arrived = 0;\n  let release: () => void;\n\n  const barrier = new Promise<void>((resolve) => {\n    release = resolve;\n  });\n\n  return async () => {\n    arrived++;\n\n    if (arrived === count) {\n      release();\n    }\n\n    await barrier;\n  };\n}\n"]}

package/dist/browser-empty.d.ts

@@ -1,2 +0,0 @@
-export declare function neonTesting(): void;
-//# sourceMappingURL=browser-empty.d.ts.map

package/dist/browser-empty.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"browser-empty.d.ts","sourceRoot":"","sources":["../src/browser-empty.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,SAE1B"}

package/dist/browser-empty.js

@@ -1,4 +0,0 @@
-export function neonTesting() {
-    throw new Error("neon-testing/vite is Node-only (Vite/Vitest context).");
-}
-//# sourceMappingURL=browser-empty.js.map

package/dist/browser-empty.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"browser-empty.js","sourceRoot":"","sources":["../src/browser-empty.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,WAAW;IACzB,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;AAC3E,CAAC","sourcesContent":["export function neonTesting() {\n  throw new Error(\"neon-testing/vite is Node-only (Vite/Vitest context).\");\n}\n"]}