Merge 7505169 into bc312ff

apiaryio · Jul 2, 2019 · fd1be98 · fd1be98
2 parents bc312ff + 7505169
commit fd1be98
Show file tree

Hide file tree

Showing 32 changed files with 766 additions and 1,214 deletions.
diff --git a/README.md b/README.md
@@ -1,24 +1,221 @@
-# Gavel.js — Validator of HTTP Transactions
-
 [![npm version](https://badge.fury.io/js/gavel.svg)](https://badge.fury.io/js/gavel)
 [![Build Status](https://travis-ci.org/apiaryio/gavel.js.svg?branch=master)](https://travis-ci.org/apiaryio/gavel.js)
 [![Build status](https://ci.appveyor.com/api/projects/status/0cpnaoakhs8q58tn/branch/master?svg=true)](https://ci.appveyor.com/project/Apiary/gavel-js/branch/master)
 [![Coverage Status](https://coveralls.io/repos/apiaryio/gavel.js/badge.svg?branch=master)](https://coveralls.io/r/apiaryio/gavel.js?branch=master)
 [![Known Vulnerabilities](https://snyk.io/test/npm/gavel/badge.svg)](https://snyk.io/test/npm/gavel)
 
-![Gavel.js - Validator of HTTP Transactions](https://raw.github.com/apiaryio/gavel/master/img/gavel.png?v=1)
+<br />
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/apiaryio/gavel/master/img/gavel.png?v=1" alt="Gavel logo" />
+</p>
+
+<h1 align="center">Gavel</h1>
+
+<p align="center">Gavel is a library that validates a given HTTP transaction (request/response pair).</p>
+
+## Install
+
+```bash
+npm install gavel
+```
+
+## Usage
+
+### CLI
+
+```bash
+# (Optional) Record HTTP messages
+curl -s --trace - http://httpbin.org/ip | curl-trace-parser > expected
+curl -s --trace - http://httpbin.org/ip | curl-trace-parser > actual
+
+# Perform the validation
+cat actual | gavel expected
+```
+
+> Example above uses [`curl-trace-parser`](https://github.com/apiaryio/curl-trace-parser).
+
+### NodeJS
+
+```js
+const gavel = require('gavel');
+
+// Define HTTP messages
+const expected = {
+  statusCode: 200,
+  headers: {
+    'Content-Type': 'application/json'
+  }
+};
+
+const actual = {
+  statusCode: 404,
+  headers: {
+    'Content-Type': 'application/json'
+  }
+};
+
+// Perform the validation
+const result = gavel.validate(expected, actual);
+```
+
+The code above wouold return the next validation `result`:
 
-Gavel detects important differences between actual and expected HTTP transactions (HTTP request and response pairs). Gavel also decides whether the actual HTTP transaction is valid or not.
+```js
+{
+  valid: false,
+  fields: {
+    statusCode: {
+      valid: false,
+      kind: 'text',
+      values: {
+        expected: 200,
+        actual: 404
+      },
+      errors: [
+        {
+          message: `Expected status code '200', but got '404'.`,
+          values: {
+            expected: 200,
+            actual: 404
+          }
+        }
+      ]
+    },
+    headers: {
+      valid: true,
+      kind: 'json',
+      values: {
+        expected: {
+          'Content-Type': 'application/json'
+        },
+        actual: {
+          'Content-Type': 'application/json'
+        }
+      },
+      errors: []
+    }
+  }
+}
+```
+
+### Usage with JSON Schema
+
+You can describe the body expectations using [JSON Schema](https://json-schema.org/) by providing a valid schema to the `bodySchema` property of the expected HTTP message:
+
+```js
+const gavel = require('gavel');
+
+const expected = {
+  bodySchema: {
+    type: 'object',
+    properties: {
+      fruits: {
+        type: 'array',
+        items: {
+          type: 'string'
+        }
+      }
+    }
+  }
+};
+
+const actual = {
+  body: JSON.stringify({
+    fruits: ['apple', 'banana', 2]
+  })
+};
+
+const result = gavel.validate(expected, actual);
+```
+
+The validation `result` against the given JSON Schema will look as follows:
+
+```js
+{
+  valid: false,
+  fields: {
+    body: {
+      valid: false,
+      kind: 'json',
+      values: {
+        actual: "{\"fruits\":[\"apple\",\"banana\",2]}"
+      },
+      errors: [
+        {
+          message: `At '/fruits/2' Invalid type: number (expected string)`,
+          location: {
+            pointer: '/fruits/2'
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+## Type definitions
+
+### Input
+
+> Gavel has no assumptions over the validity of a given HTTP message. It is the end user responsibility to operate on the valid data. Gavel will throw an exception when given invalid input data.
+
+Both expected and actual HTTP messages inherit from a generic `HttpMessage` interface:
 
-## Installation
+```ts
+interface HttpMessage {
+  method?: string;
+  statusCode?: number;
+  headers?: Record<string> | string;
+  body?: string;
+  bodySchema?: Object | string;
+}
+```
+
+### Output
+
+```ts
+// Field kind describes the type of a field's values
+// subjected to the end comparison.
+enum FieldKind {
+  null // non-comparable data (validation didn't happen)
+  text // compared as text
+  json // compared as JSON
+}
 
-```sh
-$ npm install gavel
+interface ValidationResult {
+  valid: boolean // validity of the actual message
+  fields: {
+    [fieldName: string]: {
+      valid: boolean // validity of a single field
+      kind: FieldKind
+      values: { // end compared values (coerced, normalized)
+        actual: any
+        expected: any
+      }
+      errors: FieldError[]
+    }
+  }
+}
+
+interface FieldError {
+  message: string
+  location?: { // kind-specific additional information
+    // JSON
+    pointer?: string
+    property?: string
+  }
+  values?: {
+    expected: any
+    actual: any
+  }
+}
 ```
 
-## Documentation
+## API
+
+- `validate(expected: HttpMessage, actual: HttpMessage): ValidationResult`
 
-Gavel.js is a JavaScript implementation of the [Gavel behavior specification](https://www.relishapp.com/apiary/gavel/) ([repository](https://github.com/apiaryio/gavel-spec)):
+## License
 
-- [Gavel.js-specific documentation](https://www.relishapp.com/apiary/gavel/docs/javascript/)
-- [CLI documentation](https://www.relishapp.com/apiary/gavel/docs/command-line-interface/)
+MIT
diff --git a/bin/gavel b/bin/gavel
@@ -33,7 +33,7 @@ process.stdin.on('end', function() {
     const requestResult = gavel.validate(expectedRequest, realRequest);
     const responseResult = gavel.validate(expectedResponse, realResponse);
 
-    if (requestResult.isValid && responseResult.isValid) {
+    if (requestResult.valid && responseResult.valid) {
       process.exit(0);
     } else {
       process.exit(1);

diff --git a/lib/units/isValid.js b/lib/units/isValid.js
@@ -10,11 +10,11 @@ function isValidField({ errors }) {
 
 /**
  * Returns a boolean indicating the given validation result as valid.
- * @param {Object<string, any>} validationResult
+ * @param {Object<string, any>} fields
  * @returns {boolean}
  */
-function isValidResult(validationResult) {
-  return Object.values(validationResult.fields).every(isValidField);
+function isValidResult(fields) {
+  return Object.values(fields).every(isValidField);
 }
 
 module.exports = {

diff --git a/lib/units/validateBody.js b/lib/units/validateBody.js
@@ -126,41 +126,46 @@ function getBodyValidator(realType, expectedType) {
   };
 
   const validators = [
-    [TextDiff, both(isPlainText)],
+    [TextDiff, both(isPlainText), 'text'],
     // List JsonSchema first, because weak predicate of JsonExample
     // would resolve on "application/schema+json" media type too.
     [
       JsonSchema,
       (real, expected) => {
         return isJson(real) && isJsonSchema(expected);
-      }
+      },
+      'json'
     ],
-    [JsonExample, both(isJson)]
+    [JsonExample, both(isJson), 'json']
   ];
 
   const validator = validators.find(([_name, predicate]) => {
     return predicate(realType, expectedType);
   });
 
   if (!validator) {
-    const error = `Can't validate real media type '${mediaTyper.format(
+    const error = `Can't validate actual media type '${mediaTyper.format(
       realType
-    )}' against expected media type '${mediaTyper.format(expectedType)}'.`;
-    return [error, null];
+    )}' against the expected media type '${mediaTyper.format(expectedType)}'.`;
+    return [error, null, null];
   }
 
-  return [null, validator[0]];
+  return [null, validator[0], validator[2]];
 }
 
 /**
  * Validates given bodies of transaction elements.
  * @param {Object<string, any>} expected
  * @param {Object<string, any>} real
  */
-function validateBody(expected, real) {
+function validateBody(expected, actual) {
+  const values = {
+    expected: expected.body,
+    actual: actual.body
+  };
   const errors = [];
-  const realBodyType = typeof real.body;
-  const hasEmptyRealBody = real.body === '';
+  const realBodyType = typeof actual.body;
+  const hasEmptyRealBody = actual.body === '';
 
   // Throw when user input for real body is not a string.
   if (realBodyType !== 'string') {
@@ -170,8 +175,8 @@ function validateBody(expected, real) {
   }
 
   const [realTypeError, realType] = getBodyType(
-    real.body,
-    real.headers && real.headers['content-type'],
+    actual.body,
+    actual.headers && actual.headers['content-type'],
     'real'
   );
 
@@ -185,22 +190,24 @@ function validateBody(expected, real) {
 
   if (realTypeError) {
     errors.push({
-      message: realTypeError
+      message: realTypeError,
+      values
     });
   }
 
   if (expectedTypeError) {
     errors.push({
-      message: expectedTypeError
+      message: expectedTypeError,
+      values
     });
   }
 
   const hasErrors = errors.length > 0;
 
   // Skipping body validation in case errors during
   // real/expected body type definition.
-  const [validatorError, ValidatorClass] = hasErrors
-    ? [null, null]
+  const [validatorError, ValidatorClass, kind] = hasErrors
+    ? [null, null, null]
     : getBodyValidator(realType, expectedType);
 
   if (validatorError) {
@@ -213,11 +220,13 @@ function validateBody(expected, real) {
       errors.push({
         message: `Expected "body" of "${mediaTyper.format(
           expectedType
-        )}" media type, but actual "body" is missing.`
+        )}" media type, but actual "body" is missing.`,
+        values
       });
     } else {
       errors.push({
-        message: validatorError
+        message: validatorError,
+        values
       });
     }
   }
@@ -226,19 +235,19 @@ function validateBody(expected, real) {
   const validator =
     ValidatorClass &&
     new ValidatorClass(
-      real.body,
+      actual.body,
       usesJsonSchema ? expected.bodySchema : expected.body
     );
-  const rawData = validator && validator.validate();
+  // Without ".validate()" it cannot evaluate output to result.
+  // TODO Re-do this.
+  validator && validator.validate();
   const validationErrors = validator ? validator.evaluateOutputToResults() : [];
   errors.push(...validationErrors);
 
   return {
-    isValid: isValidField({ errors }),
-    validator: ValidatorClass && ValidatorClass.name,
-    realType: mediaTyper.format(realType),
-    expectedType: mediaTyper.format(expectedType),
-    rawData,
+    valid: isValidField({ errors }),
+    kind,
+    values,
     errors
   };
 }