neon-testing 2.7.0 → 3.0.0-beta.0

package/README.md

@@ -5,7 +5,9 @@
 [![GitHub release](https://img.shields.io/github/v/release/starmode-base/neon-testing)](https://github.com/starmode-base/neon-testing/releases)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
 
-A [Vitest](https://vitest.dev/) utility for seamless integration tests with [Neon Postgres](https://neon.com/). <!-- A [STΛR MODΞ](https://starmode.dev) open-source project. -->
+A testing utility for seamless integration tests with [Neon Postgres](https://neon.com/), for [Vitest](https://vitest.dev/) and [Bun Test](https://bun.com/docs/cli/test).
+
+<!-- A [STΛR MODΞ](https://starmode.dev) open-source project. -->
 
 Each test file runs against its own isolated PostgreSQL database (Neon branch), ensuring clean, parallel, and reproducible testing of code that interacts with a database. Because it uses a real, isolated clone of your production database, you can test code logic that depends on database features, such as transaction rollbacks, unique constraints, and more.
 
@@ -29,7 +31,7 @@ Each test file runs against its own isolated PostgreSQL database (Neon branch),
 - 🔄 **Isolated test environments** - Each test file runs against its own Postgres database with your actual schema and constraints
 - 🧹 **Automatic cleanup** - Neon test branches are created and destroyed automatically
 - 🐛 **Debug friendly** - Option to preserve test branches for debugging failed tests
-- 🛡️ **TypeScript native** - With JavaScript support
+- 🛡️ **TypeScript only** - Ships TypeScript source files
 - 🎯 **ESM only** - No CommonJS support
 
 ## How it works
@@ -41,7 +43,9 @@ Each test file runs against its own isolated PostgreSQL database (Neon branch),
 
 ### Test isolation
 
-Tests in the same file share a single database instance (Neon branch). This means test files are fully isolated from each other, but individual tests within a file are intentionally not isolated. This works because Vitest runs test files in [parallel](https://vitest.dev/guide/parallelism.html), while tests within each file run sequentially.
+Each test file runs against its own database instance (Neon branch), so test files are fully isolated from each other. Tests within a single file share that branch and run sequentially — individual tests within a file are intentionally not isolated.
+
+Vitest and Bun differ in how they execute files. Vitest runs each file in its own process, [in parallel](https://vitest.dev/guide/parallelism.html), while Bun runs every file in [a single shared process](https://bun.com/docs/test), one after another by default. File-level isolation is the same on both — each file gets its own branch — but Vitest creates those branches concurrently whereas Bun creates them one at a time.
 
 If you prefer individual tests to be isolated, you can [reset the database](examples/isolated.test.ts) in a `beforeEach` lifecycle hook.
 
@@ -59,7 +63,11 @@ Test branches are automatically deleted after your tests complete. As a safety n
 ### Install
 
 ```sh
+# Vitest
 bun add -d neon-testing vitest
+
+# Bun Test
+bun add -d neon-testing
 ```
 
 ### Minimal example
@@ -67,7 +75,7 @@ bun add -d neon-testing vitest
 ```ts
 // minimal.test.ts
 import { expect, test } from "vitest";
-import { makeNeonTesting } from "neon-testing";
+import { makeNeonTesting } from "neon-testing/vitest";
 import { Pool } from "@neondatabase/serverless";
 
 // Enable Neon test branch for this test file
@@ -75,6 +83,7 @@ makeNeonTesting({
   apiKey: process.env.NEON_API_KEY!,
   projectId: process.env.NEON_PROJECT_ID!,
   // Recommended for Neon WebSocket drivers to automatically close connections
+  // (Vitest only)
   autoCloseWebSockets: true,
 })();
 
@@ -93,21 +102,29 @@ Source: [`examples/minimal.test.ts`](examples/minimal.test.ts)
 
 ### Recommended usage
 
-#### 1. Plugin setup
+#### 1. Setup
 
-First, add the Vite plugin to clear any existing `DATABASE_URL` environment variable before tests run, ensuring tests use isolated test databases.
+Register `neon-testing/setup` so any existing `DATABASE_URL` is cleared before tests run. A test file that forgets to enable branching then fails loudly instead of silently writing to a real database.
 
 ```ts
 // vitest.config.ts
 import { defineConfig } from "vitest/config";
-import { neonTesting } from "neon-testing/vite";
 
 export default defineConfig({
-  plugins: [neonTesting()],
+  test: {
+    setupFiles: ["neon-testing/setup"],
+  },
 });
 ```
 
-This plugin is recommended but not required. Without it, tests might accidentally use your existing `DATABASE_URL` (from `.env` files or environment variables) instead of the isolated test databases that Neon Testing creates. This can happen if you forget to call `neonTesting()` in a test file where database writes happen.
+For Bun, add it to `bunfig.toml` instead:
+
+```toml
+[test]
+preload = ["neon-testing/setup"]
+```
+
+Recommended but not required. Without it, a test file that forgets to call `neonTesting()` could fall back to your real `DATABASE_URL` (from `.env` or the environment) instead of an isolated test branch.
 
 #### 2. Configuration
 
@@ -115,7 +132,7 @@ Use the `makeNeonTesting` factory to generate a lifecycle function for your test
 
 ```ts
 // neon-testing.ts
-import { makeNeonTesting } from "neon-testing";
+import { makeNeonTesting } from "neon-testing/vitest"; // or "neon-testing/bun"
 
 // Export a configured lifecycle function to use in test files
 export const neonTesting = makeNeonTesting({
@@ -139,6 +156,7 @@ import { Pool } from "@neondatabase/serverless";
 // Enable Neon test branch for this test file
 neonTesting({
   // Recommended for Neon WebSocket drivers to automatically close connections
+  // (Vitest only)
   autoCloseWebSockets: true,
 });
 
@@ -157,20 +175,28 @@ Source: [`examples/recommended.test.ts`](examples/recommended.test.ts)
 
 ## Drivers
 
-This library works with any database driver that supports Neon Postgres and Vitest. The examples below demonstrate connection management, transaction support, and test isolation patterns for some popular drivers.
+This library works with any database driver that supports Neon Postgres.
+
+### Closing connections
+
+Some drivers keep a connection open after a test finishes — [Neon's WebSocket driver](https://neon.com/docs/serverless/serverless-driver#use-the-driver-over-websockets) and [node-postgres](https://www.npmjs.com/package/pg). If the test branch is deleted while a connection is still open, the driver errors. Avoid it in one of three ways:
 
-**IMPORTANT:** For [Neon WebSocket drivers](https://neon.com/docs/serverless/serverless-driver), enable `autoCloseWebSockets` in your `makeNeonTesting()` or `neonTesting()` configuration. This automatically closes WebSocket connections when deleting test branches, preventing connection termination errors.
+- close the connection yourself (e.g. `await pool.end()`)
+- enable `autoCloseWebSockets` (WebSocket driver only, Vitest only)
+- keep the branch with `deleteBranch: false`
+
+[Neon's HTTP driver](https://neon.com/docs/serverless/serverless-driver#use-the-driver-over-http) and [Postgres.js](https://www.npmjs.com/package/postgres) close their own connections, so they need none of this.
 
 ### Examples
 
-- [Neon serverless WebSocket](examples/drivers/ws-neon.test.ts)
-- [Neon serverless WebSocket + Drizzle](examples/drivers/ws-neon-drizzle.test.ts)
-- [Neon serverless HTTP](examples/drivers/http-neon.test.ts)
-- [Neon serverless HTTP + Drizzle](examples/drivers/http-neon-drizzle.test.ts)
-- [node-postgres](examples/drivers/tcp-pg.test.ts)
-- [node-postgres + Drizzle](examples/drivers/tcp-pg-drizzle.test.ts)
-- [Postgres.js](examples/drivers/tcp-postgres.test.ts)
-- [Postgres.js + Drizzle](examples/drivers/tcp-postgres-drizzle.test.ts)
+- [Neon serverless WebSocket](tests-vitest/drivers/ws-neon.test.ts)
+- [Neon serverless WebSocket + Drizzle](tests-vitest/drivers/ws-neon-drizzle.test.ts)
+- [Neon serverless HTTP](tests-vitest/drivers/http-neon.test.ts)
+- [Neon serverless HTTP + Drizzle](tests-vitest/drivers/http-neon-drizzle.test.ts)
+- [node-postgres](tests-vitest/drivers/tcp-pg.test.ts)
+- [node-postgres + Drizzle](tests-vitest/drivers/tcp-pg-drizzle.test.ts)
+- [Postgres.js](tests-vitest/drivers/tcp-postgres.test.ts)
+- [Postgres.js + Drizzle](tests-vitest/drivers/tcp-postgres-drizzle.test.ts)
 
 ## Configuration
 
@@ -179,10 +205,10 @@ You configure Neon Testing in two places:
 - **Base settings** in `makeNeonTesting()`
 - **Optional overrides** when calling the returned function (e.g., `neonTesting()`)
 
-Configure these in `makeNeonTesting()` and optionally override per test file when calling the returned function.
+Configure these in `makeNeonTesting()`; every option except `apiKey` can also be overridden per test file when calling the returned function.
 
 ```ts
-export interface NeonTestingOptions {
+export interface MakeNeonTestingOptions {
   /**
    * The Neon API key, this is used to create and teardown test branches (required)
    *
@@ -224,6 +250,8 @@ export interface NeonTestingOptions {
    * Suppresses the specific Neon WebSocket "Connection terminated unexpectedly"
    * error that may surface when deleting a branch with open WebSocket
    * connections
+   *
+   * Vitest only.
    */
   autoCloseWebSockets?: boolean;
   /**
@@ -273,7 +301,7 @@ Configure the base settings in `makeNeonTesting()`:
 
 ```ts
 // neon-testing.ts
-import { makeNeonTesting } from "neon-testing";
+import { makeNeonTesting } from "neon-testing/vitest";
 
 export const neonTesting = makeNeonTesting({
   apiKey: process.env.NEON_API_KEY!,
@@ -373,7 +401,9 @@ It's easy to run Neon integration tests in CI/CD pipelines:
 
 ## API Reference
 
-### Main exports (`neon-testing`)
+### Runner entry (`neon-testing/vitest` or `neon-testing/bun`)
+
+Both entries export the same `makeNeonTesting`; they differ only in which runner's `beforeAll`/`afterAll` hooks they wire up. (For other runners, `neon-testing/core` takes the hooks directly.)
 
 #### makeNeonTesting(options)
 
@@ -381,7 +411,7 @@ The factory function that creates a configured lifecycle function for your tests
 
 ```ts
 // neon-testing.ts
-import { makeNeonTesting } from "neon-testing";
+import { makeNeonTesting } from "neon-testing/vitest";
 
 export const neonTesting = makeNeonTesting({
   apiKey: process.env.NEON_API_KEY!,
@@ -434,24 +464,11 @@ test("access branch information", () => {
 
 See the [Neon Branch API documentation](https://api-docs.neon.tech/reference/getprojectbranch) for all available properties.
 
-### Vite plugin (`neon-testing/vite`)
-
-The Vite plugin clears any existing `DATABASE_URL` environment variable before tests run, ensuring tests use isolated test databases.
-
-```ts
-import { defineConfig } from "vitest/config";
-import { neonTesting } from "neon-testing/vite";
-
-export default defineConfig({
-  plugins: [neonTesting()],
-});
-```
-
-**Options:**
+### Setup (`neon-testing/setup`)
 
-- `debug` (boolean, default: `false`) - Enable debug logging
+A zero-config preload that clears `DATABASE_URL` before tests run, so a file that forgets to call `neonTesting()` can't reach a real database. Register it with your runner — Vitest `setupFiles` or Bun `bunfig` `preload` (see [Recommended usage](#recommended-usage)).
 
-This plugin is recommended but not required. Without it, tests might accidentally use your existing `DATABASE_URL` instead of isolated test databases.
+Set `NEON_TESTING_DEBUG=true` to log when it clears a value.
 
 ### Utilities (`neon-testing/utils`)
 

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "neon-testing",
-  "version": "2.7.0",
-  "description": "A Vitest utility for seamless integration tests with Neon Postgres",
+  "version": "3.0.0-beta.0",
+  "description": "A testing utility for seamless integration tests with Neon Postgres, for Vitest and Bun Test.",
   "keywords": [
     "neon",
     "postgres",
     "postgresql",
-    "vitest"
+    "vitest",
+    "bun",
+    "testing"
   ],
   "author": "Mikael Lirbank",
   "license": "MIT",
@@ -15,60 +17,68 @@
   "bugs": "https://github.com/starmode-base/neon-testing/issues",
   "type": "module",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./utils": {
-      "types": "./dist/utils.d.ts",
-      "import": "./dist/utils.js"
-    },
-    "./vite": {
-      "types": "./dist/vite-plugin.d.ts",
-      "import": "./dist/vite-plugin.js"
-    }
+    "./core": "./src/core.ts",
+    "./vitest": "./src/vitest.ts",
+    "./bun": "./src/bun.ts",
+    "./utils": "./src/utils.ts",
+    "./setup": "./src/setup.ts"
   },
   "files": [
-    "dist"
+    "src",
+    "!src/**/*.test.ts"
   ],
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
-    "dev": "tsc -p tsconfig.build.json --watch",
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && tsc && prettier --check . && vitest run",
+    "dev": "tsc --watch",
+    "check": "prettier --check . && tsc && bun run check:drift && bun run test",
+    "check:drift": "diff -r -x neon-testing.ts tests-bun tests-vitest",
     "format": "prettier --write .",
-    "test": "vitest",
+    "test": "vitest run && bun test",
+    "test:unit": "vitest run src",
+    "test:unit:watch": "vitest src",
+    "test:examples": "vitest run examples",
+    "test:examples:watch": "vitest examples",
+    "test:vitest": "vitest run tests-vitest",
+    "test:vitest:watch": "vitest tests-vitest",
+    "test:bun": "bun test",
+    "test:bun:watch": "bun test --watch",
     "skills:update": "bunx skills add neondatabase/agent-skills",
-    "clean:soft": "rm -rf node_modules dist && bun install",
-    "clean:hard": "rm -rf node_modules dist bun.lock && bun install",
-    "release:patch": "bun pm version patch",
-    "release:minor": "bun pm version minor",
-    "release:major": "bun pm version major",
-    "release:beta": "bun pm version prerelease --preid=beta",
-    "release:beta:patch": "bun pm version prepatch --preid=beta",
-    "release:beta:minor": "bun pm version preminor --preid=beta",
-    "release:beta:major": "bun pm version premajor --preid=beta",
+    "clean:soft": "rm -rf node_modules && bun install",
+    "clean:hard": "rm -rf node_modules bun.lock && bun install",
+    "release:patch": "bun pm version patch --message 'release: v%s'",
+    "release:minor": "bun pm version minor --message 'release: v%s'",
+    "release:major": "bun pm version major --message 'release: v%s'",
+    "release:beta": "bun pm version prerelease --preid=beta --message 'release: v%s'",
+    "release:beta:patch": "bun pm version prepatch --preid=beta --message 'release: v%s'",
+    "release:beta:minor": "bun pm version preminor --preid=beta --message 'release: v%s'",
+    "release:beta:major": "bun pm version premajor --preid=beta --message 'release: v%s'",
+    "preversion": "test \"$(git branch --show-current)\" = main && git pull --ff-only",
     "postversion": "git push --follow-tags"
   },
   "dependencies": {
-    "@neondatabase/api-client": "^2.7.1"
+    "@neondatabase/api-client": "2.7.1"
   },
   "peerDependencies": {
-    "vite": "^7",
     "vitest": "^3 || ^4"
   },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "@neondatabase/serverless": "^1.0.2",
+    "@neondatabase/serverless": "^1.1.0",
+    "@types/bun": "^1.3.14",
     "@types/pg": "^8.20.0",
     "dotenv": "^17.4.2",
     "drizzle-orm": "^0.45.2",
-    "pg": "^8.20.0",
+    "pg": "^8.21.0",
     "postgres": "^3.4.9",
-    "prettier": "^3.8.2",
+    "prettier": "^3.8.4",
     "tiny-invariant": "^1.3.3",
-    "typescript": "^5.9.3",
-    "vite": "^7.3.2",
-    "vitest": "^4.1.4"
-  },
-  "browser": {
-    "./dist/vite-plugin.js": "./dist/browser-empty.js"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
   }
 }

package/src/bun.ts

@@ -0,0 +1,13 @@
+/// <reference types="bun" />
+import { beforeAll, afterAll } from "bun:test";
+import { makeNeonTestingCore } from "./core";
+import type { MakeNeonTestingOptions } from "./core";
+
+export type { MakeNeonTestingOptions, NeonTestingOptions } from "./core";
+
+/**
+ * Create a Neon test-branch factory wired to Bun's lifecycle hooks.
+ */
+export function makeNeonTesting(options: MakeNeonTestingOptions) {
+  return makeNeonTestingCore({ ...options, hooks: { beforeAll, afterAll } });
+}