swagger-police

swagger-police is a command line tool for validating backend APIs against the published swagger specification. It can be plugged into a continuous integration system to ensure that the backend APIs confirms to the behaviour mentioned in the published swagger specification.

This library is very similar (and inspired) from abao (https://github.com/cybertk/abao) which does similar validations for a RAML spec

Please Note: The library is still in beta and is WIP !

Features

• Calls every API defined in the swagger file by generating mock data from the specs (data can be customised, see usage). This ensures that the url params, query params, headers and the body defined in the spec is supported by the service.
• Verifies the HTTP response status and headers agaisnt the specs.
• Verifies the response body against the schema defined in specs (JSON schema validation).
• Supports the following hook methods for customising the tests (see Hooks)
  • BeforeAll
  • AfterAll
  • BeforeEach
  • AfterEach
  • Test specific Before and After

Installation

npm install -g swagger-police

Usage

$ swagger-police

  Usage: swagger-police <swagger URL/path> [options]

  Options:

    -h, --help                        output usage information
    --server [server]                 The API endpoint
    --hook-files [hookFiles]          Specify pattern to match hook files
    --testcase-names [testcaseNames]  Print all the testcase names (does not execute the tests)

• Swagger URL/path - The path or the URL to the swagger file
• Server - The API endpoint base url. No need to specify this if a swagger url is specified and the APIs are hosted in the same server.
• Hook Files - A glob pattern (reletive to the execution directory) to load the hook files.

Hooks

The tool supports the following test hooks to enable setup/tear-down tasks or customising the individual tests. Hooks are simple JavaScript files which have access to a global hooks object with methods to add the specific hooks.

BeforeAll and AfterAll

These will be executed once before the tests start and after all the tests have been executed. Note that only one of each type can be specified, there cannot be more than one beforeAll/afterAll hooks. However, testcase specific hooks can be specified, see below.

hooks.beforeAll((testcases, done) => {
    done();
});

hooks.afterAll((testcases, done) => {
    done();
});

• testcases - An array of testcase objects to be executed. This is generated from the swagger specs. Any customisations made to the objects in the beforeAll hook will be reflected in the tests.
• done - The callback function

BeforeEach and AfterEach

These will be executed before and after every test. Note that only one of each type can be specified, there cannot be more than one beforeEach/afterEach hooks. However, testcase specific hooks can be specified, see below.

hooks.beforeEach((testcases, done) => {
    done();
});

hooks.afterEach((testcases, done) => {
    done();
});

• testcases - An array of testcase objects to be executed. This is generated from the swagger specs. Any customisations made to the objects in the beforeAll hook will be reflected in the tests.
• done - The callback function

Testcase specific hooks

before and after testcase specific hooks can be specified which will only be executed before and after the specific testcase. The testcases are identified using a generated name. Run the tool with the --testcase-names option to print out all the testcase names.

The hooks can be specified using the following method

hooks.add('GET /pet/{petId} -> 200', {
    before: (testcase, done) => {
        done();
    },
    
    after: (testcase, done) => {
        done();
    }
});

• 1st Argument - The testcase name. Please note that this is case sensitive.
• 2nd argument - An object with before and after functions which takes in testcase (The testcase object representing the specific test) and a callback. Any modifications made to the testcase object will reflect in the test.

If more than one such hook is specified for a specific test, the test will be executed once for every hook specified. Custom test name can be added to identify each pass. See below

hooks.add('GET /pet/{petId} -> 200 # Pass 1', {
    before: (testCase, done) => {
        done();
    },
    
    after: (testCase, done) => {
        done();
    }
});

hooks.add('GET /pet/{petId} -> 200 # Pass 2', {
    before: (testCase, done) => {
        done();
    },

    after: (testCase, done) => {
        done();
    }
});