neon-testing 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 - present Mikael Lirbank and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+# Neon testing
+
+A Vitest utility for running database tests with isolated [Neon](https://neon.com/) branches. Each test file gets its own dedicated PostgreSQL database (Neon branch), ensuring clean, parallel, and reproducible tests.
+
+## Features
+
+- 🔄 **Isolated test environments** - Each test file runs against its own Neon branch
+- 🧹 **Automatic cleanup** - Neon test branches are created and destroyed automatically
+- 🛡️ **TypeScript native** - No JavaScript support
+- 🎯 **ESM only** - No CommonJS support
+
+## How it works
+
+1. **Branch creation**: Before tests run, a new Neon branch is created with a unique name
+1. **Environment setup**: `DATABASE_URL` is set to point to your test branch
+1. **Test execution**: Your tests run against the isolated database
+1. **Cleanup**: After tests complete, the branch is automatically deleted
+
+## Quick start
+
+### Prerequisites
+
+- A [Neon project](https://console.neon.tech/app/projects) with a database
+- A [Neon API key](https://neon.tech/docs/manage/api-keys) for programmatic access
+
+### Install
+
+```bash
+bun add -d neon-testing
+```
+
+### Minimal example
+
+```typescript
+// database.test.ts
+import { expect, test } from "vitest";
+import { makeNeonTesting } from "neon-testing";
+import { Pool } from "@neondatabase/serverless";
+
+// Enable Neon test branch for this test file
+makeNeonTesting({ apiKey: "apiKey", projectId: "projectId" })();
+
+test("database operations", async () => {
+  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+  await pool.query(`CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT)`);
+  await pool.query(`INSERT INTO users (name) VALUES ('Ellen Ripley')`);
+
+  const users = await pool.query(`SELECT * FROM users`);
+  expect(users.rows).toStrictEqual([{ id: 1, name: "Ellen Ripley" }]);
+
+  await pool.end();
+});
+```
+
+### Recommended usage
+
+#### 1. Configuration
+
+Use the `makeNeonTesting` factory to generate a lifecycle function for your tests.
+
+```typescript
+// test-setup.ts
+import { makeNeonTesting } from "neon-testing";
+
+// Export a configured lifecycle function to use in test files
+export const withNeonTestBranch = makeNeonTesting({
+  apiKey: "apiKey",
+  projectId: "projectId",
+});
+```
+
+See all available options in [NeonTestingOptions](https://github.com/starmode-base/neon-testing/blob/main/index.ts#L30-L41).
+
+#### 2. Enable database testing
+
+Then call the exported test lifecycle function in the test files where you need database access.
+
+```typescript
+// database.test.ts
+import { expect, test } from "vitest";
+import { withNeonTestBranch } from "./test-setup";
+import { Pool } from "@neondatabase/serverless";
+
+// Enable Neon test branch for this test file
+withNeonTestBranch();
+
+test("database operations", async () => {
+  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+  await pool.query(`CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT)`);
+  await pool.query(`INSERT INTO users (name) VALUES ('Ellen Ripley')`);
+
+  const users = await pool.query(`SELECT * FROM users`);
+  expect(users.rows).toStrictEqual([{ id: 1, name: "Ellen Ripley" }]);
+
+  await pool.end();
+});
+```
+
+#### Override configuration
+
+Branch from a specific branch instead of main:
+
+```typescript
+import { withNeonTestBranch } from "./test-setup";
+
+withNeonTestBranch({ parentBranchId: "br-staging-123" });
+```
+
+Don't copy data when branching:
+
+```typescript
+import { withNeonTestBranch } from "./test-setup";
+
+withNeonTestBranch({ schemaOnly: true });
+```
+
+See all available options in [NeonTestingOptions](https://github.com/starmode-base/neon-testing/blob/main/index.ts#L30-L41).
+
+## Isolate individual tests
+
+Tests within a single test file share the same database instance (Neon branch), so while all test files are isolated, tests within a test file are not. If you prefer individual tests within a test file to be isolated, [simply clean up the database in a beforeEach lifecycle](examples/neon-serverless-http-isolated.test.ts).
+
+This works because Vitest runs test files in parallel, but tests within each test file run one at a time.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please open issues or pull requests on [GitHub](https://github.com/starmode-base/neon-testing/pulls).
+
+## Support
+
+For questions or support, open an issue on [GitHub](https://github.com/starmode-base/neon-testing/issues).
+
+## Commercial support
+
+Need professional help with database testing, AI integration, or modern web development?
+
+**[STΛR MODΞ](https://www.starmode.dev/)** - I run this AI development studio with data scientist and ML/AI expert Spencer Smith. We specialize in building AI-first applications, advanced AI workflows, and agentic networks. We help companies build reliable AI solutions.
+
+**[Mikael Lirbank](https://www.lirbank.com/)** - My individual consulting practice for web application development, test automation, code quality, and technical architecture.

package/index.ts

@@ -0,0 +1,152 @@
+/**
+ * https://neon.com/docs/reference/typescript-sdk
+ */
+import {
+  createApiClient,
+  EndpointType,
+  type ConnectionDetails,
+} from "@neondatabase/api-client";
+import { afterAll, beforeAll } from "vitest";
+
+/**
+ * Creates a PostgreSQL connection URI from connection parameters
+ *
+ * @param connectionParameters - The connection parameters object
+ * @param type - The type of connection to create (pooler or direct)
+ * @returns A PostgreSQL connection URI string
+ */
+function createConnectionUri(
+  connectionParameters: ConnectionDetails,
+  type: "pooler" | "direct"
+) {
+  const { role, password, host, pooler_host, database } =
+    connectionParameters.connection_parameters;
+
+  const hostname = type === "pooler" ? pooler_host : host;
+
+  return `postgresql://${role}:${password}@${hostname}/${database}?sslmode=require`;
+}
+
+export interface NeonTestingOptions {
+  /** The Neon API key, this is used to create and teardown test branches */
+  apiKey: string;
+  /** The Neon project ID to operate on */
+  projectId: string;
+  /** The parent branch ID for the new 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";
+}
+
+/** Options for overriding test database setup (excludes apiKey) */
+export type NeonTestingOverrides = Omit<Partial<NeonTestingOptions>, "apiKey">;
+
+/**
+ * Factory function that creates a Neon test database setup/teardown function
+ * for Vitest test suites.
+ *
+ * @param apiKey - The Neon API key
+ * @param projectId - The Neon project ID
+ * @param endpoint - The type of connection to create (pooler or direct)
+ * @param parentBranchId - The parent branch ID for the new branch
+ * @param schemaOnly - Whether to create a schema-only branch
+ * @returns A setup/teardown function for Vitest test suites
+ *
+ * Side effects:
+ * - Sets the `DATABASE_URL` environment variable to the connection URI for the
+ *   new branch
+ * - Deletes the test branch after the test suite runs
+ */
+export function makeNeonTesting(factoryOptions: NeonTestingOptions) {
+  const apiClient = createApiClient({ apiKey: factoryOptions.apiKey });
+
+  /**
+   * Delete all test branches
+   */
+  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
+        );
+      }
+    }
+  }
+
+  const testDbSetup = (
+    /** Override any factory options except apiKey */
+    overrides?: NeonTestingOverrides
+  ) => {
+    // Merge factory options with overrides
+    const options = { ...factoryOptions, ...overrides };
+
+    // Each test file gets its own branch ID and database client
+    let branchId: string | undefined;
+
+    /**
+     * Create a new test branch
+     *
+     * @returns The connection URI for the new branch
+     */
+    async function createBranch() {
+      const { data } = await apiClient.createProjectBranch(options.projectId, {
+        branch: {
+          name: `test/${crypto.randomUUID()}`,
+          parent_id: options.parentBranchId,
+          init_source: options.schemaOnly ? "schema-only" : undefined,
+        },
+        endpoints: [{ type: EndpointType.ReadWrite }],
+        annotation_value: {
+          "integration-test": "true",
+        },
+      });
+
+      branchId = data.branch.id;
+
+      const [connectionUri] = data.connection_uris ?? [];
+      if (!connectionUri) {
+        throw new Error("No connection URI found");
+      }
+
+      return createConnectionUri(connectionUri, options.endpoint ?? "pooler");
+    }
+
+    /**
+     * Delete the test branch
+     */
+    async function deleteBranch() {
+      if (!branchId) {
+        throw new Error("No branch to delete");
+      }
+
+      await apiClient.deleteProjectBranch(options.projectId, branchId);
+      branchId = undefined;
+    }
+
+    beforeAll(async () => {
+      process.env.DATABASE_URL = await createBranch();
+    });
+
+    afterAll(async () => {
+      await deleteBranch();
+      process.env.DATABASE_URL = undefined;
+
+      // await deleteAllTestBranches();
+    });
+  };
+
+  // Attach the utility
+  testDbSetup.deleteAllTestBranches = deleteAllTestBranches;
+
+  return testDbSetup;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "neon-testing",
+  "version": "1.0.0",
+  "description": "A Vitest utility for running database tests with isolated Neon branches",
+  "keywords": [
+    "neon",
+    "postgres",
+    "postgresql",
+    "testing",
+    "vitest"
+  ],
+  "author": "Mikael Lirbank",
+  "license": "MIT",
+  "repository": "https://github.com/starmode-base/neon-testing",
+  "homepage": "https://github.com/starmode-base/neon-testing",
+  "bugs": "https://github.com/starmode-base/neon-testing/issues",
+  "module": "index.ts",
+  "type": "module",
+  "scripts": {
+    "test": "vitest",
+    "format": "prettier --write .",
+    "release": "bun publish && git tag v$(bun -p \"require('./package.json').version\") && git push --tags"
+  },
+  "dependencies": {
+    "@neondatabase/api-client": "^2.0.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5",
+    "vitest": "^3"
+  },
+  "devDependencies": {
+    "@neondatabase/serverless": "^1.0.1",
+    "dotenv": "^16.5.0",
+    "pg": "^8.16.0",
+    "postgres": "^3.4.7",
+    "prettier": "^3.5.3"
+  },
+  "files": [
+    "index.ts",
+    "README.md",
+    "LICENSE"
+  ]
+}