Vitest MongoDB

Common errors

• Property '__MONGO_URI__' does not exist on type 'typeof globalThis'. Did you mean 'GLOBAL_VAR_TEST_URI'?

  cause The TypeScript compiler does not have a type definition for the `__MONGO_URI__` global variable provided by `vitest-mongodb`.
  fix Create a file like `test/global.d.ts` and add `declare var __MONGO_URI__: string;` to declare the global variable.

• MongooseServerSelectionError: connect ECONNREFUSED ::1:xxxxx

  cause The in-memory MongoDB server failed to start, or tests are trying to connect before it's ready, often due to Vitest running tests in separate threads without `vitest-mongodb`'s setup being correctly executed once.
  fix Ensure `vitest.config.ts` includes `setupFiles` pointing to your `vitest-mongodb` setup. If running tests concurrently, add `--no-threads` to your Vitest command (e.g., `vitest --no-threads`).

• TypeError: (0 , vitest_mongodb_1.setup) is not a function

  cause This error typically indicates an incorrect import statement, often when trying to use CommonJS `require` syntax in an ESM project, or a bundler misconfiguration.
  fix Verify that you are using ESM `import { setup, teardown } from 'vitest-mongodb';` and that your Vitest project is correctly configured for ESM modules (e.g., `type: "module"` in `package.json` or appropriate `tsconfig.json` settings).

Warnings

• gotcha When running Vitest tests concurrently with worker threads, `vitest-mongodb`'s setup file might be called multiple times, leading to multiple MongoDB instances and inconsistent test states.
  Fix: To ensure a single shared MongoDB instance, run Vitest with the `--no-threads` option (e.g., `vitest --no-threads`).
• gotcha TypeScript users will encounter type errors when accessing `globalThis.__MONGO_URI__` because the type definition is not automatically inferred.
  Fix: Create a declaration file (e.g., `test/global.d.ts`) with `declare var __MONGO_URI__: string;` to extend the `globalThis` interface.
• gotcha The `jest-mongodb` option `mongoURLEnvName` is explicitly not implemented in `vitest-mongodb`.
  Fix: Directly access the MongoDB connection string via `globalThis.__MONGO_URI__` within your tests and setup files.
• gotcha Configuration options for `setup()` require a `type` property ('default' for `MongoMemoryServerOpts` or 'replSet' for `MongoMemoryReplSetOpts`) to correctly infer `serverOptions`.
  Fix: Always specify `type: "default"` or `type: "replSet"` when passing `serverOptions` to the `setup` function, e.g., `await setup({ type: "replSet", serverOptions: { replSet: { count: 3 } } });`.

Install

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

Imports

• setup
  wrong:

  const { setup } = require('vitest-mongodb');

  correct:

  import { setup } from 'vitest-mongodb';

  vitest-mongodb is built for ESM; CommonJS `require` might work with bundlers but is not the idiomatic way to use it with Vitest.
• teardown
  wrong:

  const { teardown } = require('vitest-mongodb');

  correct:

  import { teardown } from 'vitest-mongodb';

  Used in Vitest's `afterAll` hook to clean up the in-memory MongoDB instance.
• __MONGO_URI__

  globalThis.__MONGO_URI__

  This is a global variable made available after `setup()` runs. For TypeScript, it requires a declaration like `declare var __MONGO_URI__: string;` in a `.d.ts` file.

Quickstart

This example configures Vitest to use `vitest-mongodb` via `setupFiles`, initializes and tears down an in-memory MongoDB server, and demonstrates how to connect and interact with it in a test using the globally exposed `__MONGO_URI__` variable. It also includes the necessary TypeScript declaration.

import { defineConfig } from "vitest/config";
import { afterAll, beforeAll } from "vitest";
import { setup, teardown } from "vitest-mongodb";
import { MongoClient } from "mongodb";
import { it, expect } from "vitest";

// vitest.config.ts
export default defineConfig({
  test: {
    setupFiles: ["./test/mongo-memory-server.ts"],
  },
});

// ./test/mongo-memory-server.ts
beforeAll(async () => {
  await setup({
    type: "default",
    serverOptions: { port: 27017, dbName: 'myTestDb' }
  });
});

afterAll(async () => {
  await teardown();
});

// ./test/global.d.ts (for TypeScript users)
declare var __MONGO_URI__: string;

// ./test/example.test.ts
it("should connect to the in-memory MongoDB and perform a ping", async () => {
  expect(globalThis.__MONGO_URI__).toBeDefined();
  const client = new MongoClient(globalThis.__MONGO_URI__);
  try {
    await client.connect();
    const db = client.db("myTestDb"); // Use the configured dbName
    const result = await db.command({ ping: 1 });
    expect(result.ok).toBe(1);
  } finally {
    await client.close();
  }
});