EphemeralMongo 3.0.0

EphemeralMongo

• About
• Installation
• Usage
• How it works
• MongoDB Enterprise and in-memory storage engine
• Windows Defender Firewall prompt
• Reusing runners across tests
• Changelog

About

EphemeralMongo is a .NET library that provides a simple way to run temporary and disposable MongoDB servers for integration tests and local debugging, without any dependencies or external tools. It is as simple as:

using var runner = await MongoRunner.RunAsync();
Console.WriteLine(runner.ConnectionString);

Use the resulting connection string to access the MongoDB server. It will automatically be stopped and cleaned up when the runner is disposed. You can pass options to customize the server, such as the data directory, port, and replica set configuration. More details can be found in the usage section.

List of features and capabilities:

• Multiple ephemeral and isolated MongoDB databases for running tests.
• A quick way to set up a MongoDB database for a local development environment.
• Access to MongoDB 6, 7, and 8.
• Access to MongoDB Community and Enterprise editions.
• Support for single-node replica sets, enabling transactions and change streams.
• mongoexport and mongoimport tools for exporting and importing collections.
• Support for .NET Standard 2.0, .NET Standard 2.1, .NET 8.0 and later.
• Support for Linux, macOS, and Windows.
• Supports MongoDB C# driver version 2.x and 3.x.

This project follows in the footsteps of Mongo2Go and expands upon its foundation.

Installation

Package	Description
	Install this package if you use MongoDB C# driver version 3.x.
	Install this package if you use MongoDB C# driver version 2.x.

Usage

Use MongoRunner.RunAsync() or MongoRunner.Run() methods to create a disposable instance that provides access to a MongoDB connection string, import, and export tools. An optional MongoRunnerOptions parameter can be provided to customize the MongoDB server.

// All the following properties are OPTIONAL.
var options = new MongoRunnerOptions
{
    // The desired MongoDB version to download and use.
    // Possible values are V6, V7 and V8. Default is V8.
    Version = MongoVersion.V8,

    // The desired MongoDB edition to download and use.
    // Possible values are Community and Enterprise. Default is Community.
    Edition = MongoEdition.Community,

    // If true, the MongoDB server will run as a single-node replica set. Default is false.
    UseSingleNodeReplicaSet = true,

    // Additional arguments to pass to the MongoDB server. Default is null.
    AdditionalArguments = ["--quiet"],

    // The port on which the MongoDB server will listen.
    // Default is null, which means a random available port will be assigned.
    MongoPort = 27017,

    // The directory where the MongoDB server will store its data.
    // Default is null, which means a temporary directory will be created.
    DataDirectory = "/path/to/data/",

    // Provide your own MongoDB binaries in this directory.
    // Default is null, which means the library will download them automatically.
    BinaryDirectory = "/path/to/mongo/bin/",

    // A delegate that receives the MongoDB server's standard output.
    StandardOutputLogger = Console.WriteLine,

    // A delegate that receives the MongoDB server's standard error output.
    StandardErrorLogger = Console.WriteLine,

    // Timeout for the MongoDB server to start. Default is 30 seconds.
    ConnectionTimeout = TimeSpan.FromSeconds(10),

    // Timeout for the replica set to be initialized. Default is 10 seconds.
    ReplicaSetSetupTimeout = TimeSpan.FromSeconds(5),

    // The duration for which temporary data directories will be kept.
    // Ignored when you provide your own data directory. Default is 12 hours.
    DataDirectoryLifetime = TimeSpan.FromDays(1),

    // Override this property to provide your own HTTP transport.
    // Useful when behind a proxy or firewall. Default is a shared reusable instance.
    Transport = new HttpTransport(new HttpClient()),

    // Delay before checking for a new version of the MongoDB server. Default is 1 day.
    NewVersionCheckTimeout = TimeSpan.FromDays(2)
};

// Disposing the runner will kill the MongoDB process (mongod) and delete the associated data directory
using (await var runner = MongoRunner.RunAsync(options))
{
    var database = new MongoClient(runner.ConnectionString).GetDatabase("default");

    // Do something with the database
    database.CreateCollection("people");

    // Export a collection to a file. A synchronous version is also available.
    await runner.ExportAsync("default", "people", "/path/to/default.json");

    // Import a collection from a file. A synchronous version is also available.
    await runner.ImportAsync("default", "people", "/path/to/default.json");
}

How it works

• At runtime, the MongoDB binaries (mongod, mongoimport, and mongoexport) are downloaded when needed (if not already present) and extracted to your local application data directory.
• Official download links are retrieved from this JSON file for the server and this JSON file for the tools.
• SHA256 checksums are used to verify the integrity of the downloaded files.
• MongoRunner.Run or MongoRunner.RunAsync always starts a new mongod process with a random available port.
• The resulting connection string will depend on your options (UseSingleNodeReplicaSet).
• By default, a unique temporary data directory is used and deleted when the runner is disposed.

MongoDB Enterprise and in-memory storage engine

Make sure you are allowed to use MongoDB Enterprise binaries in your projects. The official download page states:

MongoDB Enterprise Server is also available free of charge for evaluation and development purposes.

The Enterprise edition provides access to the in-memory storage engine, which is faster and more efficient for tests:

var options = new MongoRunnerOptions
{
    Edition = MongoEdition.Enterprise,
    AdditionalArguments = ["--storageEngine", "inMemory"],
};

using var runner = await MongoRunner.RunAsync(options);
// [...]

Windows Defender Firewall prompt

On Windows, you might get a Windows Defender Firewall prompt. This is because EphemeralMongo starts the mongod.exe process from your local app data directory, and mongod.exe tries to open an available port.

Reusing runners across tests

Avoid calling MongoRunner.Run or MongoRunner.RunAsync concurrently, as this will create many mongod processes and make your operating system slower. Instead, try to use a single instance and reuse it - create as many databases as you need, one per test, for example.

For this, version 3.0.0 introduces a new experimental PooledMongoRunner class. Once created, you can rent and return MongoRunner instances. Once rented a certain number of times, new instances will be created. This way, mongod processes will be reused, but not too often. This will avoid uncontrolled usage of system resources.

var options = new MongoRunnerOptions
{
    Version = MongoVersion.V7,
    UseSingleNodeReplicaSet = true
};

using var pool = new MongoRunnerPool(options);

var runner1 = await pool.RentAsync();
var runner2 = await pool.RentAsync();

try
{
    // Same connection string, same mongod process
    Console.WriteLine(runner1.ConnectionString);
    Console.WriteLine(runner2.ConnectionString);
}
finally
{
    pool.Return(runner1);
    pool.Return(runner2);
}

// This is a new mongod process
var runner3 = await pool.RentAsync();

Changelog

3.0.0

See this announcement.

2.0.0

• Breaking change: Support for MongoDB 5.0 and 6.0 has been removed, as their end-of-life has passed.
• Breaking change: arm64 is now the default target for macOS. The previous target was x64.
• Breaking change: The Linux runtime package now uses Ubuntu 22.04's MongoDB binaries instead of the 18.04 ones. OpenSSL 3.0 is now required.
• Breaking change: Updated the MongoDB C# driver to 2.28.0, which now uses strong-named assemblies.
• Added support for MongoDB 8.0.
• Introduced data directory management to delete old data directories automatically.
• Use direct connection in replica set connection strings.
• Fixed the spelling issue in MongoRunnerOptions.StandardOutputLogger.