Testing Prisma Engines - Prisma Engines

Test Organization

Prisma Engines has two main test categories:

Unit tests - Test internal functionality of individual crates and components
Integration tests - Run end-to-end requests through the driver adapter executor and schema engine

Unit Tests

Unit tests are distributed across the codebase, typically in ./tests folders at the root of modules.

Run All Unit Tests

To run unit tests for the whole workspace (excluding integration suites):

make test-unit

This excludes crates that require external services:

quaint
query-engine-tests
sql-migration-tests
schema-engine-cli
sql-schema-describer
sql-introspection-tests
mongodb-schema-connector

Run Tests for Specific Crates

cargo test -p psl -F all

Update Test Snapshots

Many tests use expect! macro snapshots. When diagnostics or output changes:

UPDATE_EXPECT=1 cargo test -p prisma-fmt
UPDATE_EXPECT=1 cargo test -p query-compiler

Always review snapshot diffs to ensure changes are intentional before committing.

Integration Tests

Schema Engine Tests

Schema engine tests require database connections. Set environment variables or use helper scripts:

Set Database Environment Variables

Use the .test_database_urls/ helper scripts:

source .test_database_urls/postgres

Or set manually:

export TEST_DATABASE_URL="postgres://user:password@localhost:5432/test"
export TEST_SHADOW_DATABASE_URL="postgres://user:password@localhost:5432/shadow"

Run Schema Engine Tests

cargo test -p sql-migration-tests -- --nocapture

Connector Test Kit (Query Compiler)

The connector test kit exercises the query compiler and driver adapters end-to-end.

Architecture

The test kit consists of three crates:

           ┌────────────────────┐
       ┌───│ query-engine-tests │───┐
       │   └────────────────────┘   │
       ▼                            ▼
┌────────────────────┐       ┌────────────────────┐
│ query-test-macros  │       │ query-tests-setup  │
└────────────────────┘       └────────────────────┘

query-engine-tests: Actual integration tests in tests/ folder
query-test-macros: Macro definitions (#[connector_test], #[test_suite])
query-tests-setup: Test configuration, connector tags, runners, logging

Prerequisites

Install Dependencies

Rust toolchain
Docker (for SQL connectors)
Node.js ≥ 20 and pnpm (for driver adapters)
direnv allow in repository root

Clone Prisma Repository

Driver adapters are built from the main Prisma repo:

cd ..
git clone https://github.com/prisma/prisma.git
cd prisma-engines

Setup Test Environment

Use dev-*-qc Makefile helpers to set up databases and build artifacts:

make dev-pg-qc

These targets:

Start the database container (if needed)
Build query compiler Wasm (build-qc-wasm-fast)
Build driver adapters kit (build-driver-adapters-kit-qc)
Write .test_config file

Configuration

Tests use either environment variables or a .test_config file: Environment Variables:

export WORKSPACE_ROOT=/path/to/prisma-engines
export TEST_CONNECTOR="postgres"
export TEST_CONNECTOR_VERSION="13"

Config File (Recommended):

.test_config

{
    "connector": "postgres",
    "version": "13"
}

The config file should be in the current working directory or $WORKSPACE_ROOT.

Run Connector Tests

cargo test -p query-engine-tests

Run with Make Targets

make test-qe

Test Specific Driver Adapters

Set DRIVER_ADAPTER environment variable:

DRIVER_ADAPTER=pg make test-qe
DRIVER_ADAPTER=neon make test-qe
DRIVER_ADAPTER=planetscale make test-qe

Or use dedicated targets:

make test-pg-qc

Driver Adapter Configuration

For advanced driver adapter testing, set these environment variables:

export EXTERNAL_TEST_EXECUTOR="$WORKSPACE_ROOT/libs/driver-adapters/executor/script/testd-qc.sh"
export DRIVER_ADAPTER=neon
export DRIVER_ADAPTER_CONFIG='{"proxyUrl":"127.0.0.1:5488/v1"}'

Relation Loading Strategies

Test different relation loading strategies:

PRISMA_RELATION_LOAD_STRATEGY=join make dev-pg-qc
PRISMA_RELATION_LOAD_STRATEGY=join make test-pg-qc

Database Management

Start All Databases

make all-dbs-up

Stop All Databases

make all-dbs-down

Start Specific Databases

make start-postgres13

Snapshot Testing with Insta

Many tests use insta for snapshot assertions.

Install cargo-insta

cargo install cargo-insta

Run Tests with Insta

# Run all tests and collect snapshots
cargo insta test --package query-engine-tests

# Review snapshots interactively
cargo insta review

# Accept all snapshots
cargo insta accept

# Reject all snapshots
cargo insta reject

Don’t blindly accept all snapshots! Always review changes carefully to ensure they match expected behavior.

Test Environment Variables

Key environment variables for testing:

Variable	Description
`WORKSPACE_ROOT`	Path to repository root
`TEST_CONNECTOR`	Connector to test (postgres, mysql, etc.)
`TEST_CONNECTOR_VERSION`	Connector version (13, 8, etc.)
`DRIVER_ADAPTER`	Driver adapter name (pg, neon, planetscale)
`DRIVER_ADAPTER_CONFIG`	JSON config for driver adapter
`EXTERNAL_TEST_EXECUTOR`	Path to test executor script
`TEST_DATABASE_URL`	Primary database connection string
`TEST_SHADOW_DATABASE_URL`	Shadow database for migrations
`LOG_LEVEL`	Logging level (trace, debug, info)
`RUST_LOG`	Rust logging filter
`UPDATE_EXPECT`	Set to `1` to update expect! snapshots
`SIMPLE_TEST_MODE`	Reduces relation_link_test tests
`RELATION_TEST_IDX`	Run specific relation test by index

Benchmarking

Run Query Compiler Benchmarks

make bench-qc

Save Benchmark Baseline

make bench-qc-baseline NAME=main

Compare Against Baseline

make bench-qc-compare NAME=main

Profile Query Compiler

make profile-qc

Troubleshooting

Tests Skip with “Missing TEST_DATABASE_URL”

Set the required environment variables or use the helper scripts:

source .test_database_urls/postgres

expect! Snapshot Failures

Update snapshots when output changes:

UPDATE_EXPECT=1 cargo test -p prisma-fmt

Driver Adapter Build Fails

Ensure ../prisma repository is checked out:

cd ..
git clone https://github.com/prisma/prisma.git
cd prisma-engines
make build-driver-adapters-kit-qc

Tests Run Concurrently Causing Issues

Use single-threaded execution:

cargo test -p query-engine-tests -- --test-threads 1
# or
make test-qe-st

Overview

Core Components

Query Compiler

Schema Engine

Prisma Schema Language

Development

​Test Organization

​Unit Tests

​Run All Unit Tests

​Run Tests for Specific Crates

​Update Test Snapshots

​Integration Tests

​Schema Engine Tests

​Connector Test Kit (Query Compiler)

​Architecture

​Prerequisites

​Setup Test Environment

​Configuration

​Run Connector Tests

​Run with Make Targets

​Test Specific Driver Adapters

​Driver Adapter Configuration

​Relation Loading Strategies

​Database Management

​Start All Databases

​Stop All Databases

​Start Specific Databases

​Snapshot Testing with Insta

​Install cargo-insta

​Run Tests with Insta

​Test Environment Variables

​Benchmarking

​Run Query Compiler Benchmarks

​Save Benchmark Baseline

​Compare Against Baseline

​Profile Query Compiler

​Troubleshooting

​Tests Skip with “Missing TEST_DATABASE_URL”

​expect! Snapshot Failures

​Driver Adapter Build Fails

​Tests Run Concurrently Causing Issues

​Next Steps

Build docs developers (and LLMs) love

Test Organization

Unit Tests

Run All Unit Tests

Run Tests for Specific Crates

Update Test Snapshots

Integration Tests

Schema Engine Tests

Connector Test Kit (Query Compiler)

Architecture

Prerequisites

Setup Test Environment

Configuration

Run Connector Tests

Run with Make Targets

Test Specific Driver Adapters

Driver Adapter Configuration

Relation Loading Strategies

Database Management

Start All Databases

Stop All Databases

Start Specific Databases

Snapshot Testing with Insta

Install cargo-insta

Run Tests with Insta

Test Environment Variables

Benchmarking

Run Query Compiler Benchmarks

Save Benchmark Baseline

Compare Against Baseline

Profile Query Compiler

Troubleshooting

Tests Skip with “Missing TEST_DATABASE_URL”

expect! Snapshot Failures

Driver Adapter Build Fails

Tests Run Concurrently Causing Issues

Next Steps