Feature tests are written to test the behavior of the software and not its implementation. It is written in business friendly, domain language as far as possible. Gherkin is a language used commonly to write feature tests with cucumber as the framework that executes the feature tests. I use gherkin/cucumber for writing feature tests and as far as this post is considered I will use gherkin tests and feature tests interchangeably.

The use of gherkin tests as executable documentation is a fairly known idea. What I realized recently was the not only are these tests executable documentation but they are also interactive documentation. So lets take an example of a feature test that tests the conversion of inventory quantity of a product into inventory level.

Feature: Convert inventory quantity for a product into inventory level

Given that the inventory quantity for a product with SKU “1234567890123” is “10”
And the inventory level is “in stock” when the quantity is between “5” and “3”
And the inventory level is “low” when the quantity is between “2” and “1”
And the inventory level is “out of stock” when the quantity is between “0” and “0”
When I convert the inventory quantity for SKU “1234567890123” into its inventory level
Then the inventory level for SKU “1234567890123” is “in stock”

Now this feature gives me a fairly good idea of what the business expects and how the feature should be implemented. If I make a change to the code for this feature, and I run my test and the test passes most likely I haven’t broken anything. Executable documentation FTW!

To take this a step further, what I can do with this feature test is, interact with it. Lets say I am wondering how the code handles boundary condition. I could very easily change the quantity in the Given from 10 to 3 and observe what happens.

Given that the inventory quantity for a product with SKU “1234567890123” is “3”
And the inventory level is “in stock” when the quantity is between “5” and “3”
And the inventory level is “low” when the quantity is between “2” and “1”
And the inventory level is “out of stock” when the quantity is between “0” and “0”
When I convert the inventory quantity for SKU “1234567890123” into its inventory level
Then the inventory level for SKU “1234567890123” is “in stock”


If I get the same answer as before which is in stock then it seems the code is working correctly for boundary condition as well, where as if it is not then we have a bug.

I hope this non-trivial example has been useful to understand what I mean by interactive documentation. I have found this “tweaking” of tests to be very useful to understand how the code works or should work.

For a long time, I thought that if the product owner/business analyst is not involved in writing the feature tests then these tests are an overhead. But of lately, I have been of the opinion that these tests are useful even for developers. If you are someone like me who jumps between different code bases frequently then these tests help come up to speed quickly with the business functionality without having to worry about the implementation/code. Also, as mentioned in the example above, I can interact with these tests to validate existing/new behavior quickly. The importance of writing these tests in a easy to understand, domain language cannot be overstated.