node-mongodb-fixtures

Setup and tear down test fixtures with MongoDB.

Use custom scripts to create indexes and more!

Install

npm install node-mongodb-fixtures

CLI

For CLI use, it can be useful to install globally:

npm install node-mongodb-fixtures -g

Usage

Programmatic

const Fixtures = require('node-mongodb-fixtures');
const fixtures = new Fixtures();

fixtures
  .connect('mongodb://localhost:27017/mydb')
  .then(() => fixtures.unload())
  .then(() => fixtures.load())
  .then(() => fixtures.disconnect());

See detailed programmatic usage below

CLI

❯ mongodb-fixtures load -u mongodb://localhost:27017/mydb

See detailed cli usage below

Try the Example

The following example will load the example fixtures into a locally running MongoDB. To use another DB modify the the connection url accordingly (in step 2)

Run the example

Clone the repo

git clone https://github.com/cdimascio/node-mongodb-fixtures && cd node-mongodb-fixtures && npm install

Load the fixtures into MongoDb

node bin/mongodb-fixtures load -u mongodb://localhost:27017/mydb --path ./examples/fixtures

Create fixtures

How

Choose a directory for your fixtures e.g. ./fixtures
Create any mix of JSON (.json), JavaScript (.js) files. (see file rules below)
Each filename defines a MongoDB collection

JSON Files

The name of the JSON file is/will be the collection name. Each JSON file must contain a 'JSON Array of JSON objects'. Each JSON object is loaded as a document in the collection.

JSON files are useful when you can represent all of your documents as JSON.

[
  { "name": "Paul", "age": 36 }, 
  { "name": "Phoebe", "age": 26 }
]

JavaScript Files

The name of the JSON file is/will be the collection name. Each .js file must return a 'JSON Array of JSON objects'. Each JSON object is loaded as a document in the collection.

JavaScript files are useful when you require code to represent your documents.

const { ObjectID: ObjectId } = require('mongodb');

module.exports = [
  { _id: ObjectId(), name: 'Paul', 'age': 36 },
  { _id: ObjectId(), name: 'Phoebe', 'age': 26 },
];

Example Structure

fixtures/
|-- people.js
|-- places.json

See ./examples/fixtures

Collection Scripts: Indexes and more...

"Collection scripts" enable you to inject your own custom logic in the fixture creation lifecycle. Each custom script is passed a reference to a MongoDB collection. You may use this reference to modify the collection however you like. For example, you can add indexes and more.

How

Create a new JavaScript file with an underscore _ suffix. e.g. people_.js.
The _ denotes a script. The text preceding it, people, is the collection name.
Each script is passed a single argument, the collection.
Each must return a function that takes a collection and returns a Promise.

Example

// people_.js
module.exports = function(collection) {
  // Write your custom logic and return a promise
  return collection.createIndex( { "address.city": 1 }, { unique: false } );
}

fixtures/
|-- people_.js
|-- people.js
|-- places.json

Note: Custom scripts run after all fixtures have completed.

Programmatic Usage

Init

use the default fixtures directory,./fixtures

const Fixtures = require('node-mongodb-fixtures');
const fixtures = new Fixtures();

or specifiy the fixtures directory

const Fixtures = require('node-mongodb-fixtures');
const fixtures = new Fixtures({
  dir: 'examples/fixtures',
  mute: false, // do not mute the log output
});

or filter the fixtures present in the directory with a Regex pattern

const Fixtures = require('node-mongodb-fixtures');
const fixtures = new Fixtures({
  dir: 'examples/fixtures',
  filter: 'people.*',
});

Connect

Use the standard MongoDB URI connection scheme

fixtures.connect('mongodb://localhost:27017/mydb'); // returns a promise

connect(uri, options, dbName)

arg	type	description
`uri`	string (required)	MongoDB connection string
`options`	object (optional)	MongoDB connection options
`dbName`	string (optional)	identifies a database to switch to. Useful when the db in the connection string differs from the db you want to connect to

See: ./examples/ex1.js

Load

fixtures.load(); // returns a promise

Unload

fixtures.unload(); // returns a promise

Disconnect

fixtures.disconnect(); // returns a promise

Example

The following example does the following:

connects to mongo
then unloads all fixtures
then loads all fixtures
then disconnects

const Fixtures = require('node-mongodb-fixtures');
const uri = 'mongodb://localhost/mydb';
const options = null;

const fixtures = new Fixtures({
  dir: 'examples/fixtures',
  filter: '.*',
});

fixtures
  .connect('mongodb://localhost:27017/mydb')
  .then(() => fixtures.unload())
  .then(() => fixtures.load())
  .catch(e => console.error(e))
  .finally(() => fixtures.disconnect());

CLI Usage

❯ mongodb-fixtures

  Usage: mongodb-fixtures [options] [command]


  Options:

    -V, --version         output the version number
    -u --url <url>        mongo connection string
    -s --ssl              use SSL
    -d --db_name <name>   database name
    -n --ssl_novalidate   use SSL with no verification
    -c --ssl_ca </path/to/cert>  path to cert
    -p --path <path>      resource path. Default ./fixtures
    -f --filter <pattern> regex pattern to filter fixture names
    -b --verbose          verbose logs
    -h, --help            output usage information


  Commands:

    load
    unload
    rebuild

Example Output

[info ] Using fixtures directory: /Users/dimascio/git/node-mongodb-fixtures/examples/fixtures
[info ] Using database mydb
[info ] No filtering in use
[start] load people
[start] load places
[done ] load people
[done ] load places
[done ] *load all
[start] script people_.js
[done ] script people_.js
[done ] *script all

Contributors

Contributors are welcome!

Special thanks to those who have contributed:

License

MIT