|
| 1 | + |
| 2 | + |
| 3 | +<div align="center"> |
| 4 | + <h1>vitest-environment-prisma-postgres</h1> |
| 5 | + <a href="https://www.npmjs.com/package/vitest-environment-prisma-postgres"><img src="https://img.shields.io/npm/v/vitest-environment-prisma-postgres.svg?style=flat" /></a> |
| 6 | + <a href="https://github.com/prisma/prisma/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" /></a> |
| 7 | + <br /> |
| 8 | + <br /> |
| 9 | + <a href="#features">Features</a> |
| 10 | + <span> • </span> |
| 11 | + <a href="#installation--setup">Installation & Setup</a> |
| 12 | + <span> • </span> |
| 13 | + <a href="#typescript-configuration">TypeScript Configuration</a> |
| 14 | + <span> • </span> |
| 15 | + <a href="#known-limiations">Known Limitations</a> |
| 16 | + <br /> |
| 17 | + <hr /> |
| 18 | +</div> |
| 19 | + |
| 20 | +## Motivation |
| 21 | + |
| 22 | +[Vitest](https://vitest.dev/) environment for [Prisma](https://www.prisma.io/) + [PostgreSQL](https://www.postgresql.org/) designed for fast integration tests. |
| 23 | + |
| 24 | +Integration tests against a database are often slow because each test needs its own database state. Teams typically either: |
| 25 | + |
| 26 | +- Reseed the database before every test, or |
| 27 | +- Insert all required data inside each test. |
| 28 | + |
| 29 | +Both approaches are slow, repetitive, and dominate test runtime. |
| 30 | + |
| 31 | +**This environment eliminates that cost.** |
| 32 | + |
| 33 | +You run migrations and seed your test database once. |
| 34 | +Each test then runs inside its own database transaction, which is rolled back automatically after the test finishes. Your tests stay isolated, realistic, and extremely fast, creating dedicated data for every test. |
| 35 | + |
| 36 | +## Features |
| 37 | + |
| 38 | +- Run integration tests against a real PostgreSQL instance. |
| 39 | +- Seed your database once at the beginning of the test run. |
| 40 | +- Tests run inside sandboxed transactions, but application-level transactions still work normally. |
| 41 | +- Test transactions are rolled back after every test. |
| 42 | +- Tests are isolated, fast, and order independent. |
| 43 | + |
| 44 | +## Installation & Setup |
| 45 | + |
| 46 | +#### Step 1: Install the environment |
| 47 | + |
| 48 | +First, install the environnment: |
| 49 | + |
| 50 | +```shell |
| 51 | +npm install vitest-environment-prisma-postgres --save-dev |
| 52 | +``` |
| 53 | + |
| 54 | +#### Step 2: Ensure peer dependency availability |
| 55 | + |
| 56 | +Then, ensure that the required peer dependencies are available. This library requires that you have all of the following installed in your project: |
| 57 | + |
| 58 | +- `vitest` in version `4.x` |
| 59 | +- `prisma` in version `7.x` |
| 60 | +- `@prisma/adapter-pg` in version `7.x` |
| 61 | + |
| 62 | +#### Step 3: Enable and configure the environment in your Vitest config |
| 63 | + |
| 64 | +Configure the environment in your Vitest config: |
| 65 | + |
| 66 | +```ts |
| 67 | +import { defineConfig } from 'vitest/config'; |
| 68 | + |
| 69 | +export default defineConfig({ |
| 70 | + test: { |
| 71 | + environment: 'prisma-postgres', |
| 72 | + environmentOptions: { |
| 73 | + 'prisma-postgres': { |
| 74 | + // You must configure the path to your prisma client. |
| 75 | + clientPath: "./generated/prisma-client" |
| 76 | + } |
| 77 | + }, |
| 78 | + setupFiles: [ |
| 79 | + // Registers hooks that start and roll back a database transaction around every test. |
| 80 | + 'vitest-environment-prisma-postgres/setup', |
| 81 | + // This is where you mock your Prisma client to use the test environment's client. |
| 82 | + './vitest.setup.ts' |
| 83 | + ], |
| 84 | + } |
| 85 | +}); |
| 86 | +``` |
| 87 | + |
| 88 | +#### Step 4: Provide a `DATABASE_URL` |
| 89 | + |
| 90 | +This environment will create the Prisma client and PostgreSQL adapter for your tests, so it has to know the connectionString to your test database. |
| 91 | + |
| 92 | +You provide it by running your tests with a `DATABASE_URL` environment variable, which must point to a PostgreSQL instance for testing. It can point to: |
| 93 | + |
| 94 | +- a real local PostgresSQL instance |
| 95 | +- a docker-compose container |
| 96 | +- a Testcontainers-created instance (see below) |
| 97 | +- a cloud-hosted PostgresSQL instance, e.g, Supabase or Prisma Postgres |
| 98 | + |
| 99 | +#### Step 5: Mock Prisma client |
| 100 | + |
| 101 | +In your setupFile, `vitest.setup.ts`, mock your local Prisma client with the client provided by this environment: |
| 102 | + |
| 103 | +```ts |
| 104 | +import { vi } from 'vitest'; |
| 105 | + |
| 106 | +vi.mock('./generated/prisma-client', () => ({ |
| 107 | + default: globalThis.prismaPostgresTestContext.client, |
| 108 | +})); |
| 109 | +``` |
| 110 | + |
| 111 | +This ensures that your application code uses the Prisma client created by the test environment. Combined with the vitest-environment-prisma-postgres/setup file, which starts and rolls back a transaction around every test, this means all Prisma queries from your code run inside an isolated transaction per test. |
| 112 | + |
| 113 | +Please make sure that you're mocking exactly the module path that your code is using to import your Prisma client. |
| 114 | + |
| 115 | +#### Step 6: Seed once per test run |
| 116 | + |
| 117 | +Make sure to seed your test database at the beginning of every test run. |
| 118 | + |
| 119 | +## TypeScript configuration |
| 120 | + |
| 121 | +If you are using TypeScript, make sure to add this environment to your `compilerOptions.types` array in your `tsconfig.json`: |
| 122 | + |
| 123 | +```json |
| 124 | +{ |
| 125 | + "compilerOptions": { |
| 126 | + "types": [ |
| 127 | + "node", |
| 128 | + "vitest/globals", |
| 129 | + "vitest-environment-prisma-postgres" |
| 130 | + ] |
| 131 | + } |
| 132 | +} |
| 133 | +``` |
| 134 | + |
| 135 | +This is required because this environment provides a global type declaration: |
| 136 | + |
| 137 | +```ts |
| 138 | +declare global { |
| 139 | + var prismaPostgresTestContext: PublicPrismaPostgresTestContext; |
| 140 | +} |
| 141 | +``` |
| 142 | + |
| 143 | +Without adding the package to `compilerOptions.types`, TypeScript will not include this global augmentation, and you will get type errors when mocking your Prisma client in `vitest.setup.ts`: |
| 144 | + |
| 145 | +```ts |
| 146 | +vi.mock('./generated/prisma-client', () => ({ |
| 147 | + default: globalThis.prismaPostgresTestContext.client, |
| 148 | + // ^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 149 | + // Error: Element implicitly has an 'any' type because |
| 150 | + // type 'typeof globalThis' has no index signature. |
| 151 | +})); |
| 152 | +``` |
| 153 | + |
| 154 | + |
| 155 | +Adding "vitest-environment-prisma-postgres" to `compilerOptions.types` ensures that the global declaration is loaded and the mock is type-safe. |
| 156 | + |
| 157 | +## Known limitations |
| 158 | + |
| 159 | +- Support for [Vitest pools](https://vitest.dev/config/pool.html#pool) set to `vmThreads` or `vmThreads` is not implemented |
| 160 | +- This environment assumes that tests inside a single worker run one at a time: |
| 161 | + - Do not use `test.concurrent` for tests that touch the database. |
| 162 | + - Keep `maxConcurrency` at `1` for DB integration tests so a worker does not run multiple DB tests at once. |
| 163 | + |
| 164 | +## License |
| 165 | + |
| 166 | +MIT |
0 commit comments