Gavel.js

<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://snyk.io/test/npm/gavel" target="_blank"> <img src="https://snyk.io/test/npm/gavel/badge.svg" alt="Known Vulnerabilities" /> </a> </p> <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 tells you whether an actual HTTP message is valid against an expected HTTP message.</p>

Install

npm install gavel

Usage

CLI

# (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.

NodeJS

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:

{
  valid: false,
  fields: {
    statusCode: {
      valid: false,
      kind: 'text',
      values: {
        expected: '200',
        actual: '404'
      },
      errors: [
        {
          message: `Expected status code '200', but got '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 is inferred.

You can describe the body expectations using JSON Schema by providing a valid schema to the bodySchema property of the expected HTTP message:

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:

{
  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'
          }
        }
      ]
    }
  }
}

Supported JSON Schema versions

• JSON Schema Draft 7
• JSON Schema Draft 6
• JSON Schema Draft 4

Examples

Take a look at the Gherkin specification, which describes on examples how validation of each field behaves:

• method
• uri
• statusCode
• headers
• body
• bodySchema

Type definitions

Gavel ships with TypeScript type definitions. Please refer to the definitions file for more details.

API

• validate(expected: HttpMessage, actual: HttpMessage): ValidationResult

License

MIT