Swagger Test Templates: Test Your APIs

The power of Swagger to accelerate API development is obvious once you read the article "A Design-First Approach to Building APIs with Swagger." While there are a variety of tools built around Swagger for the development of APIs, testing an API can be just as important. Writing tests for a large set of endpoints takes a lot of time and thought, which is why we built Swagger Test Templates, in conjunction with Swagger Node.

The Swagger Test Templates module, through either the command line interface or programmatically, generates a robust, end-to-end testing suite for all of a developer’s API endpoints defined in their Swagger specification. This saves hours of test writing and enables the developer to quickly deploy tested, functional code.

Generating test code: Handlebars JS

The first big decision was choosing the system for generating valid JavaScript code for tests from templates. We chose Handlebars JS, a powerful JavaScript library that builds versatile templates based on the Mustache templating language. In addition to having a very simple and approachable syntax, Handlebars provides various helper functions capable supporting iteration, conditionals, and partials.

Handlebars also provides an invaluable piece of functionality: the ability to write custom helper functions in JavaScript. This kept our templates from becoming bloated with conditional logic—by abstracting that logic into a custom helper, trimming down our templates, and reusing the helper in multiple places.

Testing framework: Mocha JS

Templates aren't useful without a testing framework. We chose Mocha JS for its simple organization, descriptive structure and output, and its ability to implement asynchronous tests very easily (it's just a matter of providing and calling a simple built-in callback).

For our assertion library, we chose Chai JS, which gave us should, expect, and assert. Requiring a specific assertion library was too great a constraint, however, so we exposed this as an option. The templates enable the assertion format to be passed as a configuration option, eliminating the need for a customized file for each format.

Finally, because Swagger defines REST APIs, testing requires sending real requests, potentially hitting a live production server. To do this, we decided to support both the request and supertest Node.js modules, as they're both popular but also very different. Instead of asking Handlebars to handle the heavy lifting and to support the two very different module implementations in one template, we created two sets of templates, with support for all the REST operations supported in the Swagger spec. While this added some maintenance overhead, it was a fairly low up-front investment.

Building the CLI: Commander JS

Swagger Node provides a CLI for building and managing your API, and our goal here was to extend the interface and enable the developer to generate tests with the desired options in one command.

To achieve this, we used Commander JS, which is designed to help build the CLI and also provides great features to cope with options and arguments. The first option is the test-module, and, as mentioned above, we provide support for both supertest and request. Chai provides three different assertion formats that all can be implemented through a single option. Combine this option with one that enables selective path test generation through naming or regular expression, and you can mix and match your assertion formats.

In the event of a massive rework of the API, there’s the option to force the overwrite of all generated test files; otherwise, there’ll be a prompt for each conflicted file that needs to be resolved. For the convenience of the developer, we implemented dependency injections, so that running swagger project generate-test will automatically install the necessary modules to run the tests.

Demonstration

Create a basic "Hello World" project and follow this to generate your tests. First, navigate to the project folder. Here we choose "request" as our test module:

swagger project generate-test -f request

Here are the initial and final states, before and after running the generate-test command:

Next, we need to fill in the empty data in our generated files (here is hello-test.js):

Last step: start the server, run your tests, and you're done!

swagger project start

npm test

Future work

We're excited about this first release, but this is only the beginning. The next challenge is to populate security properties by adding support for three security schemas: HTTP basic authentication, an API key, and OAuth2. It will parse the security schema, generate the security configuration file, and populate them into the testing suite. This will enable developers to test their APIs against a live, secure, production deployment.

We also plan to add data population support. An environment file will be generated that would contain values for each property of the specification model definitions or path parameters. This will further minimize the amount of manual parameter entry required by the developer.

By releasing Swagger Test Templates as an open source project, we are contributing back to the community and helping to make the Swagger API framework even stronger. Visit the  GitHub page to learn more or get involved.

The Swagger Test Templates project is the culmination of the hard work of Apigee interns Linjie Peng and Noah Dietz.