npm

Ready to take your JavaScript development to the next level? Meet npm Enterprise - the ultimate in enterprise JavaScript. Learn more »

api-contract-validator

1.1.3 • Public • Published

npm Build Status Coverage Status Known Vulnerabilities style NPM

api-contract-validator

This is a plugin for validating API response schemas against Swagger/OpenAPI definition.

Using the plugin is easy. Simply point the plugin to your Swagger 2.0 or OpenAPIv 3.0 file and add one line to your integration test to validate that your application adheres to its design contract.

Highlights

  • Asserts according to API definitions document
  • Descriptive assertion failures
  • Simple and concise usage
  • Coverage report

How does it work?

The api-contract-validator transforms your API definition into a json-schema based on the provided API documentation file. Then whenever the matchApiSchema assertion is called, it automatically extracts the method, path and status code from the response object returned by the API request that you invoked and validates the response object. Both the response headers and body are validated.

How to use?

Installation

> npm i --save-dev api-contract-validator

Chai.js

const matchApiSchema = require('api-contract-validator').chaiPlugin;
const path = require('path');
const { expect, use } = require('chai');
 
// API definitions path
const apiDefinitionsPath = path.join(__dirname, 'myApp.yaml'); 
 
// add as chai plugin
use(matchApiSchema({ apiDefinitionsPath }));
 
it('GET /pets/123', async () => {
    const response = await request.get('/pet/123');
    expect(response).to.have.status(200).and.to.matchApiSchema();
 
    // alternatively pass
    const { statusCode, headers, body } = response
    expect({
        path: '/pet/123',
        method: 'get',
        status: statusCode,
        body: body,
        headers: headers,
    }).to.have.status(200).and.to.matchApiSchema();
})

Should.js

const matchApiSchema = require('api-contract-validator').shouldPlugin;
 
// API definitions path
const apiDefinitionsPath = path.join(__dirname, 'myApp.yaml');
 
// add as should plugin
matchApiSchema(should, { apiDefinitionsPath });
 
it('GET /pets/123', async () => {
    const response = await request.get('/pet/123');
    should(response).have.status(200).and.matchApiSchema();
})

Descriptive assertion failures

AssertionError: expected response to match API schema
+ expected - actual
 
{
    "body": {
-    "age": -1
+    "age": "should be >= 0"
+    "name": "should have required property"
    }
    "headers": {
-    "x-expires-after": []
-    "x-rate-limit": -5
+    "x-expires-after": "should be string"
+    "x-rate-limit": "should be >= 0"
    }
}

Coverage report

By providing in the plugin options, the flag reportCoverage:true, the plugin generates a report of all uncovered API definitions.

use(matchApiSchema({
    apiDefinitionsPath,
    reportCoverage: true
}));
* API definitions coverage report *
 
Uncovered API definitions found:
*ROUTE*                    | *METHOD*   | *STATUSES* 
/v2/pet                    | POST       | 405        
/v2/pet                    | PUT        | 400,404,405
/v2/pet/findByStatus       | GET        | 200,400    
/v2/pet/findByTags         | GET        | 200,400    
/v2/pet/:petId             | GET        | 400,404    
/v2/pet/:petId             | POST       | 405        
/v2/pet/:petId             | DELETE     | 400,404    
/v2/pet/:petId/uploadImage | POST       | 200         

Supported request libraries

  • supertest
  • axios
  • request-promise*
  • more to come

* When using request-promise resolveWithFullResponse:true must be added to the request options, in order to properly extract the request details

Supported assertion libraries

  • chai.js
  • should.js
  • more to come

install

npm i api-contract-validator

Downloadsweekly downloads

16

version

1.1.3

license

Apache-2.0

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar
  • avatar
Report a vulnerability