Vitest MongoDB Memory Server Integration

Common errors

• Cannot find module 'mongodb-memory-server' or its corresponding type declarations.

  cause The `mongodb-memory-server` package is a peer dependency and has not been explicitly installed in the project.
  fix Run `npm install -D mongodb-memory-server` or `yarn add -D mongodb-memory-server`.

• Property 'db' does not exist on type 'TestContext'.

  cause When using `vitest-mms/globalSetup` with TypeScript, the `tsconfig.json` has not been updated to include the type declarations, or you're using a plain `test` instead of `mssTest`.
  fix Add `'vitest-mms/globalSetup'` to the `types` array in `compilerOptions` of your `tsconfig.json`. If using extended context, ensure you are importing and using `mssTest` from the correct path (e.g., `vitest-mms/mongodb/test`).

• TypeError: Cannot read properties of undefined (reading 'collection') at globalSetup

  cause The global setup file `vitest-mms/globalSetup` was not properly configured in `vitest.config.mjs` or there's an issue with the underlying `mongodb-memory-server` initialization.
  fix Ensure `globalSetup: ['vitest-mms/globalSetup']` is correctly specified in your `vitest.config.mjs` and that `mongodb-memory-server` is installed.

Warnings

• breaking Version 0.2.0 introduced breaking changes by removing deprecated exports. Code relying on older, deprecated paths or symbols will no longer function.
  Fix: Refer to the updated documentation and release notes for version 0.2.0 to update import paths and symbols. Ensure all exports are sourced from current `vitest-mms/mongodb/*` or `vitest-mms/mongoose/*` paths.
• gotcha All database-related dependencies (mongodb, mongodb-memory-server, mongoose, vitest) are peer dependencies and must be installed explicitly in your project.
  Fix: Install required peer dependencies: `npm install -D mongodb mongodb-memory-server mongoose vitest` or `yarn add -D mongodb mongodb-memory-server mongoose vitest`.
• gotcha When using TypeScript with `globalSetup`, you must add `'vitest-mms/globalSetup'` to the `types` array in your `tsconfig.json` to correctly extend the Vitest `TestContext`.
  Fix: Add `"types": ["vitest-mms/globalSetup", ...]` to your `compilerOptions` in `tsconfig.json`.
• gotcha The `mssTest` helper is overloaded; it exists under both `vitest-mms/mongodb/test` and `vitest-mms/mongoose/test`. Ensure you are importing the correct one for your chosen driver/ODM, as their extended contexts differ (e.g., `db` vs. `connection`).
  Fix: Verify the import path matches your usage: `import { mssTest } from 'vitest-mms/mongodb/test'` for native driver or `import { mssTest } from 'vitest-mms/mongoose/test'` for Mongoose.

Install

• npm install vitest-mms npm
• yarn add vitest-mms yarn
• pnpm add vitest-mms pnpm

Imports

• globalSetup
  wrong:

  import { globalSetup } from 'vitest-mms'

  correct:

  import 'vitest-mms/globalSetup'

  This is a side-effect import for Vitest's global setup file. Ensure it's listed in vitest.config.mjs and tsconfig.json types.
• setupDb

  import { setupDb } from 'vitest-mms/mongodb/helpers'

  Use this helper for simplified setup with the native MongoDB driver within individual test files.
• mssTest
  wrong:

  import { mssTest } from 'vitest-mms/mongoose/test'

  correct:

  import { mssTest } from 'vitest-mms/mongodb/test'

  This `mssTest` variant extends Vitest's context with `db` and `mongoClient` for the native MongoDB driver. A separate `mssTest` exists for Mongoose at a different path.
• setupMongooseConnection

  import { setupMongooseConnection } from 'vitest-mms/mongoose/helpers'

  Use this helper for simplified setup with Mongoose within individual test files.

Quickstart

Demonstrates the global Vitest setup using `vitest-mms/globalSetup` and how to inject the `MONGO_URI` into tests for manual connection with the native MongoDB driver.

import { defineConfig } from 'vitest/config';
import { inject, test, expect } from 'vitest';
import { MongoClient } from 'mongodb';

// vitest.config.mjs (or .ts)
export default defineConfig({
  test: {
    globalSetup: ['./vitest.globalSetup.ts'], // or vitest-mms/globalSetup directly
  },
});

// vitest.globalSetup.ts
import 'vitest-mms/globalSetup';

// index.test.ts
const MONGO_URI = inject<string>('MONGO_URI');

test('should connect to in-memory MongoDB', async () => {
  expect(MONGO_URI).toBeTypeOf('string');
  expect(MONGO_URI).toMatch(/^mongodb:\/\/127\.0\.0\.1:\d+\//);

  const client = new MongoClient(MONGO_URI);
  await client.connect();
  const db = client.db('testdb');
  const collection = db.collection('testcollection');
  await collection.insertOne({ name: 'Test Document' });
  const doc = await collection.findOne({ name: 'Test Document' });
  expect(doc).toBeDefined();
  await client.close();
});