neon-testing 2.1.0 → 2.1.1

package/README.md

@@ -1,8 +1,10 @@
-# Neon testing
+# Neon Testing
 
 [![Integration tests](https://github.com/starmode-base/neon-testing/actions/workflows/test.yml/badge.svg)](https://github.com/starmode-base/neon-testing/actions/workflows/test.yml)
+[![npm version](https://img.shields.io/npm/v/neon-testing)](https://www.npmjs.com/package/neon-testing)
+[![GitHub release](https://img.shields.io/github/v/release/starmode-base/neon-testing)](https://github.com/starmode-base/neon-testing/releases)
 
-A [Vitest](https://vitest.dev/) utility for seamless integration tests with [Neon Postgres](https://neon.com/).
+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. -->
 
 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.
 
@@ -41,12 +43,12 @@ If you prefer individual tests to be isolated, you can [reset the database](exam
 ### Install
 
 ```sh
-bun add -d neon-testing
+bun add -d neon-testing vitest
 ```
 
 ### Minimal example
 
-```typescript
+```ts
 // minimal.test.ts
 import { expect, test } from "vitest";
 import { makeNeonTesting } from "neon-testing";
@@ -77,7 +79,7 @@ test("database operations", async () => {
 
 First, add the Vite plugin to clear any existing `DATABASE_URL` environment variable before tests run, ensuring tests use isolated test databases.
 
-```typescript
+```ts
 // vitest.config.ts or vite.config.ts
 import { defineConfig } from "vitest/config";
 import { neonTesting } from "neon-testing/utils";
@@ -87,13 +89,13 @@ export default defineConfig({
 });
 ```
 
-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 `withNeonTestBranch()` in a test file where database writes happen.
+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 `withNeonTestBranch()` in a test file where database writes happen.
 
 #### 2. Configuration
 
 Use the `makeNeonTesting` factory to generate a lifecycle function for your tests.
 
-```typescript
+```ts
 // test-setup.ts
 import { makeNeonTesting } from "neon-testing";
 
@@ -108,7 +110,7 @@ export const withNeonTestBranch = makeNeonTesting({
 
 Then call the exported test lifecycle function in the test files where you need database access.
 
-```typescript
+```ts
 // recommended.test.ts
 import { expect, test } from "vitest";
 import { withNeonTestBranch } from "./test-setup";
@@ -150,18 +152,66 @@ This library works with any database driver that supports Neon Postgres and Vite
 
 ## Configuration
 
-You configure neon-testing in two places:
+You configure Neon Testing in two places:
 
 - **Base settings** in `makeNeonTesting()`
 - **Optional overrides** in `withNeonTestBranch()`
 
-See all available options in [NeonTestingOptions](https://github.com/starmode-base/neon-testing/blob/main/index.ts#L33-L75).
+Configure these in `makeNeonTesting()` and optionally override per test file via `withNeonTestBranch()`.
+
+```ts
+export interface NeonTestingOptions {
+  /**
+   * The Neon API key, this is used to create and teardown test branches
+   *
+   * https://neon.com/docs/manage/api-keys#creating-api-keys
+   */
+  apiKey: string;
+  /**
+   * The Neon project ID to operate on
+   *
+   * https://console.neon.tech/app/projects
+   */
+  projectId: string;
+  /**
+   * The parent branch ID for the new branch. If omitted or empty, the branch
+   * 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 (pooler is recommended)
+   */
+  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
+   */
+  autoCloseWebSockets?: boolean;
+}
+```
+
+See all available options in [NeonTestingOptions](index.ts#L31-L73).
 
 ### Base configuration
 
 Configure the base settings in `makeNeonTesting()`:
 
-```typescript
+```ts
 import { makeNeonTesting } from "neon-testing";
 
 export const withNeonTestBranch = makeNeonTesting({
@@ -174,26 +224,20 @@ export const withNeonTestBranch = makeNeonTesting({
 
 Override the base configuration in specific test files with `withNeonTestBranch()`:
 
-```typescript
+```ts
 import { withNeonTestBranch } from "./test-setup";
 
 withNeonTestBranch({ parentBranchId: "br-staging-123" });
 ```
 
-## CI/CD
-
-It is easy to run Neon integration in CI/CD
-
-### GitHub Actions
+## Continuous integration
 
-[Example](.github/workflows/test.yml)
+It's easy to run Neon integration tests in CI/CD pipelines:
 
-### Vercel
-
-Two options:
-
-- Add `vitest run` to the `build` script in [package.json](https://github.com/starmode-base/template-tanstack-start/blob/83c784e164b55fd8d59c5b57b907251e5eb03de1/app/package.json#L11l)
-- Add `vitest run` to the _Build Command_ in the Vercel dashboard
+- **GitHub Actions** — see the [example workflow](.github/workflows/test.yml)
+- **Vercel** — either
+  - add `vitest run` to the `build` script in [package.json](https://github.com/starmode-base/template-tanstack-start/blob/83c784e164b55fd8d59c5b57b907251e5eb03de1/app/package.json#L11), or
+  - add `vitest run` to the _Build Command_ in the Vercel dashboard
 
 ## Utilities
 
@@ -201,20 +245,20 @@ Two options:
 
 The `deleteAllTestBranches()` function is a utility that deletes all test branches from your Neon project. This is useful for cleanup when tests fail unexpectedly and leave orphaned test branches.
 
-```typescript
+```ts
 import { withNeonTestBranch } from "./test-setup";
 
 // Access the cleanup utility
 await withNeonTestBranch.deleteAllTestBranches();
 ```
 
-The function identifies test branches by looking for the `integration-test: true` annotation that neon-testing automatically adds to all test branches it creates.
+The function identifies test branches by looking for the `integration-test: true` annotation that Neon Testing automatically adds to all test branches it creates.
 
 ### lazySingleton()
 
 The `lazySingleton()` function creates a lazy singleton from a factory function. This is useful for managing database connections efficiently:
 
-```typescript
+```ts
 import { lazySingleton } from "neon-testing/utils";
 import { neon } from "@neondatabase/serverless";
 
@@ -250,12 +294,8 @@ bun run release
 
 The command will abort if there are uncommitted changes in the working tree, or if the `version` in [package.json](package.json) has not been incremented.
 
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## Need help?
+## Author
 
-Hi, I’m [Mikael Lirbank](https://www.lirbank.com/). I help teams build reliable AI systems. I care about quality—AI evals, robust test suites, clean data models, and clean architecture. Sometimes I draw user interfaces.
+Hi, I'm [Mikael Lirbank](https://www.lirbank.com/). I build robust, reliable, high-quality AI systems. I care deeply about quality—AI evals, robust test suites, clean data models, and clean architecture.
 
-Want to ship faster without breaking things? Let’s talk.
+Need help building elegant systems? [I'm happy to help](https://www.lirbank.com/).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon-testing",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "A Vitest utility for seamless integration tests with Neon Postgres",
   "keywords": [
     "neon",