{"id":13089,"library":"dredd","title":"Dredd HTTP API Testing Framework","description":"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.","status":"active","version":"14.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/apiaryio/dredd","tags":["javascript","api","test","testing","documenation","integration","acceptance"],"install":[{"cmd":"npm install dredd","lang":"bash","label":"npm"},{"cmd":"yarn add dredd","lang":"bash","label":"yarn"},{"cmd":"pnpm add dredd","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for managing and processing HTTP transactions during tests, often updated with Dredd itself.","package":"dredd-transactions","optional":false}],"imports":[{"note":"Used for programmatic integration to instantiate the Dredd testing engine. Since Dredd ships TypeScript definitions, prefer ESM imports for modern Node.js/TypeScript projects.","wrong":"const Dredd = require('dredd').Dredd;","symbol":"Dredd","correct":"import Dredd from 'dredd';"},{"note":"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.","wrong":"node node_modules/dredd","symbol":"Dredd CLI","correct":"npx dredd"},{"note":"Type definition for the HTTP transaction object, useful when writing Dredd hooks in TypeScript to ensure type safety when modifying requests or responses.","symbol":"Transaction","correct":"import type { Transaction } from 'dredd';"}],"quickstart":{"code":"{\n  // openapi.yaml (or .json, .apib)\n  \"openapi\": \"3.0.0\",\n  \"info\": {\n    \"title\": \"Example API\",\n    \"version\": \"1.0.0\"\n  },\n  \"paths\": {\n    \"/message\": {\n      \"get\": {\n        \"summary\": \"Get a greeting message\",\n        \"responses\": {\n          \"200\": {\n            \"description\": \"A greeting message\",\n            \"content\": {\n              \"application/json\": {\n                \"schema\": {\n                  \"type\": \"object\",\n                  \"properties\": {\n                    \"message\": {\n                      \"type\": \"string\",\n                      \"example\": \"Hello from Dredd!\"\n                    }\n                  }\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n}\n\n// app.js (Example API Backend)\nconst express = require('express');\nconst app = express();\nconst port = 3000;\n\napp.get('/message', (req, res) => {\n  res.json({ message: 'Hello from Dredd!' });\n});\n\napp.listen(port, () => {\n  console.log(`Example API listening at http://localhost:${port}`);\n});\n\n// dredd.yml (Dredd Configuration)\n# Replace 'openapi.yaml' with your API description file name\nblueprint: openapi.yaml\nserver: 'node app.js'\nendpoint: 'http://localhost:3000'\nlanguage: nodejs\n\n// Terminal Commands\n// 1. Install Dredd (if not already globally installed)\n// npm install -g dredd\n\n// 2. Create the openapi.yaml and app.js files as above.\n\n// 3. (Optional) Run dredd init to create a dredd.yml, then customize it.\n// dredd init\n\n// 4. Run Dredd tests\nnpx dredd\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Update your API description documents to use JSON Schema Draft V4 or newer (Draft 6 or Draft 7 are also supported).","message":"Dredd v13.0.0 removed support for JSON Schema Draft V3.","severity":"breaking","affected_versions":">=13.0.0"},{"fix":"Migrate your API description documents to JSON Schema Draft V4 or newer to avoid future breaking changes.","message":"Usage of JSON Schema Draft V3 in API description documents will trigger a deprecation warning.","severity":"deprecated","affected_versions":">=12.2.0 <13.0.0"},{"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.","message":"JSON Schema generated from OpenAPI 2.0 (Swagger) documents is explicitly set to JSON Schema Draft V4 by Dredd.","severity":"gotcha","affected_versions":">=12.2.1"},{"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.","message":"For stability in CI environments, it is recommended to pin Dredd to a specific version.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"By default, Dredd only tests responses with 2xx status codes. Responses with other status codes are skipped.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Dredd could not find any API endpoints in the provided API description document that matched the configured filters or existed.","error":"error: No matching transactions were found."},{"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.","cause":"Dredd failed to load one or more specified hook files because the file path was incorrect or the file did not exist.","error":"Error: ENOENT: no such file or directory, stat 'path/to/hookfile.js'"},{"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.","cause":"Your API description document (OpenAPI, API Blueprint) contains syntax errors or is malformed, preventing Dredd from processing it.","error":"error: Failed to parse API description document."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"dredd"}