Using Dredd as a JavaScript Library

Dredd is an ES module. Import and configure it from your JavaScript code:

import Dredd from '@stacklych/dredd';
const dredd = new Dredd(configuration);

Then you need to run the Dredd testing:

dredd.run(function (err, stats) {
  // err is present if anything went wrong
  // otherwise stats is an object with useful statistics
});

As you can see, dredd.run is a function receiving another function as a callback. Received arguments are err (error if any) and stats (testing statistics) with numbers accumulated throughout the Dredd run.

Configuration Object for Dredd Class

Let’s have a look at an example configuration first. (Please also see the CLI options to read detailed information about the list of available options).

{
  endpoint: 'http://127.0.0.1:3000/api', // your URL to API endpoint the tests will run against
  path: [],         // Required Array if Strings; filepaths to API description documents, can use glob wildcards
  'dry-run': false, // Boolean, do not run any real HTTP transaction
  names: false,     // Boolean, Print Transaction names and finish, similar to dry-run
  loglevel: 'warning', // String, logging level (debug, warning, error, silent)
  only: [],         // Array of Strings, run only transaction that match these names
  header: [],       // Array of Strings, these strings are then added as headers (key:value) to every transaction
  user: null,       // String, Basic Auth credentials in the form username:password
  hookfiles: [],    // Array of Strings, filepaths to files containing hooks (can use glob wildcards)
  reporter: ['dot', 'html'], // Array of possible reporters, see folder lib/reporters
  output: [],       // Array of Strings, filepaths to files used for output of file-based reporters
  'inline-errors': false, // Boolean, If failures/errors are display immediately in Dredd run
  require: null,    // String, When using nodejs hooks, require the given module before executing hooks
  color: true,
  emitter: new EventEmitter(), // listen to test progress, your own instance of EventEmitter
  apiDescriptions: ['FORMAT: 1A\n# Sample API\n']
}

Warning

The usage of nested options key is deprecated. Please list options under the root of the configuration.

Warning

The top-level server property must be replaced by endpoint. Do not confuse with the options –server option, that provides a server running command (i.e. npm start).

configuration

configuration.endpoint

The HTTP(S) address of the API server to test against the API description(s). A valid URL is expected, e.g. http://127.0.0.1:8000

Type:

string

Required:

yes

configuration.path

Array of paths or URLs to API description documents.

Type:

array

Required:

yes

configuration.emitter

Listen to test progress by providing your own instance of EventEmitter.

Type:

EventEmitter

configuration.apiDescriptions

API descriptions as strings. Useful when you don’t want to operate on top of the filesystem.

Type:

array