Setup and tear down test fixtures with MongoDB.
Branch: master
Clone or download
Latest commit d1def56 Feb 17, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets logo Nov 6, 2018
bin add re example Aug 6, 2018
examples add filtering to example Aug 8, 2018
lib drop collection on unload Jan 25, 2019
.eslintrc.json initial version Jul 18, 2017
.gitignore initial version Jul 18, 2017
LICENSE initial version Jul 18, 2017
README.md Fix typo in README.md Feb 4, 2019
index.js initial version Jul 18, 2017
package-lock.json update deps Feb 18, 2019
package.json update deps Feb 18, 2019

README.md

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

  1. Clone the repo
git clone https://github.com/cdimascio/node-mongodb-fixtures && cd node-mongodb-fixtures && npm install`
  1. Load the fixtures into MongoDb
node bin/mongodb-fixtures load -u mongodb://localhost:27017/mydb --path ./examples/fixtures

Create fixtures

How

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

JSON Files

The name of the JSON file is becomes 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 becomes collection name. Each .js or .ts files 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.

var ObjectId = require('mongodb').ObjectID;

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

  1. Create a new JavaScript file with an underscore _ suffix. e.g. people_.js.
  2. The _ denotes a script. The text preceding it, people, is the collection name.
  3. Each script is passed a single argument, the collection.
  4. 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