Swagger for definition and REST API testing

Testing as cli application

$ npm install -g driven-swagger-test
$ driven-swagger-test

Usage: driven-swagger-test <JSON or YAML Swagger file definition> [options]

Create Postman collection with test from swagger

Options:
  -v, --version              output the version number
  -g --global [var]          Add global variables (default: [])
  -r, --run [dataFile]       Run postman collection using newman cli.
  -s, --save                 Save postman collection to disk
  -t, --tokenUrl [tokenUrl]  Override token url in swagger.
  -h, --help                 output usage information

Usage in node applications as integration test

$ npm install driven-swagger-test --save-dev

const swaggerTests = require('driven-swagger-test/src/swagger');
const server = require('./server');

describe('Swagger definition to Postman test', () => {
  before(done => {
    // Run your REST API Server
    server.run(() => {
      console.log('Server is running');
      done();
    });
  });

  it.only('Pet Store run all', async () => {
    try {
      const results = await swaggerTests(`${__dirname}/swaggers/petstore-swagger.yaml`, {
        run: `${__dirname}/data.json`,
        save: true
      });

      console.assert(!results.tests.definition.some(result => result.code >= 5000), 'Errors in test.');
    } catch (error) { throw error; }
  });

  after(done => {
    server.stop(() => {
      done();
    });
  });
});

Why definition test?

Becouse API-First definition, is better with test

• Do you have security in operations? Your response should be contain 401 (unauthorized)!
• Do you have GET operation? You should be contain consumes (accept) definition.
• Do you have any param in PATH? Your response should be contain 404 (not found)!
• Do you have POST/PUT/PATCH operation? Your response should be contain 400 (bad request)!

These are just some of the many test included in this tool.

REST API testing directly in Swagger!

Vendor extension x-pm-test for test (These can be specified for any response, except default.)

responses:
  200:
    description: "successful operation"
    schema:
      type: "array"
      items:
        $ref: "#/definitions/Pet"
    x-pm-test:
    - params:
      - name: status
        in: query
        value: '{{status}}'
  400:
    description: "Invalid status value"
    x-pm-test:
      - params:
        - name: status
          in: query
          value: 'aaaaaa'

x-pm-test object representation

• x-pm-test (array, optional) - Tests array.
  • description (string, optional) - Description used in postman endpoint name.
  • params (array, optional) - Define parameters values in test
    • name (string, required) - Param name. Required to all parameters, except body.
    • in (string, required) - The location of the parameter. Possible values are "query", "header", "path", "formData" or "body*".
    • value (string, required) - Value to fetch in parameter
  • plugins (array, optional)
    • name (string, required) - Plugin name to use
    • params (object) - Object to define parameters to plugin
  • raw (string, optional) - Define your custom postman test.

YAML example

x-pm-test:
- description: Get pets by status
  params:
  - name: status
    in: query
    value: '{{status}}'
  plugins:
    - name: valueCheck
      params:
        item: 'id'
        value: 0
    - name: isArray
      params:
        item: 'tags'
    - name: isObject
      params:
        item: 'category'

Integration test on wiki

Special thank you

To Marco Antonio Sanz and CloudAppi for the whole idea.

TODO:

1. Refactoring
2. Clean code
3. Use external plugins
4. More defaults definition test
5. More defaults integration test
6. Support Swagger 3.0 (Aka. Open API)
7. Better documentation