Gavel HTTP Transaction Validator

10.0.4 · maintenance · verified Wed Apr 22

Gavel is a JavaScript library designed for validating actual HTTP messages against expected HTTP messages. It provides a detailed comparison, indicating discrepancies in status codes, headers, and body content. The library supports JSON Schema validation (Draft 4, 6, and 7) for defining complex body expectations. The current stable version is 10.0.4, last released in December 2021. Its release cadence appears infrequent, with recent updates primarily focused on security patches for internal dependencies rather than new feature development. Gavel differentiates itself by offering granular validation results, pinpointing exact failures, including specific error messages and locations within JSON Schema mismatches, making it a valuable tool for API contract testing and robust HTTP interaction validation.

Common errors

```
ReferenceError: require is not defined in ES module scope
```
cause Attempting to use CommonJS `require()` in an ESM context (e.g., in a `.mjs` file or when `type: "module"` is set in `package.json`).

fix Use ESM `import gavel from 'gavel';` instead of `const gavel = require('gavel');`.
```
Expected status code '200', but got '404'.
```
cause The actual HTTP response status code does not match the expected status code defined in the validation rules.

fix Adjust the `expected.statusCode` value to match the anticipated actual status code, or verify that the actual response is indeed incorrect.
```
At '/fruits/2' Invalid type: number (expected string)
```
cause The actual HTTP body data does not conform to the JSON Schema provided in `expected.bodySchema` at the specified JSON Pointer path.

fix Modify the `actual.body` to match the expected JSON Schema structure and data types, or refine the `expected.bodySchema` to accurately reflect valid inputs.

Warnings

breaking Gavel v10.0.0 increased the minimum required Node.js version to `v10.18`.
Fix: Ensure your Node.js environment is at least v10.18.0. Update Node.js if necessary.
gotcha The Gavel CLI is explicitly stated as not supported on Windows environments.
Fix: For Windows users, use the Node.js API directly or a WSL (Windows Subsystem for Linux) environment for CLI usage.
gotcha Recent releases (v10.0.x) primarily consist of dependency security updates (e.g., `glob-parent`, `tar`, `lodash`). While fixes, frequent updates for transitive dependencies might indicate an older dependency tree or potential supply chain risks if not regularly patched.
Fix: Regularly update `gavel` to the latest patch version to incorporate critical security fixes. Perform routine dependency audits.

Install

npm install gavel npm
yarn add gavel yarn
pnpm add gavel pnpm

Imports

gavel
wrong:
```
const gavel = require('gavel');
```
correct:
```
import gavel from 'gavel';
```
While the README shows CJS, for modern TypeScript/ESM projects, use `import gavel from 'gavel';`. Gavel ships with TypeScript types.

gavel.validate

wrong:

import { validate } from 'gavel'; // Gavel does not expose named exports for core functions directly.

correct:

import gavel from 'gavel'; const result = gavel.validate(expected, actual);

The primary validation logic is exposed as a method on the default `gavel` object.

Gavel.ValidationResult
```
import type { GavelValidationResult } from 'gavel';
```
For type-checking the validation result object, import `GavelValidationResult`.

Quickstart

Demonstrates basic HTTP transaction validation, including status code, headers, and JSON body against a schema.

import gavel from 'gavel';

const expected = {
  statusCode: 200,
  headers: {
    'Content-Type': 'application/json'
  },
  bodySchema: {
    type: 'object',
    properties: {
      message: { type: 'string' }
    },
    required: ['message']
  }
};

const actual = {
  statusCode: 200,
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'Hello, world!'
  })
};

const result = gavel.validate(expected, actual);
console.log(result);

view raw JSON →