During the last week I came across an interesting success case in my software development experiences: “self -generated contracts validation and API tests using Swagger specs…”
I agree, writing enough tests to guarantee high “lines and cases coverage” levels require a lot of effort and will usually drain developers energy and motivation…
In this article, I want to share with you a technique that will highly reduce the overhead of APIs development and later integration testing in Node.js, using Swagger, Express.js and OpenAPI Test Templates.
Your API implementation should start with your Swagger Spec
But, what is Swagger?
Swagger is an open-source software framework backed by a large ecosystem of tools that helps developers design, build, document, and consume RESTful Web services. While most users identify Swagger by the Swagger UI tool, the Swagger toolset includes support for automated documentation, code generation, and test-case generation.
Swagger is also known as OpenAPI.
Building our Swagger Spec
Using the existing open-source tools to build Swagger Specs is rather simple. Let’s take the following example as our project use case:
You can read the complete Swagger Specification v2 here: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
I have my Swagger based API spec, now what?
In this article we are gonna be using the awesome swagger-express-middleware, among other features you have:
- Supports Swagger 2.0 specs in JSON or YAML
- Thoroughly tested
- Mock middleware
- Metadata middleware
- Parse Request middleware
- Validate Request middleware
- CORS middleware
- Files middleware
You can explore more details here: https://www.npmjs.com/package/swagger-express-middleware#features
Mock your API
Once you have defined you API, there is no need to block frontend teams from starting their development, just right away you can expose your HTTP service, mocking all endpoints according to the Swagger Spec:
Implement your endpoints
Now is time to implement your endpoints with real business work-flows. For the purpose of simplicity, in this example we only have to implement the GET /pets endpoint and respect the response schema:
Generate and execute API tests using the Swagger Spec as your contract reference 🚀
Now is the time to create “magic”, let’s generate and execute integration tests using the API contracts defined in the Swagger Spec. To do this we are gonna use the oatts module, and yes, it is very simple:
First things first:
Swagger is great!
In the enterprise world, we usually require to start documenting API contracts before any implementation starts. Here, Swagger is the number 1 tool for that.
Therefore we might not be surprise why the Node.js frameworks also ship-in plugins for integrating our APIs with it:
- https://www.npmjs.com/package/swagger-express-middleware Express.js
- https://www.npmjs.com/package/hapi-swaggered Hapijs
- https://www.npmjs.com/package/fastify-swagger Fastify
- … the list is big!
In this article we have described a quick trip from documentation, mocking, implementation and testing.
Of course, for the purpose of simplicity we have used a minimalist API with just one endpoint; but I can guarantee you that the oatts will generate all possible tests according to your Swagger Specs.
It also allows you to attach custom values for complex tests workflows… https://github.com/google/oatts#custom-values
Also remember, oatts ensures the responses from your API endpoints match the expected contract.
Finally, you can find a fully working demo at: https://github.com/jkyberneees/swagger-api-tests