vitest-mongodb

library1.0.3jsnpmunverified

vitest-mongodb is a utility package designed to facilitate integration testing for applications using MongoDB within a Vitest test environment. It leverages `mongodb-memory-server` to spin up an ephemeral, in-memory MongoDB instance for each test run or suite, ensuring isolated and clean test states without requiring a persistent MongoDB installation. The current stable version is 1.0.3, with updates typically driven by upstream changes in Vitest or `mongodb-memory-server`. This package does not have a stated fixed release cadence but follows standard semantic versioning practices. Its key differentiator from `jest-mongodb` is its native integration with Vitest's setup files and global variables, providing a streamlined, Vite-centric experience, although some configuration paradigms from `jest-mongodb` have different implementations or are not directly supported.

testing database

npm install vitest-mongodb

github ↗package ↗

INSTALL

IMPORT

SIG · VITEST-MONGODB

vitest-mongodb

testingjavascriptv1.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

setup

✓ import { setup } from 'vitest-mongodb';

✗ const { setup } = require('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

✓ import { teardown } from 'vitest-mongodb';

✗ const { teardown } = require('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.

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(); } });

Debug

Known issues

gotchaWhen 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`).

affects: >=1.0.0

gotchaTypeScript 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.

affects: >=1.0.0

gotchaThe `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.

affects: >=1.0.0

gotchaConfiguration 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 } } });`.

affects: >=1.0.0

Errors

Common errors & fixes

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

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

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

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).

Upgrade

Version history

1.0.3latest on npm

Audit

Dependencies

mongodb-memory-serverrequiredProvides the in-memory MongoDB instance for testing.

vitestrequiredThe core test runner it integrates with; typically a devDependency in consumer projects, but fundamental to this library's function.

Agent activity

27 hits · last 30 days

node