Testing

The full external version of this is in TESTING.md. This page summarizes the test taxonomy, the conventions for writing each kind, and the runner commands.

Frameworks: Jest and Vitest

Older packages run on Jest. Newer subcommands and packages run on Vitest. packages/cli runs both — Jest for legacy commands, Vitest for new subcommand coverage. From AGENTS.md:

Default Jest/Vitest runner is invoked via pnpm --filter @prisma/<pkg> test <pattern>; it wraps dotenv and expects .db.env.

Test files conventions:

• *.test.ts — Jest tests, excluded from build output by esbuild config
• *.vitest.ts — Vitest tests in mixed packages

Test taxonomy

graph TD
    A[Test types]
    A --> Unit[Unit tests<br/>per-package src/__tests__/*.test.ts]
    A --> CmdTests[CLI command tests<br/>packages/cli/src/__tests__/commands]
    A --> Functional[Functional matrix<br/>packages/client/tests/functional]
    A --> E2E[Client e2e<br/>packages/client/tests/e2e]
    A --> Integration[Integration tests<br/>packages/integration-tests]
    A --> Migrate[Migrate tests<br/>packages/migrate/src/__tests__]
    A --> Bench[Benchmarks<br/>*.bench.ts]

Unit tests

Per-package, run as:

cd packages/<pkg>
pnpm run test [pattern]    # name pattern
pnpm run test [pattern] -t [test name]
pnpm run test [pattern] -u # update snapshots

These typically don't need a database. They live next to the source under src/__tests__/ (or alongside source as *.test.ts).

CLI command tests

Tests for individual prisma <command> subcommands live under packages/cli/src/__tests__/commands/ and packages/migrate/src/__tests__/. They use the helper context from packages/migrate/src/__tests__/__helpers__/context.ts, which exposes:

• ctx.setConfigFile(name) — point the next CLI invocation at a specific prisma.config.ts fixture; reset automatically after each test
• ctx.setDatasource(url) / ctx.resetDatasource() — override the datasource URL for one invocation

When a fixture has multiple schemas (e.g., invalid-url.prisma), it usually has matching configs (invalid-url.config.ts) that tests swap between with ctx.setConfigFile.

When testing namespaces (db, migrate), see packages/migrate/src/__tests__/DbCommand.test.ts for the pattern.

Client functional tests (the matrix)

The largest single test surface area. Each test is a directory under packages/client/tests/functional/ with three files:

• _matrix.ts — defines provider/adapter/preview-feature combinations
• prisma/_schema.ts — schema template, parameterized on matrix values
• tests.ts (or test.ts) — the actual test code

Example matrix:

import { defineMatrix } from '../_utils/defineMatrix';

export default defineMatrix(() => [
  [{ provider: Providers.SQLITE }, { provider: Providers.POSTGRESQL }],
  [{ previewFeatures: '' }, { previewFeatures: 'improvedQueryRaw' }],
]);

The product (SQLITE×'', SQLITE×improvedQueryRaw, POSTGRESQL×'', POSTGRESQL×improvedQueryRaw) generates four test suites. Use the second argument of defineMatrix to exclude impossible combinations.

Schema templates are functions of the matrix entry; use idForProvider(provider) for portable primary keys.

Run them:

pnpm --filter @prisma/client test:functional       # types + code
pnpm --filter @prisma/client test:functional:code  # code only
pnpm --filter @prisma/client test:functional:types # type checks only
pnpm --filter @prisma/client test:functional:code --adapter js_pg <pattern>

The driver-adapter flavors are: js_pg, js_neon, js_libsql, js_planetscale, js_d1, js_better_sqlite3, js_mssql, js_mariadb, js_pg_cockroachdb.

pnpm new-test (run inside packages/client) scaffolds a new test directory.

Conditional type tests

If different matrix entries produce different generated types, a single test file may be valid for some and invalid for others. Use the @ts-test-if magic comment:

// @ts-test-if: provider !== Providers.MONGODB
prisma.$queryRaw`...`;

When the JS expression evaluates falsy, @ts-expect-error is inserted at generation time.

Client e2e tests

packages/client/tests/e2e/. Need a fresh root build:

pnpm build
pnpm --filter @prisma/client test:e2e --verbose --runInBand

Used for end-to-end scenarios that require a real generated client and process.

Integration tests

packages/integration-tests/ — provider-by-provider coverage that doesn't fit naturally inside the client package. Mostly Jest's each for parameterized scenarios:

cd packages/integration-tests
pnpm run jest integration.sqlite -t 'findOne where PK'

Migrate tests

Under packages/migrate/src/__tests__/. Fixtures in packages/migrate/src/__tests__/fixtures mirror the test names. The ctx helpers from packages/migrate/src/__tests__/__helpers__/context.ts are shared.

Test databases

The docker/docker-compose.yml file launches PostgreSQL, MySQL, MariaDB, MS SQL Server, MongoDB (with replica set init), and PlanetScale's local proxy. Bring it up with:

docker compose -f docker/docker-compose.yml up -d

Ports and credentials are in .db.env, loaded automatically by the test runners (dotenv -e ../../.db.env).

Benchmarks

pnpm bench [pattern]

Locations:

• packages/client/src/__tests__/benchmarks/query-performance/query-performance.bench.ts — end-to-end queries
• packages/client/src/__tests__/benchmarks/query-performance/compilation.bench.ts — query compilation
• packages/client-engine-runtime/bench/interpreter.bench.ts — interpreter / data mapper
• packages/client/src/__tests__/benchmarks/huge-schema/, lots-of-relations/ — generation

CodSpeed (CI: benchmark.yml) tracks these over time and alerts on >100% regression.

When to put a test where

Change	Test location
New CLI subcommand	packages/cli/src/__tests__/commands/<Name>.test.ts
New Migrate subcommand or behavior	packages/migrate/src/__tests__/<Name>.test.ts
New Client query behavior	New folder under packages/client/tests/functional
Driver-adapter-specific behavior	Functional test with _matrix.ts filtering by adapter
Cross-provider integration scenario	packages/integration-tests/
Generator output	packages/client/src/__tests__/types/
Schema engine RPC behavior	packages/migrate/src/__tests__/
Anything bound to a specific framework like Next.js	prisma/ecosystem-tests (different repo)

Rule of thumb: if you can test it in prisma/prisma, do that. Only use ecosystem-tests for framework-bound or platform-bound coverage.