Chai OpenAPI Response Validator

Use Chai to assert that HTTP responses satisfy an OpenAPI spec.

Problem 😕

If your server's behaviour doesn't match your API documentation, then you need to correct your server, your documentation, or both. The sooner you know the better.

Solution 😄

This plugin lets you automatically test whether your server's behaviour and documentation match. It extends the Chai Assertion Library to support the OpenAPI standard for documenting REST APIs. In your JavaScript tests, you can simply assert expect(responseObject).to.satisfyApiSpec

Features:

• Validates the status and body of HTTP responses against your OpenAPI spec (see example)
• Validates objects against schemas defined in your OpenAPI spec (see example)
• Load your OpenAPI spec just once in your tests (load from a filepath or object)
• Supports OpenAPI 2 and 3
• Supports OpenAPI specs in YAML and JSON formats
• Supports $ref in response definitions (i.e. $ref: '#/definitions/ComponentType/ComponentName')
• Informs you if your OpenAPI spec is invalid
• Supports responses from axios, request-promise, supertest, superagent, and chai-http
• Use in Mocha and other test runners

Contributing ✨

If you've come here to help contribute - thanks! Take a look at the contributing docs to get started.

Installation

npm

1npm install --save-dev chai-openapi-response-validator

yarn

1yarn add --dev chai-openapi-response-validator

Importing

ES6 / TypeScript

1import chaiResponseValidator from 'chai-openapi-response-validator';

CommonJS / JavaScript

1const chaiResponseValidator = require('chai-openapi-response-validator').default;

Usage

In API tests, validate the status and body of HTTP responses against your OpenAPI spec:

1. Write a test:

1// Set up Chai
2import chai from 'chai';
3const expect = chai.expect;
4
5// Import this plugin
6import chaiResponseValidator from 'chai-openapi-response-validator';
7
8// Load an OpenAPI file (YAML or JSON) into this plugin
9chai.use(chaiResponseValidator('path/to/openapi.yml'));
10
11// Write your test (e.g. using Mocha)
12describe('GET /example/endpoint', () => {
13  it('should satisfy OpenAPI spec', async () => {
14    // Get an HTTP response from your server (e.g. using axios)
15    const res = await axios.get('http://localhost:3000/example/endpoint');
16
17    expect(res.status).to.equal(200);
18
19    // Assert that the HTTP response satisfies the OpenAPI spec
20    expect(res).to.satisfyApiSpec;
21  });
22});

2. Write an OpenAPI Spec (and save to path/to/openapi.yml):

1openapi: 3.0.0
2info:
3  title: Example API
4  version: 1.0.0
5paths:
6  /example:
7    get:
8      responses:
9        200:
10          description: Response body should be an object with fields 'stringProperty' and 'integerProperty'
11          content:
12            application/json:
13              schema:
14                type: object
15                required:
16                  - stringProperty
17                  - integerProperty
18                properties:
19                  stringProperty:
20                    type: string
21                  integerProperty:
22                    type: integer

3. Run your test to validate your server's response against your OpenAPI spec:

The assertion passes if the response status and body satisfy openapi.yml:

1// Response includes:
2{
3  status: 200,
4  body: {
5    stringProperty: 'string',
6    integerProperty: 123,
7  },
8};

The assertion fails if the response body is invalid:

1// Response includes:
2{
3  status: 200,
4  body: {
5    stringProperty: 'string',
6    integerProperty: 'invalid (should be an integer)',
7  },
8};

Output from test failure:

1AssertionError: expected res to satisfy API spec
2
3expected res to satisfy the '200' response defined for endpoint 'GET /example/endpoint' in your API spec
4res did not satisfy it because: integerProperty should be integer
5
6res contained: {
7  body: {
8      stringProperty: 'string',
9      integerProperty: 'invalid (should be an integer)'
10    }
11  }
12}
13
14The '200' response defined for endpoint 'GET /example/endpoint' in API spec: {
15  '200': {
16    description: 'Response body should be a string',
17    content: {
18      'application/json': {
19        schema: {
20          type: 'string'
21        }
22      }
23    }
24  },
25}

In unit tests, validate objects against schemas defined in your OpenAPI spec:

1. Write a test:

1// Set up Chai
2import chai from 'chai';
3const expect = chai.expect;
4
5// Import this plugin and the function you want to test
6import chaiResponseValidator from 'chai-openapi-response-validator';
7import { functionToTest } from 'path/to/your/code';
8
9// Load an OpenAPI file (YAML or JSON) into this plugin
10chai.use(chaiResponseValidator('path/to/openapi.yml'));
11
12// Write your test (e.g. using Mocha)
13describe('functionToTest()', () => {
14  it('should satisfy OpenAPI spec', async () => {
15    // Assert that the function returns a value satisfying a schema defined in your OpenAPI spec
16    expect(functionToTest()).to.satisfySchemaInApiSpec('ExampleSchemaObject');
17  });
18});

2. Write an OpenAPI Spec (and save to path/to/openapi.yml):

1openapi: 3.0.0
2info:
3  title: Example API
4  version: 1.0.0
5paths:
6  /example:
7    get:
8      responses:
9        200:
10          description: Response body should be an ExampleSchemaObject
11          content:
12            application/json:
13              schema: '#/components/schemas/ExampleSchemaObject'
14components:
15  schemas:
16    ExampleSchemaObject:
17      type: object
18      required:
19        - stringProperty
20        - integerProperty
21      properties:
22        stringProperty:
23          type: string
24        integerProperty:
25          type: integer

3. Run your test to validate your object against your OpenAPI spec:

The assertion passes if the object satisfies the schema ExampleSchemaObject:

1// object includes:
2{
3  stringProperty: 'string',
4  integerProperty: 123,
5};

The assertion fails if the object does not satisfy the schema ExampleSchemaObject:

1// object includes:
2{
3  stringProperty: 123,
4  integerProperty: 123,
5};

Output from test failure:

1AssertionError: expected object to satisfy schema 'ExampleSchemaObject' defined in API spec:
2object did not satisfy it because: stringProperty should be string
3
4object was: {
5    {
6      stringProperty: 123,
7      integerProperty: 123
8    }
9  }
10}
11
12The 'ExampleSchemaObject' schema in API spec: {
13  type: 'object',
14  required: [
15    'stringProperty'
16    'integerProperty'
17  ],
18  properties: {
19    stringProperty: {
20      type: 'string'
21    },
22    integerProperty: {
23      type: 'integer'
24    }
25  }
26}

Loading your OpenAPI spec (3 different ways):

1. From an absolute filepath (see above)

2. From an object:

1// Set up Chai
2import chai from 'chai';
3const expect = chai.expect;
4
5// Import this plugin
6import chaiResponseValidator from 'chai-openapi-response-validator';
7
8// Get an object representing your OpenAPI spec
9const openApiSpec = {
10  openapi: '3.0.0',
11  info: {
12    title: 'Example API',
13    version: '0.1.0',
14  },
15  paths: {
16    '/example/endpoint': {
17      get: {
18        responses: {
19          200: {
20            description: 'Response body should be a string',
21            content: {
22              'application/json': {
23                schema: {
24                  type: 'string',
25                },
26              },
27            },
28          },
29        },
30      },
31    },
32  },
33};
34
35// Load that OpenAPI object into this plugin
36chai.use(chaiResponseValidator(openApiSpec));
37
38// Write your test (e.g. using Mocha)
39describe('GET /example/endpoint', () => {
40  it('should satisfy OpenAPI spec', async () => {
41    // Get an HTTP response from your server (e.g. using axios)
42    const res = await axios.get('http://localhost:3000/example/endpoint');
43
44    expect(res.status).to.equal(200);
45
46    // Assert that the HTTP response satisfies the OpenAPI spec
47    expect(res).to.satisfyApiSpec;
48  });
49});

3. From a web endpoint:

1// Set up Chai
2import chai from 'chai';
3const expect = chai.expect;
4
5// Import this plugin and an HTTP client (e.g. axios)
6import chaiResponseValidator from 'chai-openapi-response-validator';
7import axios from 'axios';
8
9// Write your test (e.g. using Mocha)
10describe('GET /example/endpoint', () => {
11  // Load your OpenAPI spec from a web endpoint
12  before(async () => {
13    const response = await axios.get('url/to/openapi/spec');
14    const openApiSpec = response.data; // e.g. { openapi: '3.0.0', <etc> };
15    chai.use(chaiResponseValidator(openApiSpec));
16  });
17
18  it('should satisfy OpenAPI spec', async () => {
19    // Get an HTTP response from your server (e.g. using axios)
20    const res = await axios.get('http://localhost:3000/example/endpoint');
21
22    expect(res.status).to.equal(200);
23
24    // Assert that the HTTP response satisfies the OpenAPI spec
25    expect(res).to.satisfyApiSpec;
26  });
27});