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
    }
  }
}