In one of my previous posts on the topic of functional testing, Blackbox Testing Microservices, I gave an explanation how we created a separate application which uses REST client to communicate with the main application, thus giving it a kind of input and waiting for a response to verify it. That post is followed by story about WireMock and external dependencies in Graybox Testing blog post. This post will be built on top of that by adding Cucumber to the equation, which improves readability and collaboration with business people.
Cucumber is a great tool which enables developers to write scenarios, in plain English business language, and framework translates it to method calls based on the given rules. It follows a Gherkin notation (given/when/then) which is nice for documenting prerequisites, doing actual call and testing outcome. Also, a nice feature is Before annotation which can be used to bring the application before scenario to some desired state, it works sort of like JUnit Before and After annotations. For more details about Cucumber please check the official site.
We started by building flows to our functional testing application and it became hard to follow it through code separated in a lot of classes divided in a lot of packages. Also, we had a hard time keeping ourselves on the same page when describing the features, either among us or when talking to business people. We realised that functional testing application could be a great source of documentation, since it already captured the main application flows. There was only one problem, all of that was buried deep in code. We explored a couple of options and settled with Cucumber. We sort of did the opposite of what was supposed to be done, since you should first define the scenario in plain business language and then generate method calls and implement the code in each step. Since we had the code, we needed to build scenarios out of this code and structure the code in small self-explanatory steps. This made it much harder, since we had built a lot of features already in the code and they were interdependent. After a while we managed to do so, and this is the outcome of our upload CSV flow (not an exact copy of it but it paints the picture).
Given products CSV file for organization X
When CSV file is uploaded to FTP server.
Then the API call for organization X returns newly added products.
It is plain and simple, nicely catches the flow we are testing, and documents the feature in a way everyone will understand (both technical and nontechnical people). We added more scenarios, testing both happy path and error cases. After we had finished we had a full coverage of CSV upload functionality both through tests and documentation. This was a starting point for new developers ready to work on this functionality, since they could understand how a feature should look like.
Cucumber and such tools add great value to the project. All projects that I worked on struggled with good documentation. It was either non-existent or it was outdated since it is hard to always update documentation when you change code. This approach brings the best of two worlds, it keeps documentation close to code and it is written in a way everyone will understand. It is important not to go overboard with details when writing scenarios, and the best way to do this is to try to imagine you are a business guy reading this.