Have ideas to improve npm?Join in the discussion! »

    hippie-swagger

    3.3.2 • Public • Published

    hippie-swagger

    "The confident hippie"

    js-standard-style Build Status npm version

    Synopsis

    hippie-swagger is a tool for testing RESTful APIs. In addition to validating api behavior, it will fail tests when swagger documentation is missing or inaccurate.

    As the test suite runs, any request or response details not matching the swagger file will throw an appropriate exception, failing the spec. This ensures the swagger definition accurately describes application behavior, keeping documentation in sync with reality.

    hippie-swagger uses hippie under the hood, an excellent API testing tool.

    Features

    • All hippie features included
    • All aspects of swagger file validated; parameters, request/response body, paths, etc.
    • Checks for extra parameters, paths, headers, etc not mentioned in the swagger file
    • Ensures swagger file accurately describes API behavior
    • Accurate, human readable assertion messages

    Installation

    npm install hippie-swagger --save-dev
    

    Basic Usage

    var hippie = require('hippie-swagger'),
        swagger = require('./my-dereferenced-swagger-file'); // see example for how to dereference swagger
    
    hippie(app, swagger)
    .get('/users/{username}')
    .pathParams({
      username: 'cachecontrol'
    })
    .expectStatus(200)
    .expectValue('user.first', 'John')
    .expectHeader('cache-control', 'no-cache')
    .end(function(err, res, body) {
      if (err) throw err;
    });

    Usage

    • See hippie documentation for a description of the base api
    • When specifying a url(.get, .post, .patch, .url, etc), use the swagger path
    • Provide any path variables using pathParams

    These aside, use hippie as you normally would; see the example.

    Methods

    #constructor (Object app, Object swagger, Object [options])

    Test an HTTP app (like express) directly

    hippie(app, swagger, options)
    .get('/projects')
    .end(fn);

    #constructor (Object swagger, Object [options])

    Test a remote HTTP app using a fully qualified url

    hippie(swagger, options)
    .get('http://localhost:3000/projects')
    .end(fn);

    #pathParams(Object hash)

    Replaces variables contained in the swagger path.

    hippie(app, swagger)
    .get('/projects/{projectId}/tasks/{taskId}')
    .pathParams({
      projectId: 123,
      taskId: 99
    })
    .end(fn);

    Options

    To customize behavior, an options hash may be passed to the constructor. Typically, options only need to be specified in situations where the test covers responses to improper requests (e.g. validating the application returns a 422 when a required parameter is not provided).

    var options = {
      validateResponseSchema: true,
      validateParameterSchema: true,
      errorOnExtraParameters: true,
      errorOnExtraHeaderParameters: false
    };
    hippie(app, swagger, options)

    validateResponseSchema - Validate the server's response against the swagger json-schema definition (default: true)

    validateParameterSchema - Validate the request parameters against the swagger json-schema definition (default: true)

    validateRequiredParameters - Validate that required parameters were provided (default: true)

    errorOnExtraParameters - Throw an error if a parameter is missing from the swagger file (default: true)

    errorOnExtraHeaderParameters - Throw an error if a request header is missing from the swagger file. By default this is turned off, because it results in every request needing to specify the "Content-Type" and "Accept" headers, which quickly becomes verbose. (default: false)

    Example

    See the example folder

    Validations

    When hippie-swagger detects it is interacting with the app in ways not specified in the swagger file, it will throw an error and fail the test. The idea is to use hippie's core features to write API tests as per usual, and hippie-swagger will only interject if the swagger contract is violated.

    Below are list of some of the validations that hippie-swagger checks for:

    Paths

    hippie(app, swagger)
    .get('/pathNotMentionedInSwagger')
    .end(fn);
    // path does not exist in swagger file; throws:
    //    Swagger spec does not define path: pathNotMentionedInSwagger

    Parameter format

    hippie(app, swagger)
    .get('/users/{userId}')
    .pathParams({
      userId: 'string-value',
    })
    .end(fn);
    // userId provided as a string, but swagger specifies it as an integer; throws:
    //    Invalid format for parameter {userId}

    Required Parameters

    hippie(app, swagger)
    .get('/users/{username}')
    .end(fn);
    // "username" is marked 'required' in swagger file; throws:
    //    Missing required parameter in path: username

    Extraneous Parameters

    hippie(app, swagger)
    .get('/users')
    .qs({ page: 2, limit: 30 })
    .end(fn);
    // "page" missing from swagger file; throws:
    //    Error: query parameter not mentioned in swagger spec: "page", available params: limit

    Response format

    hippie(app, swagger)
    .get('/users')
    .end(fn);
    // body failed to validate against swagger file's "response" schema; throws:
    //    Response from /users failed validation: [failure description]

    Method validation

    hippie(app, swagger)
    .post('/users')
    .end(fn);
    // "post" method not mentioned in swagger file; throws:
    //    Swagger spec does not define method: "post" in path /users

    Post body format

    hippie(app, swagger)
    .post('/users')
    .send({"bogus":"post-body"})
    .end(fn);
    
    // post body fails to validate against swagger file's "body" parameter; throws:
    //    Invalid format for parameter {body}, received: {"bogus":"post-body"}

    Form Url-Encoded Parameters

    hippie(app, swagger)
    .form()
    .post('/users')
    .send({})
    .end(fn);
    
    // "username" is {required: true, in: formData} in swagger; throws:
    //    Missing required parameter in formData: username

    Multipart Forms

    hippie(app, swagger)
    .header('Content-Type','multipart/form-data')
    .send()
    .post('/users/upload')
    .end(fn);
    
    // "fileUpload" is {required: true, in: formData, type: file} in swagger; throws:
    //    Missing required parameter in formData: fileUpload

    Troubleshooting

    The most common mistake is forgetting to dereference the swagger file:

    "'Error: cant resolve reference ...'

    Dereferencing can be accomplished using swagger-parser. The example gives a demonstration.

    Contributing

    To run the hippie-swagger tests:

    npm test
    

    License

    ISC

    Install

    npm i hippie-swagger

    DownloadsWeekly Downloads

    379

    Version

    3.3.2

    License

    ISC

    Unpacked Size

    63 kB

    Total Files

    31

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar