The sweetest fruit salad recipe for energy saving services
Chapter 8. Discoverable/Testable
(This story begins in Chapter 0. Launching an energy-saving rocket to the stars)
In this chapter we are describing two key aspects of our service:
- Discoverable: How we help consumers use it
- Testable: How we help consumers and other DEXMA developers work with it
1. Discoverable: API Documentation
Regarding the first goal, we want to provide a complete, concise and always-up-to-date API documentation.
We chose Swagger to automatically provide a bottom-up approach for generating service’s documentation. This approach ensures that documentation is always aligned with code since it is a mirror of the code, actually, it is generated from the code.
This is how it looks like:
We are not going to enter into the details of its configuration since there are lots of articles out there already. Let’s better focus on the second topic which usually doesn’t attract so much attention: A functional test suite which keeps aligned with the code…
2. Testable
Swagger does not provide a functional test suite that exemplifies the service with examples of requests and expected responses for both happy test cases and error scenarios. To completely describe service’s behaviour, we decided to design a Functional Test Suite in Postman based directly on the acceptance criteria of our user stories, closing this way the loop, from feature definition to test.
2.1. Functional Test Suite
In the example below, we show the test suite corresponding to a specific feature. As long as we have implemented the required scenarios of the features, we have been adding an exemplifying request and also recorded its response as a practical example.
We have also enforced the test suite with the expected functional test results, for each test case, as shown below:
But we want to go beyond, by not allowing the test suite obsolescence when the next developer visits the code. To enforce the test suite is up to date, we have included the Functional Test Suite as a step in our Software Development Lifecycle, meaning that any further change (that will come from an Acceptance Criteria) will become either an update to an existing Postman test case or a brand new test case inside the Functional Test Suite.
2.2. Load/Stress Test Suite
Maybe you are familiar with Postman, but have you ever tried Newman? Newman is the cli companion of Postman for running the load/stress tests. We decided to take advantage of the already created functional test suite to create a load test suite based on it.
Installation
As a prerequisite, you need NodeJS >= v6 and npm installed
npm install -g newman
npm install -g newman-reporter-html
newman --versionConfiguration
First we need to replace values by the properties that will help us to use different values on each request, as follows:
You can use a test values file (iterationData.csv in the example below) to define a set of values for the properties defined in your request. It is very useful, for instance, to send requests with different content, but it is a finite and static set of values. We prefer using the Pre-request script that gives complete control and define different values for each iteration.
Then, you can use the Pre-request Script to easily generate different values for each request, like in this example:
Execution
You can use either the URL or a local copy of the postman collection. For instance
newman run Our-StressTest.postman_collection.json --env-var "<ENVIRONMENT_VARIABLES>" --verbose -d iterationData.csv -r cli,json,junit,html -n <NUM_ITERATIONS>where:
ENVIRONMENT_VARIABLES are the variables defined in your Postman Collection, like for instance the URL you want to send the requests to
NUM_ITERATIONS specifies the number of times the collection will be executed
The option reporter-silent stops showing messages in your console, and only sends them to the reporting components
Once finished the stress test execution, it creates a set of reports under newman folder, like this one:
This trip ends in Chapter N. Time to enjoy the dessert
