Command-line Interface¶
Usage¶
$ dredd '<api-description-document>' '<api-location>' [OPTIONS]
Example:
$ dredd ./apiary.md http://127.0.0.1:3000
Arguments¶
-
api-description-document
¶
URL or path to the API description document (API Blueprint, OpenAPI 2). Sample values:
./api-blueprint.apib
,./openapi2.yml
,./openapi2.json
,http://example.com/api-blueprint.apib
-
api-location
¶
URL, the root address of your API. Sample values:
http://127.0.0.1:3000
,http://api.example.com
Configuration File¶
If you use Dredd repeatedly within a single project, the preferred way to run it is to first persist your configuration in a dredd.yml
file. With the file in place you can then run Dredd every time simply just by:
$ dredd
Dredd offers interactive wizard to setup your dredd.yml
file:
$ dredd init
See below how sample configuration file could look like. The structure is the same as of the Dredd Class configuration object.
reporter: apiary
custom:
- "apiaryApiKey:yourSecretApiaryAPiKey"
- "apiaryApiName:apiName"
dry-run: null
hookfiles: "dreddhooks.js"
server: rails server
server-wait: 3
init: false
names: false
only: []
output: []
header: []
sorted: false
user: null
inline-errors: false
details: false
method: []
loglevel: warning
path: []
blueprint: api-description.apib
endpoint: "http://127.0.0.1:3000"
Note
Do not get confused by Dredd using a keyword blueprint
also for paths to OpenAPI 2 documents. This is for historical reasons and will be changed in the future.
CLI Options Reference¶
Remember you can always list all available arguments by dredd --help
.
-
--color
¶
Use –color/–no-color to enable/disable colored output Default value:
true
-
--config
¶
Path to dredd.yml config file. Default value:
"./dredd.yml"
-
--custom
,
-j
¶
Pass custom key-value configuration data delimited by a colon. E.g. -j ‘a:b’ Default value:
[]
-
--details
,
-d
¶
Determines whether request/response details are included in passing tests. Default value:
false
-
--dry-run
,
-y
¶
Do not run any real HTTP transaction, only parse API description document and compile transactions. Default value:
null
-
--header
,
-h
¶
Extra header to include in every request. This option can be used multiple times to add multiple headers. Default value:
[]
-
--help
¶
Show usage information.
-
--hookfiles
,
-f
¶
Path to hook files. Can be used multiple times, supports glob patterns. Hook files are executed in alphabetical order. Default value:
null
-
--hooks-worker-after-connect-wait
¶
How long to wait between connecting to hooks handler and start of testing. [ms] Default value:
100
-
--hooks-worker-connect-retry
¶
How long to wait between attempts to connect to hooks handler. [ms] Default value:
500
-
--hooks-worker-connect-timeout
¶
Total hooks handler connection timeout (includes all retries). [ms] Default value:
1500
-
--hooks-worker-handler-host
¶
Host of the hooks handler. Default value:
"127.0.0.1"
-
--hooks-worker-handler-port
¶
Port of the hooks handler. Default value:
61321
-
--hooks-worker-term-retry
¶
How long to wait between attempts to terminate hooks handler. [ms] Default value:
500
-
--hooks-worker-term-timeout
¶
How long to wait between trying to terminate hooks handler and killing it. [ms] Default value:
5000
-
--hooks-worker-timeout
¶
How long to wait for hooks handler to start. [ms] Default value:
5000
-
--init
,
-i
¶
Run interactive configuration. Creates dredd.yml configuration file. Default value:
false
-
--inline-errors
,
-e
¶
Determines whether failures and errors are displayed as they occur (true) or aggregated and displayed at the end (false). Default value:
false
-
--language
,
-a
¶
Language of hookfiles. Possible options are: nodejs, ruby, python, php, perl, go, rust Default value:
"nodejs"
-
--loglevel
,
-l
¶
Application logging level. Supported levels: ‘debug’, ‘warning’, ‘error’, ‘silent’. The value ‘debug’ also displays timestamps. Default value:
"warning"
-
--method
,
-m
¶
Restrict tests to a particular HTTP method (GET, PUT, POST, DELETE, PATCH). This option can be used multiple times to allow multiple methods. Default value:
[]
-
--names
,
-n
¶
Only list names of requests (for use in a hookfile). No requests are made. Default value:
false
-
--only
,
-x
¶
Run only specified transaction name. Can be used multiple times Default value:
[]
-
--output
,
-o
¶
Specifies output file when using additional file-based reporter. This option can be used multiple times if multiple file-based reporters are used. Default value:
[]
-
--path
,
-p
¶
Additional API description paths or URLs. Can be used multiple times with glob pattern for paths. Default value:
[]
-
--reporter
,
-r
¶
Output additional report format. This option can be used multiple times to add multiple reporters. Options: xunit, nyan, dot, markdown, html, apiary. Default value:
[]
-
--require
¶
When using nodejs hooks, require the given module before executing hooks Default value:
null
-
--server
,
-g
¶
Run API backend server command and kill it after Dredd execution. E.g. rails server Default value:
null
-
--server-wait
¶
Set delay time in seconds between running a server and test run. Default value:
3
-
--sorted
,
-s
¶
Sorts requests in a sensible way so that objects are not modified before they are created. Order: CONNECT, OPTIONS, POST, GET, HEAD, PUT, PATCH, LINK, UNLINK, DELETE, TRACE. Default value:
false
-
--user
,
-u
¶
Basic Auth credentials in the form username:password. Default value:
null
-
--version
¶
Show version number.