OpenAPI Test Templates for cypress (oatts-cypress)

Generate basic cypress snapshot test scaffolding for your OpenAPI specification.

Disclaimer

oatts-cypress is based off of the oatts module and the lessons learned during its development.

This is a work in progress.

Goal

The goal of oatts-cypress is to provide a standalone module for generating cypress snapshot test code scaffolding based on a given OpenAPI specification.

The hope is that by providing such a tool, API developers will be encouraged to test the contract between their spec and backend early, often and continuously as the project grows.

Usage

There are a couple ways to use oatts-cypress.

Module

Install via npm

npm install --save oatts-cypress

Then use it in code

var oatts = require('oatts-cypress');
 
var options = {
    // see "Options" section below for available options
};
 
var tests = oatts.generate('/path/to/openapi.yaml', options);
 
console.log(tests)

Command line interface

Install globally via npm

npm install -g oatts-cypress

Then use in your command line

> oatts generate --help
 
  Usage: generate [options]
 
  generate unit test scaffolding for a given OpenAPI/Swagger Spec
 
  Options:
 
    -h, --help                             output usage information
    --host <host>                          target hostname to use in test generation
    -p, --paths <paths>                    comma separated list of paths to generate tests for
    -e, --samples                          generate sample response bodies rather than schema, if applicable
    -s, --spec <spec>                      path to the target OpenAPI/Swagger spec document to consume
    -w, --writeTo <writeTo>                directory to write the generated tests to file
    -c, --consumes <consumes>              consumes/content-type to use in request when applicable to the API resource
    -o, --produces <produces>              produces/accept to use in request when applicable to the API resource
    -u, --customValues <customValues>      custom request values to be used in generation; takes precedent over a customValuesFile
    --customValuesFile <customValuesFile>  path to JSON file with custom request values to be used in generation
    -m, --scheme <scheme>                  which scheme to use if multiple are present in spec
    -t --templates <templateDir>           path to direcotry of custom templates
    -S, --status-codes <statusCodes>       comma separated list of status codes to explicity generate tests for
 
> oatts generate -s ./path/to/openapi.yaml -w ./output/dir
> ls ./output/dir
pet-test.js  pet-{petId}-uploadImage-test.js  user-test.js 
. . .

Using the result

The resulting test files are built using the cypress snapshot

Please follow the above link to setup your cypress project after generating the tests

Custom Values

Custom values can be supplied through both the command line and a JSON file. The in-line, command line supplied JSON will take precedent.

An example custom values JSON file can be found here.

Custom Templates

Custom templates can be supplied via the templates option. The directory pointed to by the option must contain 4 Handlebars templates named the same way as those found in ./templates.

• topLevel.handlebars: the top level template for a single test file
• pathLevel.handlebars: the path level template, usually the beginning of a test suite for a specific path
• operationLevel.handlebars: the operation level template, for a single operation test suite
• transactionLevel.handlebars: the template for a single transaction, or a single response code's unit test

The data available to be used in the templates is specified in the ProcessedSpec type.

There are also a few helpers available to be used in the Handlebars templates, which can be found in the templateHelpers documentation namespace. Use the default templates as examples of how to use them.

Options

The following options can be passed to the generation function, some/all are exposed in the accompanying CLI:

Testing

To test this module simply use the npm script

npm test

Contributing

Contributors are welcome! Please see CONTRIBUTING.md.

License

See LICENSE file.