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 = ; var options = // see "Options" section below for available options; var tests = oatts; console
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
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 filepathLevel.handlebars
: the path level template, usually the beginning of a test suite for a specific pathoperationLevel.handlebars
: the operation level template, for a single operation test suitetransactionLevel.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:
Name | CLI Flag | Default | Required | Description |
---|---|---|---|---|
spec |
--spec -s |
n/a | true |
Path to a swagger.yaml or openapi.yaml |
host |
--host |
spec.host |
false |
Hostname to put in test requests; defaults to host in given spec |
paths |
--paths -p |
spec.paths |
false |
API paths to generate tests for; defaults to all paths in given spec |
samples |
--samples -e |
false |
false |
Toggle generating sample responses for assertion |
writeTo |
--writeTo -w |
n/a | false |
Directory to write generated tests to; will create the directory if it doesn't exist |
consumes |
--consumes -c |
operation.consumes[0] | | spec.conumes[0] |
false |
Consumes header to use in a request when applicable |
produces |
--produces -o |
operation.produces[0] | | spec.produces[0] |
false |
Produces header to use in a request when applicable |
customValues |
--customValues -u |
n/a | false |
Values to be populated in requests where specified; overrides customValuesFile |
customValuesFile |
--customValuesFile |
n/a | false |
Path to a JSON file with values to populate in requests |
scheme |
--scheme -m |
spec.schemes[0] |
false |
Override for multiple scheme present in a spec |
templates |
--templates -t |
'./templates' |
false |
Path to directory containing custom templates |
statusCodes |
--status-codes -S |
operation.responses |
false |
comma separated list of status codes to explicity generate tests for |
jsonRefs |
n/a | false |
(See JsonRefs~JsonRefsOptions) | |
customFormats |
n/a | false |
The key/value pair of custom formats (The keys are the format name and the values are async functions. See ZSchema Custom Formats) | |
customFormatGenerators |
n/a | false |
The key/value pair of custom format generators (The keys are the format name and the values are functions. See json-schema-mocker Custom Format) | |
customValidators |
n/a | false |
The custom validators. See DocumentValidationFunction |
Testing
To test this module simply use the npm
script
npm test
Contributing
Contributors are welcome! Please see CONTRIBUTING.md.
License
See LICENSE file.