Jest Matchers for OpenAPI Validation

0.14.2 verified Thu Apr 23 auth: no javascript

jest-openapi is a Jest plugin that significantly enhances the standard Jest assertion capabilities by providing specialized matchers for validating API responses and data objects against an OpenAPI specification (supporting both v2 and v3). Its core purpose is to automate the verification that a server's actual runtime behavior precisely matches its documented API contract. The current stable version, 0.14.2, was last updated in January 2022, having seen several iterative improvements and fixes throughout 2021, indicating an actively maintained project with a practical, feature-driven release cadence. This library is indispensable for ensuring contract consistency and preventing silent discrepancies between backend service implementations and their public-facing documentation, thereby reducing integration issues for consuming clients. It stands out by offering broad compatibility with responses from various popular HTTP client libraries, including axios, request-promise, supertest, and superagent. Furthermore, it effortlessly processes OpenAPI specifications provided in either YAML or JSON formats, intelligently resolves $ref declarations within the spec, and delivers clear, diagnostic error messages when validation failures occur. For development teams utilizing testing frameworks that are built around Chai, a companion package, chai-openapi-response-validator, offers an equivalent set of validation utilities.

Common errors

error TypeError: expect(...).toSatisfyApiSpec is not a function ↓

cause The jest-openapi matchers have not been loaded or initialized correctly into Jest's environment.

fix

Ensure jestOpenAPI('path/to/spec.yml'); is called once in your test setup or at the beginning of the test file where the matchers are used. Also, check that the import jestOpenAPI from 'jest-openapi'; or const jestOpenAPI = require('jest-openapi').default; statement is present.

error ValidationError: Response does not match OpenAPI spec: ... ↓

cause The actual HTTP response object (status, headers, body) or the validated object does not conform to the schema defined in your OpenAPI specification for the given request path and method.

fix

Inspect the detailed error message provided by jest-openapi. It will pinpoint which part of the response (e.g., status code, header, body property) violated the spec. You will then need to either adjust your API implementation to match the spec or update your OpenAPI specification to accurately reflect the API's current behavior.

error Error: 'path/to/openapi.yml' is not a valid file path or object. ↓

cause The argument provided to `jestOpenAPI()` is either an incorrect file path, a non-existent file, or an invalid OpenAPI object.

fix

Double-check the provided path string. Ensure it is absolute or correctly relative to the current working directory or the test file. Verify that the file exists, is readable, and contains valid YAML or JSON conforming to the OpenAPI specification. If providing an object, ensure it is a correctly structured OpenAPI definition.

Warnings

breaking The underlying validation dependency `openapi-response-validator` was updated from v3 to v9 in v0.14.0. This might introduce changes in validation rules, behavior, and specifically, the error messages returned for validation failures. ↓

fix Review your tests that assert on specific error messages or subtle validation edge cases, as they might need adjustments. Ensure your API still passes validation against the updated dependency.

gotcha When using CommonJS `require`, the `jest-openapi` module exports a default function, which must be accessed via `.default`. Directly requiring without `.default` will result in an undefined module. ↓

fix Change `const jestOpenAPI = require('jest-openapi');` to `const jestOpenAPI = require('jest-openapi').default;`.

gotcha The `jestOpenAPI()` function must be called with a valid path to your OpenAPI specification file (YAML or JSON) or an OpenAPI object before `toSatisfyApiSpec()` or `toSatisfySchemaInApiSpec()` can be used. Failure to do so will result in Jest matcher errors. ↓

fix Ensure `jestOpenAPI('path/to/your/spec.yml')` is executed once in your test setup (e.g., `setupFilesAfterEnv` in Jest config or at the top of a test file) before any tests run that use its matchers. Verify the path is correct and the file exists.

Install

npm install jest-openapi

yarn add jest-openapi

pnpm add jest-openapi

Imports

jestOpenAPI
wrong
```
const jestOpenAPI = require('jest-openapi');
```
correct
```
import jestOpenAPI from 'jest-openapi';
```
The package exports a default function. CommonJS users must access it via `.default`.
jestOpenAPI
wrong
```
import { jestOpenAPI } from 'jest-openapi';
```
correct
```
const jestOpenAPI = require('jest-openapi').default;
```
This is the correct CommonJS `require` pattern. Attempting to import named exports will fail as it only provides a default export.
toSatisfyApiSpec
```
expect(response).toSatisfyApiSpec();
```
This is a Jest matcher extended by jest-openapi, and is automatically available after calling `jestOpenAPI('path/to/spec.yml')`.

Quickstart

Demonstrates initializing jest-openapi with an OpenAPI spec and using `toSatisfyApiSpec()` to validate an HTTP response and `toSatisfySchemaInApiSpec()` for an object.

import axios from 'axios';
import jestOpenAPI from 'jest-openapi';
import path from 'path';

// Point to your OpenAPI spec file. Ensure the path is correct.
const openApiSpecPath = path.resolve(__dirname, './openapi.yml');

// Load your OpenAPI spec into the plugin once per test suite.
// This makes the custom matchers available globally within Jest's context.
jestOpenAPI(openApiSpecPath);

describe('API Endpoint Validation', () => {
  it('should validate GET /users against OpenAPI spec', async () => {
    // Simulate an HTTP response from your server
    // Replace with your actual API call (e.g., using axios, supertest)
    const res = await axios.get('http://localhost:3000/users');

    expect(res.status).toEqual(200);

    // Assert that the HTTP response satisfies the OpenAPI spec
    expect(res).toSatisfyApiSpec();
  });

  it('should validate a specific object against a schema', () => {
    const userObject = { id: 1, name: 'John Doe', email: 'john.doe@example.com' };
    // Assuming 'User' is a defined schema in your openapi.yml
    expect(userObject).toSatisfySchemaInApiSpec('User');
  });
});