Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time

Using Dredd as a JavaScript Library

Dredd can be used directly from your JavaScript code. First, import and configure Dredd:

var Dredd = require('dredd');
var dredd = new Dredd(configuration);

Then you need to run the Dredd testing: (err, stats) {
  // err is present if anything went wrong
  // otherwise stats is an object with useful statistics

As you can see, 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 :ref:`CLI options <usage-cli>` to read detailed information about the list of available options).

  endpoint: '', // 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']


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


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).

.. js:data:: configuration

.. js:attribute:: configuration.endpoint

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

   :type: string
   :required: yes

.. js:attribute:: configuration.path

   Array of paths or URLs to API description documents.

   :type: array
   :required: yes

.. js:attribute:: configuration.emitter

   Listen to test progress by providing your own instance of `EventEmitter <>`__.

   :type: EventEmitter

.. js:attribute:: configuration.apiDescriptions

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

   :type: array