mongodb-runner

library6.7.7jsnpmunverified

MongoDB Runner is a utility for programmatically or via CLI spinning up and managing MongoDB server instances and clusters specifically for testing purposes. It simplifies the process of testing code against various MongoDB topologies like standalone, replica sets, or sharded clusters, without requiring manual MongoDB installation or management. The current stable version is 6.7.7, and based on its development activity, it appears to have a regular release cadence, often aligning with new MongoDB server releases or bug fixes. A key differentiator is its ability to download and manage multiple MongoDB server versions locally, including enterprise versions, and to integrate with Docker. It offers both a convenient command-line interface via `npx` and a robust programmatic API for integration into test suites, abstracting away the complexities of `mongod` and `mongos` commands.

testing database

npm install mongodb-runner

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MONGODB-RUNNER

mongodb-runner

testingjavascriptv6.7.7

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.

MongoCluster

✓ import { MongoCluster } from 'mongodb-runner';

✗ const MongoCluster = require('mongodb-runner').MongoCluster;

The library primarily promotes ESM usage for its programmatic API. CommonJS `require` might work for some exports but ESM is preferred and shown in documentation.

start

✓ import { MongoCluster } from 'mongodb-runner'; const cluster = await MongoCluster.start(...);

✗ import { start } from 'mongodb-runner';

`start` is a static method of `MongoCluster`, not a direct export from the package.

CliOptions

✓ import type { CliOptions } from 'mongodb-runner';

Type imports are crucial for TypeScript users to get autocompletion and type checking for configuration options.

This quickstart demonstrates how to programmatically start a standalone MongoDB instance, log its connection string, and then gracefully shut it down using the `mongodb-runner` API.

import { MongoCluster } from 'mongodb-runner'; async function runTest() { let cluster; try { // Start a standalone MongoDB instance cluster = await MongoCluster.start({ topology: 'standalone', version: '6.0.0' // Specify a MongoDB version }); console.log(`MongoDB started: ${cluster.connectionString}`); // Example: Connect with a simple MongoClient (requires 'mongodb' package) // import { MongoClient } from 'mongodb'; // const client = new MongoClient(cluster.connectionString); // await client.connect(); // console.log('Successfully connected to MongoDB!'); // await client.db('test').collection('mycollection').insertOne({ data: 'hello' }); // await client.close(); } catch (error) { console.error('Failed to start or use MongoDB cluster:', error); } finally { if (cluster) { console.log('Stopping MongoDB cluster...'); await cluster.close(); console.log('MongoDB cluster stopped.'); } } } runTest();

mongodb-runner --version

Debug

Known issues

breakingVersion 5.0.0 of `mongodb-runner` was a complete rewrite, introducing significant breaking changes to both the CLI and programmatic API. Existing codebases using versions prior to 5.x will require substantial modifications.

fix

Review the official `mongodb-runner` documentation for version 5 and above to understand the new API and CLI commands. Update import paths, method calls, and configuration options accordingly.

affects: >=5.0.0

gotchaWhen using the CLI, arguments intended for the underlying `mongod` or `mongos` processes must be passed after a `--` separator to distinguish them from `mongodb-runner` options.

fix

Always use `npx mongodb-runner start -t replset -- --setParameter allowDiskUseByDefault=true` where `--setParameter` is for the MongoDB server, and `--port` is for `mongodb-runner`.

affects: >=5.0.0

gotchaRunning `mongodb-runner` can download large MongoDB binary packages, which consume significant disk space and can take time on first use. This behavior can be unexpected in CI/CD environments or environments with limited bandwidth.

fix

To manage download locations, use the `--downloadDir` option. For CI/CD, consider pre-downloading binaries or caching the `--downloadDir` across builds to reduce setup time.

affects: >=1.0.0

gotchaIf `mongodb-runner` instances are not properly shut down, they can leave orphaned processes or files, leading to resource consumption or port conflicts on subsequent runs.

fix

Always ensure `cluster.close()` is called in programmatic usage, ideally within a `finally` block. For CLI usage, use `npx mongodb-runner stop --all` or `npx mongodb-runner stop --id <cluster_id>`.

affects: >=1.0.0

Errors

Common errors & fixes

Error: EADDRINUSE: address already in use :::27017

A MongoDB instance (or another process) is already running on the default port 27017.

fix

Either stop the existing process, or specify a different port for `mongodb-runner` using `npx mongodb-runner start -- --port <new_port>` for CLI, or `await MongoCluster.start({ port: <new_port> })` for programmatic use.

Cannot find package 'mongodb-runner' imported from ...

Attempting to use `mongodb-runner` with `import` syntax in a CommonJS module or an environment not configured for ESM.

fix

Ensure your `package.json` has `"type": "module"` for ESM, or use `require` syntax if you must stick to CommonJS (though ESM is the preferred API for `mongodb-runner` v5+). Alternatively, run your script with `node --experimental-modules your-script.js` if Node.js version is older and doesn't natively support ESM.

TypeError: MongoCluster.start is not a function

Incorrect import of `MongoCluster` or an attempt to use an old API structure after the v5 rewrite.

fix

Ensure you are using `import { MongoCluster } from 'mongodb-runner';` and calling `await MongoCluster.start(...)`. If you are on an older version, consult the documentation for that specific version.

Upgrade

Version history

6.7.7latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/mongodb-js/devtools-shared ↗

packagehttps://www.npmjs.com/package/mongodb-runner ↗

homepagehttps://www.npmjs.com/package/mongodb-runner ↗