dredd

library14.1.0jsnpmunverified

Dredd is an HTTP API testing framework designed to validate API description documents, such as OpenAPI (formerly Swagger) and API Blueprint, against a running backend API. It ensures that the API implementation adheres to its documented contract by generating requests based on the specification and comparing the actual responses to the described expectations. The current stable version is 14.1.0, with ongoing development and a release cadence that includes major version updates for parser improvements, schema validation, and dependency management. Dredd's key differentiators include its strong focus on documentation-driven testing, support for various API description formats, and its extensible hook system. This hook system allows developers to write custom test logic in multiple languages (including Node.js), enabling advanced scenarios like authentication, data setup, and cleanup, making it a valuable tool for integration into CI/CD pipelines for continuous contract compliance.

testing http-networking devops

npm install dredd

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DREDD

dredd

testingjavascriptv14.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Dredd

✓ import Dredd from 'dredd';

✗ const Dredd = require('dredd').Dredd;

Used for programmatic integration to instantiate the Dredd testing engine. Since Dredd ships TypeScript definitions, prefer ESM imports for modern Node.js/TypeScript projects.

Dredd CLI

✓ npx dredd

✗ node node_modules/dredd

Dredd is primarily a command-line interface (CLI) tool. `npx` is the recommended way to run it without global installation. If globally installed, `dredd` can be run directly.

Transaction

✓ import type { Transaction } from 'dredd';

Type definition for the HTTP transaction object, useful when writing Dredd hooks in TypeScript to ensure type safety when modifying requests or responses.

This quickstart demonstrates how to set up Dredd to test a simple Express.js API against an OpenAPI 3.0 specification. It includes the API description, the API server code, Dredd's configuration file, and the command to execute the tests.

{ // openapi.yaml (or .json, .apib) "openapi": "3.0.0", "info": { "title": "Example API", "version": "1.0.0" }, "paths": { "/message": { "get": { "summary": "Get a greeting message", "responses": { "200": { "description": "A greeting message", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Hello from Dredd!" } } } } } } } } } } } // app.js (Example API Backend) const express = require('express'); const app = express(); const port = 3000; app.get('/message', (req, res) => { res.json({ message: 'Hello from Dredd!' }); }); app.listen(port, () => { console.log(`Example API listening at http://localhost:${port}`); }); // dredd.yml (Dredd Configuration) # Replace 'openapi.yaml' with your API description file name blueprint: openapi.yaml server: 'node app.js' endpoint: 'http://localhost:3000' language: nodejs // Terminal Commands // 1. Install Dredd (if not already globally installed) // npm install -g dredd // 2. Create the openapi.yaml and app.js files as above. // 3. (Optional) Run dredd init to create a dredd.yml, then customize it. // dredd init // 4. Run Dredd tests npx dredd

dredd --version

Debug

Known issues

breakingDredd v13.0.0 removed support for JSON Schema Draft V3.

fix

Update your API description documents to use JSON Schema Draft V4 or newer (Draft 6 or Draft 7 are also supported).

affects: >=13.0.0

deprecatedUsage of JSON Schema Draft V3 in API description documents will trigger a deprecation warning.

fix

Migrate your API description documents to JSON Schema Draft V4 or newer to avoid future breaking changes.

affects: >=12.2.0 <13.0.0

gotchaJSON Schema generated from OpenAPI 2.0 (Swagger) documents is explicitly set to JSON Schema Draft V4 by Dredd.

fix

Be aware that even if your OpenAPI 2.0 document implies an older JSON Schema draft, Dredd will validate against Draft V4. Adjust your expectations or manually specify a newer draft in your schema if possible.

affects: >=12.2.1

gotchaFor stability in CI environments, it is recommended to pin Dredd to a specific version.

fix

Use `npm install dredd@stable` or `npm install dredd@<version>` (e.g., `npm install dredd@14`) in your CI configuration to ensure consistent test runs.

affects: >=1.0.0

gotchaBy default, Dredd only tests responses with 2xx status codes. Responses with other status codes are skipped.

fix

To test non-2xx responses, you must explicitly activate them using Dredd hooks. Refer to the 'Multiple Requests and Responses' how-to guide in the Dredd documentation.

affects: >=1.0.0

Errors

Common errors & fixes

error: No matching transactions were found.

Dredd could not find any API endpoints in the provided API description document that matched the configured filters or existed.

fix

Ensure your `blueprint` or `path` in `dredd.yml` points to a valid API description file (OpenAPI/API Blueprint). Verify the API description document contains valid paths and operations. Use `dredd --names` to list detected transactions and debug path matching.

Error: ENOENT: no such file or directory, stat 'path/to/hookfile.js'

Dredd failed to load one or more specified hook files because the file path was incorrect or the file did not exist.

fix

Double-check the `hookfiles` path in your `dredd.yml` configuration or the `--hookfiles` CLI option. Ensure the file exists and the path is correct relative to where you are running Dredd.

error: Failed to parse API description document.

Your API description document (OpenAPI, API Blueprint) contains syntax errors or is malformed, preventing Dredd from processing it.

fix

Use a linter or validator for your specific API description format (e.g., `swagger-cli validate <file>` for OpenAPI or an API Blueprint linter) to identify and fix syntax errors in your document.

Upgrade

Version history

14.1.0latest on npm

Audit

Dependencies

dredd-transactionsrequiredCore dependency for managing and processing HTTP transactions during tests, often updated with Dredd itself.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/apiaryio/dredd ↗

packagehttps://www.npmjs.com/package/dredd ↗

homepagehttps://dredd.org ↗