Nincompoops Producing Methane

    api-contract-validator
    TypeScript icon, indicating that this package has built-in type declarations

    2.2.8 • Public • Published

    npm npm Build Status Coverage Status Known Vulnerabilities style NPM

    api-contract-validator

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

    Using the plugin is easy. Simply point the plugin to your API definitions file path 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 (can be printed to your terminal or exported to a json file)
    • Supports response format from axios, superagent, supertest, request and light-my-request (used by fastify)
    • Supports OpenAPI 3.0
    • Supports multiple definition files

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

    Jest

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

    Multiple api definitions files

    use apiDefinitionsPath option with an array of files paths

    const apiDefinitionsPath = [path.join(__dirname, 'myApp.yaml'), path.join(__dirname, 'myApp2.yaml')];

    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         

    Exporting the report:

    When providing exportCoverage: true a coverage.json file will be created in your cwd with following structure:

    use(matchApiSchema({
        apiDefinitionsPath,
        exportCoverage: true
    }));

    coverage.json:

    [{"route":"/v2/pet","method":"POST","statuses":"405"},
    {"route":"/v2/pet","method":"PUT","statuses":"400,404,405"},
    {"route":"/v2/pet/:petId","method":"GET","statuses":"200"},
    {"route":"/v2/pet/:petId","method":"POST","statuses":"405"},
    {"route":"/v2/pet/:petId","method":"DELETE","statuses":"404"}]

    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
    • jest
    • more to come

    Install

    npm i api-contract-validator

    DownloadsWeekly Downloads

    4,507

    Version

    2.2.8

    License

    Apache-2.0

    Unpacked Size

    45.6 kB

    Total Files

    24

    Last publish

    Collaborators

    • kobic
    • idanto