Prisma Mock

Common errors

• Error: Cannot read properties of undefined (reading 'datamodel')

  cause `createPrismaMock` was called without the `datamodel` option when using `prisma-mock/client` for Prisma 7+, or the `dmmf` object was incorrectly imported or passed.
  fix For Prisma 7+, ensure you have configured and run the DMMF generator in your `schema.prisma`. Then, import `* as dmmf from './generated/dmmf'` (or similar path) and pass it as `createPrismaMock(Prisma, { datamodel: dmmf })`.

• TypeError: createPrismaMock is not a function

  cause This typically occurs when attempting to `require` the `prisma-mock` or `prisma-mock/client` package in an ESM context, or due to an incorrect import path.
  fix For ESM projects, use `import createPrismaMock from 'prisma-mock'` or `import createPrismaMock from 'prisma-mock/client'`. If in a CommonJS environment, ensure your project setup correctly handles ESM imports, or verify the package's export map configuration.

• ReferenceError: Prisma is not defined

  cause When using `prisma-mock/client` (required for Prisma 7+), the `Prisma` namespace was not imported or passed correctly as the first argument to `createPrismaMock`.
  fix Ensure you are importing `Prisma` from your generated Prisma client (e.g., `import { Prisma } from "./generated/client";`) and passing it as the first argument to `createPrismaMock`.

Warnings

• breaking The `v1.0.0` release introduced significant breaking changes to the API interface, requiring a review of how `createPrismaMock` is called. It also enabled indexing by default for performance improvements, which might subtly alter behavior if previous versions relied on unindexed behavior.
  Fix: Review the `createPrismaMock` signature and options in the `v1.0.0` release notes and README. Update argument passing, especially if custom DMMF or initial data was used. Adapt any test logic that might be affected by default indexing.
• deprecated The `prisma-mock/legacy` export is deprecated. While currently maintained for backward compatibility, new projects and refactors should migrate to the recommended `prisma-mock` (for Prisma 6 and below) or `prisma-mock/client` (for Prisma 7+) entry points.
  Fix: Update imports from `prisma-mock/legacy` to either `prisma-mock` or `prisma-mock/client` based on your Prisma version and adjust initialization as per the updated API.
• gotcha For Prisma v7 and above, `prisma-mock/client` must be used. This entry point explicitly requires the `Prisma` namespace and a `dmmf` object (generated by a DMMF generator) to be passed during initialization. Failure to provide these or properly configure the DMMF generator will lead to runtime errors.
  Fix: Ensure your `schema.prisma` is configured with a DMMF generator and run `prisma generate`. Import `Prisma` from your generated client path and the DMMF object (e.g., `import * as dmmf from "./generated/dmmf"`), then pass them to `createPrismaMock(Prisma, { datamodel: dmmf })`.
• gotcha When mocking a global Prisma client instance (e.g., a default export in a `db` module), it's crucial to correctly set up your mocking library (e.g., `jest.mock`) and ensure `mockDeep` and `mockReset` are used with `createPrismaMock({ mockClient: db })`. Incorrect setup can lead to state leakage between tests or unexpected behavior.
  Fix: Follow the example in the README for mocking a global Prisma instance using `jest-mock-extended` or `vitest-mock-extended`, ensuring `mockReset` is called `beforeEach` test to prevent state pollution.

Install

• npm install prisma-mock npm
• yarn add prisma-mock yarn
• pnpm add prisma-mock pnpm

Imports

• createPrismaMock
  wrong:

  const createPrismaMock = require("prisma-mock");

  correct:

  import createPrismaMock from "prisma-mock";

  This is the default export, recommended for Prisma versions 6 and below. It automatically uses the Prisma client from `@prisma/client/default`.
• createPrismaMock
  wrong:

  const createPrismaMock = require("prisma-mock/client");

  correct:

  import createPrismaMock from "prisma-mock/client";

  Use this entry point for Prisma v7 and newer. It requires explicitly passing the `Prisma` namespace and a generated `dmmf` object for proper mock initialization.
• Prisma

  import { Prisma } from "./generated/client";

  This represents the Prisma namespace from your generated client, necessary when using `prisma-mock/client` for Prisma v7+ to provide type information. The import path should match your `schema.prisma` output configuration.
• dmmf

  import * as dmmf from "./generated/dmmf";

  This imports the Data Model Meta Format (DMMF) object, which `prisma-mock/client` uses for understanding your Prisma schema in Prisma v7+. Ensure you have a DMMF generator configured in your `schema.prisma`.

Quickstart

This quickstart demonstrates how to initialize `prisma-mock` for Prisma 7+ projects, including setting up the `Prisma` namespace and DMMF. It shows basic `create`, `findUnique`, and `update` operations within a typical testing environment (e.g., Jest or Vitest), along with state clearing and optional initial data seeding.

import createPrismaMock from "prisma-mock/client";
import { Prisma } from "./generated/client"; // Adjust path based on your Prisma client generation
import * as dmmf from "./generated/dmmf"; // Ensure DMMF generator is configured and run

let client: ReturnType<typeof createPrismaMock>;

beforeEach(() => {
  // Initialize the mock client before each test
  client = createPrismaMock(Prisma, {
    datamodel: dmmf,
    // Optionally start with some initial data
    data: {
      user: [
        { id: 1, name: 'Initial User', email: 'initial@example.com' }
      ]
    }
  });
  // Clear any state from previous tests
  client.$clear();
});

describe('User operations', () => {
  it('should create a new user', async () => {
    const newUser = await client.user.create({
      data: {
        id: 2,
        name: 'Alice Smith',
        email: 'alice@example.com',
      },
    });
    expect(newUser).toEqual({ id: 2, name: 'Alice Smith', email: 'alice@example.com' });

    const userCount = await client.user.count();
    expect(userCount).toBe(2); // Includes initial user
  });

  it('should find a user by ID', async () => {
    // Create a user specifically for this test if not pre-seeded
    await client.user.create({ data: { id: 3, name: 'Bob Johnson', email: 'bob@example.com' } });
    const foundUser = await client.user.findUnique({ where: { id: 3 } });
    expect(foundUser?.name).toBe('Bob Johnson');
  });

  it('should update an existing user', async () => {
    const updatedUser = await client.user.update({
      where: { id: 1 },
      data: { name: 'Updated Initial User' },
    });
    expect(updatedUser?.name).toBe('Updated Initial User');
  });
});