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
npm install --save-dev chai-openapi-response-validator
yarn
yarn add --dev chai-openapi-response-validator
Importing
ES6 / TypeScript
import chaiResponseValidator from 'chai-openapi-response-validator';
CommonJS / JavaScript
const 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:
import chai from 'chai';
const expect = chai.expect;
import chaiResponseValidator from 'chai-openapi-response-validator';
chai.use(chaiResponseValidator('path/to/openapi.yml'));
describe('GET /example/endpoint', () => {
it('should satisfy OpenAPI spec', async () => {
const res = await axios.get('http://localhost:3000/example/endpoint');
expect(res.status).to.equal(200);
expect(res).to.satisfyApiSpec;
});
});
2. Write an OpenAPI Spec (and save to path/to/openapi.yml
):
openapi: 3.0.0
info:
title: Example API
version: 1.0.0
paths:
/example:
get:
responses:
200:
description: Response body should be an object with fields 'stringProperty' and 'integerProperty'
content:
application/json:
schema:
type: object
required:
- stringProperty
- integerProperty
properties:
stringProperty:
type: string
integerProperty:
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
:
{
status: 200,
body: {
stringProperty: 'string',
integerProperty: 123,
},
};
The assertion fails if the response body is invalid:
{
status: 200,
body: {
stringProperty: 'string',
integerProperty: 'invalid (should be an integer)',
},
};
Output from test failure:
AssertionError: expected res to satisfy API spec
expected res to satisfy the '200' response defined for endpoint 'GET /example/endpoint' in your API spec
res did not satisfy it because: integerProperty should be integer
res contained: {
body: {
stringProperty: 'string',
integerProperty: 'invalid (should be an integer)'
}
}
}
The '200' response defined for endpoint 'GET /example/endpoint' in API spec: {
'200': {
description: 'Response body should be a string',
content: {
'application/json': {
schema: {
type: 'string'
}
}
}
},
}
In unit tests, validate objects against schemas defined in your OpenAPI spec:
1. Write a test:
import chai from 'chai';
const expect = chai.expect;
import chaiResponseValidator from 'chai-openapi-response-validator';
import { functionToTest } from 'path/to/your/code';
chai.use(chaiResponseValidator('path/to/openapi.yml'));
describe('functionToTest()', () => {
it('should satisfy OpenAPI spec', async () => {
expect(functionToTest()).to.satisfySchemaInApiSpec('ExampleSchemaObject');
});
});
2. Write an OpenAPI Spec (and save to path/to/openapi.yml
):
openapi: 3.0.0
info:
title: Example API
version: 1.0.0
paths:
/example:
get:
responses:
200:
description: Response body should be an ExampleSchemaObject
content:
application/json:
schema: '#/components/schemas/ExampleSchemaObject'
components:
schemas:
ExampleSchemaObject:
type: object
required:
- stringProperty
- integerProperty
properties:
stringProperty:
type: string
integerProperty:
type: integer
3. Run your test to validate your object against your OpenAPI spec:
The assertion passes if the object satisfies the schema ExampleSchemaObject
:
{
stringProperty: 'string',
integerProperty: 123,
};
The assertion fails if the object does not satisfy the schema ExampleSchemaObject
:
{
stringProperty: 123,
integerProperty: 123,
};
Output from test failure:
AssertionError: expected object to satisfy schema 'ExampleSchemaObject' defined in API spec:
object did not satisfy it because: stringProperty should be string
object was: {
{
stringProperty: 123,
integerProperty: 123
}
}
}
The 'ExampleSchemaObject' schema in API spec: {
type: 'object',
required: [
'stringProperty'
'integerProperty'
],
properties: {
stringProperty: {
type: 'string'
},
integerProperty: {
type: 'integer'
}
}
}
Loading your OpenAPI spec (3 different ways):
1. From an absolute filepath (see above)
2. From an object:
import chai from 'chai';
const expect = chai.expect;
import chaiResponseValidator from 'chai-openapi-response-validator';
const openApiSpec = {
openapi: '3.0.0',
info: {
title: 'Example API',
version: '0.1.0',
},
paths: {
'/example/endpoint': {
get: {
responses: {
200: {
description: 'Response body should be a string',
content: {
'application/json': {
schema: {
type: 'string',
},
},
},
},
},
},
},
},
};
chai.use(chaiResponseValidator(openApiSpec));
describe('GET /example/endpoint', () => {
it('should satisfy OpenAPI spec', async () => {
const res = await axios.get('http://localhost:3000/example/endpoint');
expect(res.status).to.equal(200);
expect(res).to.satisfyApiSpec;
});
});
3. From a web endpoint:
import chai from 'chai';
const expect = chai.expect;
import chaiResponseValidator from 'chai-openapi-response-validator';
import axios from 'axios';
describe('GET /example/endpoint', () => {
before(async () => {
const response = await axios.get('url/to/openapi/spec');
const openApiSpec = response.data;
chai.use(chaiResponseValidator(openApiSpec));
});
it('should satisfy OpenAPI spec', async () => {
const res = await axios.get('http://localhost:3000/example/endpoint');
expect(res.status).to.equal(200);
expect(res).to.satisfyApiSpec;
});
});