neon-testing

library2.7.0jsnpmunverified

Vitest utility for integration tests with Neon Postgres. Each test file runs against an isolated Neon branch, providing real database features like transactions and constraints. Version 2.7.0. ESM-only. No CommonJS support. Integrates with Neon WebSocket drivers for automatic connection cleanup. Supports optional branch preservation for debugging. Requires a Neon project and API key.

testing database

npm install neon-testing

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NEON-TESTING

neon-testing

testingjavascriptv2.7.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

makeNeonTesting

✓ import { makeNeonTesting } from 'neon-testing'

✗ const makeNeonTesting = require('neon-testing')

ESM-only package; CommonJS require() will throw an error.

NeonTestingConfig

✓ import type { NeonTestingConfig } from 'neon-testing'

✗ import { NeonTestingConfig } from 'neon-testing'

NeonTestingConfig is a TypeScript type; import it using type import to avoid runtime errors.

NeonTestingResult

✓ import type { NeonTestingResult } from 'neon-testing'

Utility type for the return value of makeNeonTesting.

Sets up an isolated Neon branch for a test file using makeNeonTesting, creates a table, inserts data, and verifies the result.

// minimal.test.ts import { expect, test } from 'vitest'; import { makeNeonTesting } from 'neon-testing'; import { Pool } from '@neondatabase/serverless'; const cleanup = makeNeonTesting({ apiKey: process.env.NEON_API_KEY ?? '', projectId: process.env.NEON_PROJECT_ID ?? '', autoCloseWebSockets: true, })(); 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 ('Alice')"); const { rows } = await pool.query('SELECT * FROM users'); expect(rows).toHaveLength(1); expect(rows[0].name).toBe('Alice'); await pool.end(); }); afterAll(async () => { await cleanup(); });

Debug

Known issues

breakingESM-only: This package does not support CommonJS (require()).

fix

Use import statements instead of require().

affects: >=2.0.0

deprecatedVitest v3 and v4 support only; older vitest versions are not supported.

fix

Upgrade vitest to v3 or v4 (or v5, v6, etc. if supported by future releases).

affects: >=2.0.0

gotchaNeon API key and project ID required; missing will throw an error.

fix

Set NEON_API_KEY and NEON_PROJECT_ID environment variables.

affects: >=1.0.0

gotchaTest branches auto-delete after 10 minutes by default; test runs taking longer may timeout.

fix

Increase the expiresIn option (e.g., expiresIn: 20) for long-running tests.

affects: >=1.0.0

gotchaautoCloseWebSockets is recommended for Neon WebSocket drivers to prevent hanging connections.

fix

Set autoCloseWebSockets: true in the configuration.

affects: >=2.0.0

breakingVitest v2 not supported; packages requiring vitest@2 will fail.

fix

Use vitest@3 or later.

affects: >=2.0.0

breakingRequires vite@7 as peer dependency; older vite versions incompatible.

fix

Install vite@7 or later.

affects: >=2.0.0

Errors

Common errors & fixes

Error: The package "neon-testing" is not compatible with CommonJS. Use ESM import instead.

Using require() instead of import.

fix

Change require('neon-testing') to import { makeNeonTesting } from 'neon-testing'.

TypeError: makeNeonTesting is not a function

Incorrect import or missing default export.

fix

Ensure you import the named export: import { makeNeonTesting } from 'neon-testing'.

Error: NEON_API_KEY environment variable is not set

API key missing from environment.

fix

Set NEON_API_KEY in your .env file or test environment.

Error: Branch creation failed: 401 Unauthorized

Invalid or expired Neon API key.

fix

Generate a new Neon API key and update your environment variable.

Error: Project not found: <project_id>

Incorrect NEON_PROJECT_ID.

fix

Verify your Neon project ID from the Neon console.

Upgrade

Version history

2.7.0latest on npm

Audit

Dependencies

viterequiredPeer dependency required by vitest

vitestrequiredPeer dependency required for test runner integration

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/starmode-base/neon-testing ↗

packageneon-testing ↗

homepagehttps://github.com/starmode-base/neon-testing ↗