prisma/prisma

Tests

Active contributors: jacek-prisma, Oleksii Orlenko

Purpose

The @prisma/client package owns the largest test surface area in the monorepo. This page maps the test directories so you know where to add coverage for a given change.

Layout

packages/client/
├── tests/
│   ├── functional/        # The matrix-driven functional suite (current default)
│   └── e2e/               # End-to-end with real generated clients
└── src/
    └── __tests__/
        ├── benchmarks/    # Benchmark.js suites (CodSpeed)
        ├── integration/
        │   ├── happy/     # Legacy folder-based integration tests (write functional tests instead)
        │   └── errors/    # Legacy error path integration tests
        ├── types/         # tsd type tests for generated client TS types
        └── *.test.ts      # Unit tests

When to add what

Change	Where the test goes
New query behavior (CRUD action, filter, etc.)	New folder in `tests/functional/<topic>/`
Regression for a closed issue	`tests/functional/issues/<issue-number>/`
Driver-adapter-specific behavior	Functional test with `_matrix.ts` filtering by adapter
Generated TypeScript types	`src/__tests__/types/*.ts` (uses `tsd`)
Pure runtime utility	`src/__tests__/<name>.test.ts` (Jest unit)
Cross-package end-to-end	`tests/e2e/<scenario>/` (requires fresh `pnpm build`)
Performance	`src/__tests__/benchmarks/...` plus `*.bench.ts` (Benchmark.js)

The legacy integration/happy/ and integration/errors/ folders are flagged as deprecated in TESTING.md. Don't add to them; write a functional test instead.

Functional test anatomy

Each functional test directory has three files (see TESTING.md for details):

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

A minimal example matrix that runs against SQLite and PostgreSQL:

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

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

Use idForProvider(provider) from _utils/idForProvider for portable primary key declarations:

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

export default testMatrix.setupSchema(
  ({ provider }) => `
  generator client { provider = "prisma-client-js" }
  datasource db { provider = "${provider}" }
  model User { id ${idForProvider(provider)} }
`
);

Running

# Code only (no type checks)
pnpm --filter @prisma/client test:functional:code

# Code + type checks
pnpm --filter @prisma/client test:functional

# Type checks only
pnpm --filter @prisma/client test:functional:types

# Specific adapter
pnpm --filter @prisma/client test:functional:code --adapter js_pg <pattern>

# E2E (needs prior root build)
pnpm build && pnpm --filter @prisma/client test:e2e --verbose --runInBand

Each functional test produces generated artifacts under tests/functional/<test>/.generated/. The generated client there imports packages/client/runtime/client.js directly. If you change runtime code in src/runtime/ and want functional tests to pick it up, you may need to rebuild the runtime bundle first.

Asserting on errors

From AGENTS.md:

// ✅ Works across realms
expect(result.name).toBe('PrismaClientKnownRequestError');
expect(result.code).toBe('P2002');

// ❌ Fails when the error class is from a different module realm
expect(result).toBeInstanceOf(PrismaClientKnownRequestError);

The instanceof check is brittle in functional tests because the generated client lives in a separate .generated/ directory and gets its own PrismaClientKnownRequestError class instance.

Benchmarks

Benchmarks live under src/__tests__/benchmarks/ and run via pnpm bench [pattern]. Notable suites:

query-performance/query-performance.bench.ts — end-to-end query timing
query-performance/compilation.bench.ts — query compilation only
huge-schema/, lots-of-relations/ — generation throughput

Numbers are tracked over time by CodSpeed in benchmark.yml. The threshold for a regression alert is >100% (intentionally loose because variance on huge-schema generation is high).