gavel

Gavel

Gavel tells you whether an actual HTTP message is valid against an expected HTTP message.

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'.`,
          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 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'
          }
        }
      ]
    }
  }
}

Note that JSON schema Draft-05+ are not currently supported. Follow the support progress.

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

Type definitions below are described using TypeScript syntax.

Input

Gavel makes no assumptions over the validity of a given HTTP message according to the HTTP specification (RFCs 2616, 7540) 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:

interface HttpMessage {
  uri?: string;
  method?: string;
  statusCode?: number;
  headers?: Record<string> | string;
  body?: string;
  bodySchema?: Object | string;
}

Output

// 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[]
  }
}

API

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

License

MIT