Data Structures

Data Structures#

Documentation of various data structures used by 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 transaction

  • name: My API > /greetings > Retrieve Message > 200 > application/json (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.yaml (string)

    • apiName: My API (string)

    • resourceGroupName: '' (string) - empty for OpenAPI 3, which has no resource groups

    • resourceName: /greetings (string) - the path of the operation

    • actionName: Retrieve Message (string) - the operation summary (or the HTTP method when there is none)

    • exampleName: 200 > application/json (string) - the response status code and media type

  • host: 127.0.0.1 (string) - server hostname without port number

  • port: 3000 (number) - server port number

  • protocol: https: (enum[string]) - server protocol

    • https: (string)

    • http: (string)

  • fullPath: /message (string) - expanded URI Template with parameters (if any) used for the HTTP request Dredd performs to the tested server

  • request (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) - indicates body contains a textual content encoded in UTF-8

      • base64 (string) - indicates body 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 description

    • method: 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) - indicates body contains a textual content encoded in UTF-8

      • base64 (string) - indicates body contains a binary content encoded in Base64

  • skip: false (boolean) - can be set to true and the transaction will be skipped

  • fail: false (enum) - can be set to true 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 Validation 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 is produced by Dredd’s built-in response validator.

Validation Result Field (object)#

  • 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[Validation Error (object)])

Validation 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