Skip to content

Latest commit

 

History

History
336 lines (244 loc) · 12.6 KB

JSDOC.md

File metadata and controls

336 lines (244 loc) · 12.6 KB
Raw

JSDoc for mongodb-sandbox

Launch a stand-alone MongoDB Topology for use within a Test Suite.

Examples

mongodb-sandbox is Promise-based API.

Embed a Lifecycle into the mocha Test Framework, backed by a MongoDB 3.4.2 Sandbox.

A variant of this Example, as well as examples for other Test Frameworks, can be found in the README.

const { createSandbox } = require('mongodb-sandbox');

const sandbox = createSandbox({
  version: '3.4.2',
});

before(function() {
  const lifecycle = sandbox.lifecycle(this);

  before(lifecycle.beforeAll);
  beforeEach(lifecycle.beforeEach);
  afterEach(lifecycle.afterEach);
  after(lifecycle.afterAll);
});

Programatically create, start and stop a MongoDB 3.6.8 Sandbox

const { createSandbox } = require('mongodb-sandbox');

const sandbox = createSandbox({
  version: '3.6.8',
});

sandbox.start()
.then(() => {
  // use it in some fashion

  // and when you're done,
  return sandbox.stop();
});

A script to install the latest version of MongoDB to back a Sandbox, out-of-band from your Test Suite.

#!/usr/bin/env node
const { installSandbox } = require('mongodb-sandbox');

installSandbox()
.then((sandbox) => {
  console.log('installed the latest version of MongoDB.');
});

Options

Configuration properties are documented in Sandbox.options.

In addition to the properties a Sandbox recognizes, the you may provide any options passed to a MongoDBDownload instance (from the mongodb-download module).

Several useful properties are:

  • version - a specific MongoDB version, eg. '3.4.2'; default = 'latest'
  • downloadDir - the directory where the MongoDB binaries will be downloaded & installed. default = a cache local to the mongodb-sandbox module.

Classes

Lifecycle

A simple encapsulation of methods for a Test Framework lifecycle.

Sandbox

A Sandbox that launches a stand-alone MongoDB Topology for use within a Test Suite.

Functions

createSandbox() ⇒ Sandbox

A Factory method for a Sandbox.

installSandbox() ⇒ Promise.<Sandbox>

Installs MongoDB support for a Sandbox.

Lifecycle

A simple encapsulation of methods for a Test Framework lifecycle.

Kind: global class
Params: Sandbox sandbox
Params: Object [context] an instance of the Test Framework context

lifecycle.sandbox

The Sandbox passed to the constructor.

Kind: instance property of Lifecycle
Properties

lifecycle.context

The Test Framework context passed to the constructor.

Kind: instance property of Lifecycle
Properties

  • Object

lifecycle.beforeAll() ⇒ Promise.<Lifecycle>

To be invoked at the start of the global Test Framework lifecycle.

Kind: instance method of Lifecycle
Returns: Promise.<Lifecycle> - a Promise resolving this
Params: Object [context] an instance of the Test Framework context

lifecycle.beforeEach() ⇒ Promise.<Lifecycle>

To be invoked at the start of each individual case in the Test Framework lifecycle.

Kind: instance method of Lifecycle
Returns: Promise.<Lifecycle> - a Promise resolving this
Params: Object [context] an instance of the Test Framework context

lifecycle.afterEach() ⇒ Promise.<Lifecycle>

To be invoked at the end of each individual case in the Test Framework lifecycle.

Kind: instance method of Lifecycle
Returns: Promise.<Lifecycle> - a Promise resolving this
Params: Object [context] an instance of the Test Framework context

lifecycle.afterAll() ⇒ Promise.<Lifecycle>

To be invoked at the end of the global Test Framework lifecycle.

Kind: instance method of Lifecycle
Returns: Promise.<Lifecycle> - a Promise resolving this
Params: Object [context] an instance of the Test Framework context

Sandbox

A Sandbox that launches a stand-alone MongoDB Topology for use within a Test Suite.

Kind: global class
Params: options [options] Sandbox configuration options

sandbox.options

The configuration options passed to the constructor.

Kind: instance property of Sandbox
Properties

sandbox.isRunning : Boolean

true if the Sandbox is running.

Kind: instance property of Sandbox

sandbox.config : config

Configuration properties for connecting to the MongoDB Topology backing a running Sandbox.

Kind: instance property of Sandbox
Throws:

  • Error if the Sandbox is not running.

sandbox.start() ⇒ Promise.<Sandbox>

Kind: instance method of Sandbox
Returns: Promise.<Sandbox> - a Promise resolving this

sandbox.stop() ⇒ Promise.<Sandbox>

Kind: instance method of Sandbox
Returns: Promise.<Sandbox> - a Promise resolving this

sandbox.install() ⇒ Promise.<Sandbox>

Install a version of MongoDB.

Kind: instance method of Sandbox
Returns: Promise.<Sandbox> - a Promise resolving this
See: mongodb-download

sandbox.hasDocuments() ⇒ Promise.<Boolean>

Kind: instance method of Sandbox
Returns: Promise.<Boolean> - a Promise resolving true if the Sandbox contains any Documents.

sandbox.purgeDocuments() ⇒ Promise.<Sandbox>

Delete all Documents from the Sandbox.

Kind: instance method of Sandbox
Returns: Promise.<Sandbox> - a Promise resolving this

sandbox.lifecycle() ⇒ Promise.<Lifecycle>

Kind: instance method of Sandbox
Returns: Promise.<Lifecycle> - a Promise resolving a Lifecycle instance.
Params: Object [context] an instance of the Test Framework context

sandbox.client() ⇒ Promise.<MongoClient>

Kind: instance method of Sandbox
Returns: Promise.<MongoClient> - a Promise resolving a singleton MongoDB Client connected to the Sandbox.
See: newClient

sandbox.newClient() ⇒ Promise.<MongoClient>

The Connections backing all returned Clients will be closed automatically upon #stop.

Kind: instance method of Sandbox
Returns: Promise.<MongoClient> - a Promise resolving a MongoDB Client connected to the Sandbox.

Sandbox.options : Object

Options for constructing a Sandbox.

Beyond the properties called out below, you may provide any options passed to a MongoDBDownload instance from the mongodb-download module, eg. { version, downloadDir }, etc.

Kind: static typedef of Sandbox
See: Options
Properties

  • host String - an alternate bind_ip for the mongod Daemon, eg. '0.0.0.0'; default = 127.0.0.1
  • basePort Number - where to start looking for an available local port; default = 27017 (MongoDB standard)
  • database String - the Database name to use in the Test Suite; default = 'mongodb-sandbox'
  • minimumUptimeMs Number - the minimum amount of time that the Topology should be left running, in milliseconds; default = 0ms

Sandbox.config : Object

Configuration available from a running Sandbox.

port is not exposed at the top level; rather, it is exposed from the mongod option entries within daemons.

Kind: static typedef of Sandbox
Properties

  • url String - a MongoDB connection URL for the MongoDB Topology
  • host String - the host where the Sandbox is listening
  • database String - the name of the Sandbox database to be used for testing
  • downloadDir String - the directory where the MongoDB binaries have been installed
  • daemons Array.<Object> - an Array of mongod daemon options, one for each MongoDB Server which backs the Sandbox, providing (at least) { bind_ip, port, dbpath, url }

createSandbox() ⇒ Sandbox

A Factory method for a Sandbox.

Kind: global function
Returns: Sandbox - a MongoDB Sandbox instance
Params: options [options] Sandbox configuration options

installSandbox() ⇒ Promise.<Sandbox>

Installs MongoDB support for a Sandbox.

Kind: global function
Returns: Promise.<Sandbox> - a Promise resolving a Sandbox instance which has been installed.
Params: options [options] Sandbox configuration options