Merge pull request #221 from apiaryio/unified-api

Implements unified result structure

.nvmrc

@@ -0,0 +1 @@
+v8.12.0

CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+Thank you for deciding to contribute to Gavel.js. Please read the guidelines below to ensure the smoothest developer's experience during the involvement.
+
+## Workflow
+
+1. Clone the repository.
+2. Install dependencies:
+
+```bash
+npm install
+```
+
+3. Use the correct NodeJS version:
+
+```bash
+nvm use
+```
+
+4. Create a branch for a feature or a bugfix.
+5. Follow the [Conventional Commit Messages](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#user-content--git-commit-guidelines) for commit messages.
+6. Issue a pull request and undergo a code review.
+7. Upon approval, merge the pull request.

README.md

@@ -1,24 +1,249 @@
-# Gavel.js — Validator of HTTP Transactions
+<p align="center">
+  <a href="https://badge.fury.io/js/gavel" target="_blank">
+    <img src="https://badge.fury.io/js/gavel.svg" alt="npm version" />
+  </a>
+  <a href="https://travis-ci.org/apiaryio/gavel.js" target="_blank">
+    <img src="https://travis-ci.org/apiaryio/gavel.js.svg?branch=master" alt="Build Status" />
+  </a>
+  <a href="https://ci.appveyor.com/project/Apiary/gavel-js/branch/master" target="_blank">
+    <img src="https://ci.appveyor.com/api/projects/status/0cpnaoakhs8q58tn/branch/master?svg=true" alt="Build Status" />
+  </a>
+  <a href="https://coveralls.io/r/apiaryio/gavel.js?branch=master" target="_blank">
+    <img src="https://coveralls.io/repos/apiaryio/gavel.js/badge.svg?branch=master" alt="Coverage Status" />
+  </a>
+  <a href="https://snyk.io/test/npm/gavel" target="_blank">
+    <img src="https://snyk.io/test/npm/gavel/badge.svg" alt="Known Vulnerabilities" />
+  </a>
+</p>
 
-[![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)
+<br />
 
-![Gavel.js - Validator of HTTP Transactions](https://raw.github.com/apiaryio/gavel/master/img/gavel.png?v=1)
+<p align="center">
+  <img src="https://raw.githubusercontent.com/apiaryio/gavel/master/img/gavel.png?v=1" alt="Gavel logo" />
+</p>
 
-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.
+<h1 align="center">Gavel</h1>
 
-## Installation
+<p align="center">Gavel tells you whether an actual HTTP message is valid against an expected HTTP message.</p>
 
-```sh
-$ npm install gavel
+## 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
+```
+
+> **Gavel CLI is not supported on Windows**. 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 would return the following validation `result`:
+
+```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
+
+> When a parsable JSON body is expected without an explicit schema the [default schema](https://github.com/apiaryio/gavel-spec/blob/master/features/expectations/bodyJsonExample.feature) is inferred.
+
+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'
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+> Note that JSON schema Draft-05+ are not currently supported. [Follow the support progress](https://github.com/apiaryio/gavel.js/issues/90).
+
+## Examples
+
+Take a look at the [Gherkin](https://cucumber.io/docs/gherkin/) specification, which describes on examples how validation of each field behaves:
+
+- [`method`](https://github.com/apiaryio/gavel-spec/blob/master/features/javascript/fields/method)
+- [`statusCode`](https://github.com/apiaryio/gavel-spec/blob/master/features/javascript/fields/statusCode)
+- [`headers`](https://github.com/apiaryio/gavel-spec/blob/master/features/javascript/fields/headers)
+- [`body`](https://github.com/apiaryio/gavel-spec/blob/master/features/javascript/fields/body)
+- [`bodySchema`](https://github.com/apiaryio/gavel-spec/blob/master/features/javascript/fields/bodySchema)
+
+## Type definitions
+
+Type definitions below are described using [TypeScript](https://www.typescriptlang.org/) syntax.
+
+### Input
+
+> Gavel makes no assumptions over the validity of a given HTTP message according to the HTTP specification (RFCs [2616](https://www.ietf.org/rfc/rfc2616.txt), [7540](https://httpwg.org/specs/rfc7540.html)) and will accept any input matching the input type definition. Gavel will throw an exception when given malformed input data.
+
+Both expected and actual HTTP messages (no matter request or response) inherit from a single `HttpMessage` interface:
+
+```ts
+interface HttpMessage {
+  method?: string;
+  statusCode?: number;
+  headers?: Record<string> | string;
+  body?: string;
+  bodySchema?: Object | string;
+}
 ```
 
-## Documentation
+### Output
+
+```ts
+// Field kind describes the type of a field's values
+// subjected to the end comparison.
+enum ValidationKind {
+  null // non-comparable data (validation didn't happen)
+  text // compared as text
+  json // compared as JSON
+}
+
+interface ValidationResult {
+  valid: boolean // validity of the actual message
+  fields: {
+    [fieldName: string]: {
+      valid: boolean // validity of a single field
+      kind: ValidationKind
+      values: { // end compared values (coerced, normalized)
+        actual: any
+        expected: any
+      }
+      errors: FieldError[]
+    }
+  }
+}
+
+interface FieldError {
+  message: string
+  location?: { // kind-specific additional information
+    // kind: json
+    pointer?: string
+    property?: string[]
+  }
+  values?: {
+    expected: any
+    actual: any
+  }
+}
+```
+
+## 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](LICENSE)

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);

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 = {