DADI API Testbed

Overview

This module creates test data and inserts it into an instance of DADI API.

API reference

constructor(options)

Initialises a new instance of the testbed. Takes an options object with the following parameters.

Option	Description	Default	Required
abortOnError	Shows an error message and terminates the process when an error occurs	false	No
batchSize	The number of documents to include in a batch when inserting into API	50	No
clientId	The API client ID	N/A	Yes
clientSecret	The API client secret	N/A	Yes
port	The API port	80	No
uri	The API URI, including protocol (e.g. http://api.somedomain.tech)	N/A	Yes

Example:

const Testbed = require('@dadi/api-testbed')

const myTest = new Testbed({
  clientId: 'testClient',
  clientSecret: 'superSecret'
  port: 4050,
  uri: 'http://localhost'
})

addData(options)

Adds a series of documents to a given collection. Takes an options object with the following parameters.

Option	Description	Default	Required
cleanup	Whether to delete all documents from the collection before starting the insertion	true	No
collection	The name of the collection	'articles'	Yes
count	The number of documents to insert	1	No
property	The name of the property	'example'	Yes
fields	The fields schema	See Specifying fields	Yes
key	A unique key for isolating this operation in the performance report (see Measuring performance)	'main'	No

Example:

await myTest.addData({
  collection: 'users',
  property: 'example',
  count: 5000,
  fields: {
    name: {
      format: '{{name.firstName}} {{name.lastName}}',
      transform: value => `Mr. ${value}`
    },
    profileImage: {
      reference: {
        mediaBucket: 'mediaStore'
      }
    }
  }
})

addMedia(options)

Creates a series of images and uploads them to a given media bucket. Takes an options object with the following parameters.

Option	Description	Default	Required
bucket	The name of the media bucket	'mediaStore'	No
count	The number of media documents to insert	1	No
height	The height of the images	100	No
key	A unique key for isolating this operation in the performance report (see Measuring performance)	'main'	No
width	The width of the images	100	No

Example:

await myTest.addMedia({
  bucket: 'mediaStore',
  count: 20,
  height: 300,
  width: 450
})

addReferenceData(options)

Adds an array of identifiers for existing data so that your test data can reference data already in the database.

Option	Description	Default	Required
collection	The name of the collection	none	Yes
ids	An array of document identifiers for the collection	Yes

Example:

const dataRecords = getDataFromAPI('collectionName')

myTest.addReferenceData({
  collection: 'collectionName',
  ids: dataRecords.map(item => item._id)
})

getPerformanceData(options)

Gets performance data for the set of operations performed. See Measuring performance.

await myTest.run({
  body: {
    name: 'New name'
  },
  method: 'put',
  uri: '/vjoin/example/users/123456'
})

run(options)

Runs a query against any RESTful endpoint, returning results and measuring the time it took for the request to be processed. Takes an options object with the following parameters.

Option	Description	Default	Required
body	Request body as an object	null	No
key	A unique key for isolating this operation in the performance report (see Measuring performance)	'main'	No
method	HTTP verb	'get'	No
uri	Relative URI for the RESTful endpoint	N/A	Yes

Example:

const { results } = await myTest.run({
  body: {
    name: 'New name'
  },
  method: 'put',
  uri: '/vjoin/example/users/123456'
})

Specifying fields

This module allows you to specify exactly the format of the data that is inserted into API – choosing the data types, asking for people's names or establishing references between collections are just some of the options supported.

To configure this, the addData method accepts a fields object, mapping field names to objects that define their content. In those objects, the following properties are accepted.

Option	Description	Example
format	A placeholder string supported by faker	'{{name.firstName}} {{name.lastName}}'
reference	An object for establishing a connection with another collection (via a collection property) or media bucket (using mediaBucket). It chooses a random document from the referenced resource as the value for the field.	'{ collection: "books" }
transform	A callback function that transforms the value attributed to the field by any other option (e.g. does further transformations to a value created with the format option)	value => \Mr. ${value}``

Example:

The following function call inserts into the vjoin/example/books collection 5000 documents, each with two fields: name containing one sentence of lorem ipsum, and author containing the ID of a random document from the users collection (which would need to be inserted prior to this call).

await myTest.addData({
  collection: 'books',
  property: 'example',
  count: 5000,
  fields: {
    name: {
      format: '{{lorem.sentences(1)}}'
    },
    author: {
      reference: {
        collection: 'users'
      }
    }
  }
})

Adding multiple referenced or media documents

The above examples all show how to assign a single referenced document or media item to a field. To assign multiple documents from a collection, or to assign documents from multiple collections, an array can be passed as the value for collection or mediaBucket. Each array item should specify a collection or mediaBucket, and a count property to indicate how many documents to assign to the field.

Example:

The following function call inserts into the vjoin/example/books collection 5000 documents, each with two fields: name containing one sentence of lorem ipsum, and tags containing five IDs of random documents from the tags collection (which would need to be inserted prior to this call).

await myTest.addData({
  collection: 'books',
  property: 'example',
  count: 5000,
  fields: {
    name: {
      format: '{{lorem.sentences(1)}}'
    },
    tags: {
      reference: {
        collection: [
          {
            collection: 'tags',
            count: 5
          }
        ]
      }
    }
  }
})

Example:

The following function call inserts into the vjoin/example/books collection 5000 documents, each with two fields: name containing one sentence of lorem ipsum, and sections. sections would contain two IDs from the textOnly collection, followed by one ID from the images collection and finally two more IDs from the textOnly collection.

await myTest.addData({
  collection: 'books',
  property: 'example',
  count: 5000,
  fields: {
    name: {
      format: '{{lorem.sentences(1)}}'
    },
    sections: {
      reference: {
        collection: [
          {
            collection: 'textOnly',
            count: 2
          },
          {
            collection: 'images',
            count: 1
          },
          {
            collection: 'textOnly',
            count: 2
          }
        ]
      }
    }
  }
})

Working with references

In the current version of this module, data needs to be inserted in the correct order for references to work. For example, in a scenario where collection B references collection A, the addData call to collection A would need to take place before the call on collection B. This limitation will be addressed in future releases.

Measuring performance

An internal performance monitor keeps track of the time it takes for each operation to complete. Time is measured in millseconds with sub-millisecond resolution. For each operation, the total runtime is calculated, as well as the number of requests that fall under the 50, 65, 75, 80, 90, 95, 98, and 99 percentiles (similarly to Apache Bench).

Example:

{
  "main": {
    "total": 6011.073279999996,
    "percentiles": {
      "50": 28.932340000000295,
      "65": 30.04501300000038,
      "75": 31.299869999999828,
      "80": 31.5112180000001,
      "90": 33.64954899999975,
      "95": 36.37320799999998,
      "98": 65.03318399999989,
      "99": 142.1427430000001,
      "100": 2882.7424
    }
  }
}

This data is grouped by operations with the same key parameter – e.g. if you call addMedia(), addData() and run() with the same key (or with no key, which is the same as using the default main), performance data for all the resulting requests will be displayed as a single group. If you supply different keys to some operations, their performance data will be shown as a new group.

Example:

{
  "main": {
    "total": 6011.073279999996,
    "percentiles": {
      "50": 28.932340000000295,
      "65": 30.04501300000038,
      "75": 31.299869999999828,
      "80": 31.5112180000001,
      "90": 33.64954899999975,
      "95": 36.37320799999998,
      "98": 65.03318399999989,
      "99": 142.1427430000001,
      "100": 2882.7424
    }
  },
  "add books": {
    "total": 6.8522460000003775,
    "percentiles": {
      "50": 6.8522460000003775,
      "65": 6.8522460000003775,
      "75": 6.8522460000003775,
      "80": 6.8522460000003775,
      "90": 6.8522460000003775,
      "95": 6.8522460000003775,
      "98": 6.8522460000003775,
      "99": 6.8522460000003775,
      "100": 6.8522460000003775
    }
  }
}