From bfac836476aac370e296045bd58ac3efb97f58b0 Mon Sep 17 00:00:00 2001 From: artem-zakharchenko Date: Mon, 19 Aug 2019 11:42:45 +0200 Subject: [PATCH] docs: updates "Data structures" with new transaction structure --- docs/data-structures.rst | 94 ++++++++++++++-------------------------- 1 file changed, 33 insertions(+), 61 deletions(-) diff --git a/docs/data-structures.rst b/docs/data-structures.rst index a2f54cc79..8644e0157 100644 --- a/docs/data-structures.rst +++ b/docs/data-structures.rst @@ -68,6 +68,7 @@ Transaction object is passed as a first argument to :ref:`hook functions - (boolean) - test (:ref:`transaction-test`) - test data passed to Dredd’s reporters +- errors (:ref:`test-run-error`) - Transaction run errors (not validation errors) - results (:ref:`transaction-results`) - testing results .. _transaction-test: @@ -94,32 +95,17 @@ Transaction Test (object) - valid (boolean) - origin (object) - :ref:`transaction `.origin -.. _transaction-results: - -Transaction Results (object) ----------------------------- - -This is a cousin of the :ref:`gavel-validation-result`. - -- general (object) - contains Dredd’s custom messages (e.g. “test was skipped”), formatted the same way like those from Gavel - - - results (array[:ref:`gavel-error`]) - -- statusCode (:ref:`gavel-validator-output`) -- headers (:ref:`gavel-validator-output`) -- body (:ref:`gavel-validator-output`) - .. _gavel-validation-result: -Gavel Validation Result (object) +Transaction Results (object) -------------------------------- -Can be seen also `here `__ and `here `__. +Transaction result equals to the validation result of the :ref:`gavel-validation-result`. You can read more about the `Gavel validation structure `__. -- statusCode (:ref:`gavel-validator-output`) -- headers (:ref:`gavel-validator-output`) -- body (:ref:`gavel-validator-output`) -- version (string) - version number of the Gavel Validation Result structure +- valid (boolean) - Indicates whether a transaction is valid. +- fields (object) + + - [fieldName: string]: :ref:`gavel-validator-output` .. _gavel-validator-output: @@ -128,54 +114,38 @@ Gavel Validator Output (object) Can be seen also `here `__. -- results (array[:ref:`gavel-error`]) -- realType (string) - media type -- expectedType (string) - media type -- validator (string) - validator class name -- rawData (enum) - raw output of the validator, has different structure for every validator and is saved and used in Apiary to render graphical diff by `gavel2html `__ - - - (:ref:`jsonschema-validation-result`) - - (:ref:`textdiff-validation-result`) +- valid (boolean) - Indicates an HTTP message field as valid +- kind (enum: "json" | "text" | null) +- values (object) -.. _jsonschema-validation-result: + - expected (any) - Expected value of an HTTP message field + - actual (any) - Actual value of an HTTP message field -JsonSchema Validation Result (object) -------------------------------------- +- errors (:ref:`gavel-error`[]) -The validation error is based on format provided by `Amanda `__ and is also “documented” `here `__. Although for validation of draft4 JSON Schema Gavel uses `tv4 `__ library, the output then gets reshaped into the structure of Amanda’s errors. +.. _gavel-error: -This validation result is returned not only when validating against `JSON Schema`_, but also when validating against JSON example or when validating HTTP headers. +Gavel Error (object) +-------------------- -- length: ``0`` (number, default) - number of error properties -- errorMessages (object) - doesn’t seem to ever contain anything or be used for anything -- *0* (object) - validation error details, property is always a string containing a number (0, 1, 2, …) +Can also be seen as part of Gavel Validator Output `here `__. - - property (array[string]) - path to the problematic property in format of `json-pointer’s parse() output `__ - - propertyValue (mixed) - real value of the problematic property (can be also ``undefined`` etc.) - - attributeName: ``enum``, ``required`` (string) - name of the relevant JSON Schema attribute, which triggered the error - - attributeValue (mixed) - value of the relevant JSON Schema attribute, which triggered the error - - message (string) - error message (in case of tv4 it contains :rfc:`JSON Pointer <6901>` to the problematic property and for both Amanda and tv4 it can directly mention property names and/or values) - - validator: ``enum`` (string) - the same as ``attributeName`` - - validatorName: ``error``, ``enum`` (string) - the same as ``attributeName`` - - validatorValue (mixed) - the same as ``attributeValue`` +- message (string) - Error message +- location (object) - (Optional) kind-dependent extra error information -.. _textdiff-validation-result: + - pointer (string) - :rfc:`JSON Pointer <6901>` path + - property (string[]) - A deep property path -TextDiff Validation Result (string) ------------------------------------ +.. _test-run-error: -Block of text which looks extremely similar to the standard GNU diff/patch format. Result of the ``patch_toText()`` function of the ``google-diff-match-patch`` library (`docs `__). +Test run error (object) +-------------- -.. _gavel-error: +Whenever an exception occurs during a test run it's being recorded under the ``errors`` property of the test. -Gavel Error (object) --------------------- - -Can also be seen as part of Gavel Validator Output `here `__. +Test run error has the following structure: -- pointer (string) - :rfc:`JSON Pointer <6901>` path -- severity (string) - severity of the error -- message (string) - error message +- message (string) - Error message. .. _apiary-reporter-test-data: @@ -187,12 +157,13 @@ Apiary Reporter Test Data (object) - duration (number) - duration of the test in milliseconds - result (string) - :ref:`test `.status - startedAt (number) - :ref:`test `.startedAt -- resultData (object) +- results (object) - request (object) - :ref:`test `.request - realResponse (object) - :ref:`test `.actual - expectedResponse (object) - :ref:`test `.expected - - result (:ref:`transaction-results`) - :ref:`test `.results + - errors (:ref:`test-run-error`) - Test run errors (not validation errors) + - validationResult (:ref:`transaction-results`) - :ref:`test `.results Internal Apiary Data Structures ------------------------------- @@ -222,9 +193,10 @@ Also known as ``stats`` in Dredd’s code. Apiary Test Step (object) ~~~~~~~~~~~~~~~~~~~~~~~~~ -- resultData +- results - request (object) - :ref:`test `.request - realResponse (object) - :ref:`test `.actual - expectedResponse (object) - :ref:`test `.expected - - result (:ref:`transaction-results`) - :ref:`test `.results + - errors (:ref:`test-run-error`) - Test run errors (not validation errors) + - validationResult (:ref:`transaction-results`) - :ref:`test `.results