Data Structures
Documentation of various data structures in both Gavel and Dredd. MSON notation is used to describe the data structures.
Transaction (object)
Transaction object is passed as a first argument to hook functions and is one of the main public interfaces in Dredd.
id:
GET (200) /greetings
- identifier for this transactionname:
./api-description.apib > My API > Greetings > Hello, world! > Retrieve Message > Example 2
(string) - reference to the transaction definition in the original API description document (see also Dredd Transactions)origin (object) - reference to the transaction definition in the original API description document (see also Dredd Transactions)
filename:
./api-description.apib
(string)apiName:
My Api
(string)resourceGroupName:
Greetings
(string)resourceName:
Hello, world!
(string)actionName:
Retrieve Message
(string)exampleName:
Example 2
(string)
host:
127.0.0.1
(string) - server hostname without port numberport:
3000
(number) - server port numberprotocol:
https:
(enum[string]) - server protocolhttps:
(string)http:
(string)
fullPath:
/message
(string) - expanded URI Template with parameters (if any) used for the HTTP request Dredd performs to the tested serverrequest (object) - the HTTP request Dredd performs to the tested server, taken from the API description
body:
Hello world!\n
(string)bodyEncoding (enum) - can be manually set in hooks
utf-8
(string) - indicatesbody
contains a textual content encoded in UTF-8base64
(string) - indicatesbody
contains a binary content encoded in Base64
headers (object) - keys are HTTP header names, values are HTTP header contents
uri:
/message
(string) - request URI as it was written in API descriptionmethod:
POST
(string)
expected (object) - the HTTP response Dredd expects to get from the tested server
statusCode:
200
(string)headers (object) - keys are HTTP header names, values are HTTP header contents
body (string)
bodySchema (object) - JSON Schema of the response body
real (object) - the HTTP response Dredd gets from the tested server (present only in
after
hooks)statusCode:
200
(string)headers (object) - keys are HTTP header names, values are HTTP header contents
body (string)
bodyEncoding (enum)
utf-8
(string) - indicatesbody
contains a textual content encoded in UTF-8base64
(string) - indicatesbody
contains a binary content encoded in Base64
skip:
false
(boolean) - can be set totrue
and the transaction will be skippedfail:
false
(enum) - can be set totrue
or string and the transaction will fail(string) - failure message with details why the transaction failed
(boolean)
test (Transaction Test (object)) - test data passed to Dredd’s reporters
errors (Test Runtime Error (object)) - Transaction runtime errors
results (Transaction Results (object)) - testing results
Transaction Test (object)
start (Date) - start of the test
end (Date) - end of the test
duration (number) - duration of the test in milliseconds
startedAt (number) - unix timestamp, transaction.startedAt
title (string) - transaction.id
request (object) - transaction.request
actual (object) - transaction.real
expected (object) - transaction.expected
status (enum) - whether the validation passed or not, defaults to empty string
pass
(string)fail
(string)skip
(string)
message (string) - concatenation of all messages from all Gavel Error (object) in
results
or Dredd’s custom message (e.g. “failed in before hook”)results (Dredd’s transaction.results)
valid (boolean)
origin (object) - transaction.origin
Transaction Results (object)
Transaction result equals to the result of the Gavel validation library.
valid (boolean) - Indicates whether the transaction is valid.
fields (object) - uri - Gavel Validation Result Field (object) - method - Gavel Validation Result Field (object) - statusCode - Gavel Validation Result Field (object) - headers - Gavel Validation Result Field (object) - body - Gavel Validation Result Field (object)
Gavel Validation Result Field (object)
Can be seen also here.
valid (boolean) - Whether the HTTP message field is valid
kind (enum[string], nullable) - The validation kind applied to the expected/actual data (how the values were compared) - json - text
values (object)
expected (any) - Expected value of the HTTP message field
actual (any) - Actual value of the HTTP message field
errors (array[Gavel Error (object)])
Gavel Error (object)
message (string) - Error message
location (object, optional) - Kind-dependent extra error information
pointer (string) - JSON Pointer path
property (array[string]) - A deep property path
Test Runtime Error (object)
Whenever an exception occurs during a test run it’s being recorded under the errors
property of the test.
Test run error has the following structure:
message (string) - Error message.
severity (enum[string]) - Severity of the occurred error - warning - error
Apiary Reporter Test Data (object)
testRunId (string) - ID of the test run, recieved from Apiary
origin (object) - test.origin
duration (number) - duration of the test in milliseconds
result (string) - test.status
startedAt (number) - test.startedAt
results (object)
request (object) - test.request
realResponse (object) - test.actual
expectedResponse (object) - test.expected
errors (array[Test Runtime Error (object)]) - Test run errors (not validation errors)
validationResult (Transaction Results (object)) - test.results
Internal Apiary Data Structures
These are private data structures used in Apiary internally and they are documented incompletely. They’re present in this document just to provide better insight on what and how Apiary internally saves. It is closely related to what you can see in documentation for Apiary Tests API for authenticated test reports.
Apiary Test Run (object)
Also known as stats
in Dredd’s code.
result
tests:
0
(number, default) - total number of testsfailures:
0
(number, default)errors:
0
(number, default)passes:
0
(number, default)skipped:
0
(number, default)start:
0
(number, default)end:
0
(number, default)duration:
0
(number, default)
Apiary Test Step (object)
results
request (object) - test.request
realResponse (object) - test.actual
expectedResponse (object) - test.expected
errors (array[Test Runtime Error (object)]) - Test runtime errors
validationResult (Transaction Results (object)) - test.results