jest-openapi

library0.14.2jsnpmunverified

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.

testing http-networking serialization

npm install jest-openapi

github ↗package ↗

INSTALL

IMPORT

SIG · JEST-OPENAPI

jest-openapi

testingjavascriptv0.14.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

jestOpenAPI

✓ import jestOpenAPI from 'jest-openapi';

✗ const jestOpenAPI = require('jest-openapi');

The package exports a default function. CommonJS users must access it via `.default`.

jestOpenAPI

✓ const jestOpenAPI = require('jest-openapi').default;

✗ import { jestOpenAPI } from 'jest-openapi';

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')`.

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

Debug

Known issues

breakingThe 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.

affects: >=0.14.0

gotchaWhen 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;`.

affects: All versions

gotchaThe `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.

affects: All versions

Errors

Common errors & fixes

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

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.

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

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: 'path/to/openapi.yml' is not a valid file path or object.

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.

Upgrade

Version history

0.14.2latest on npm

Audit

Dependencies

openapi-response-validatorrequiredProvides the core OpenAPI validation logic used by jest-openapi.

@types/requestoptionalRequired for TypeScript compilation, specifically for handling HTTP response types internally, as of v0.14.2.

@types/superagentoptionalRequired for TypeScript compilation, specifically for handling HTTP response types internally, as of v0.14.2.

jestoptionalThis is a Jest plugin and requires Jest as a testing framework.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/openapi-library/OpenAPIValidators ↗

packagehttps://www.npmjs.com/package/jest-openapi ↗