Gherkin Tests Guidelines

Gherkin is a particular language that originates from Behavioral-Driven Development (BDD). In BDD, the developer defines tests that will guide the development and constitute a requirement. The tests are written by first defining the feature that is going to be tested, then defining the most relevant execution paths for that feature, called scenarios, and, finally, detailing the scenarios into simple steps using Gherkin language.

Features

Every Gherkin test should test a specific feature. Every tested feature is contained in a single test class.

An example of feature for the H2DbWireStoreComponent can be “Store wire envelopes“ and the corresponding test class will be StoreWireEnvelopeTest.java.

Guidelines for defining features:

• group features for a specific component in the same test package
• if it is not easy to define a simple name that describes the feature, then maybe it is too complicated and needs to be split into multiple features
• if the tested component is simple, then use the existing naming convention: ComponentNameTest

Scenarios

Scenarios break down the single feature into steps. Each scenario covers a path of execution for that feature and is identified by a method inside the feature class.

As an example for the H2DbStoreComponent, one can think of a scenario “Successful store data“ which will correspond to the method successfulStore(), but also of a scenario that should cause an error like “Store in a DB table that does not exist“.

Guidelines for defining scenarios:

• try to define also the unhappy paths, i.e. paths that cause errors
• methods that define scenarios do not return values, do not have parameters, and should be annotated with JUnit’s @Test annotation
• the method name should describe the scenario as better as possible; no comments should be needed to understand it; else, break it down into multiple ones
• no nested scenarios
• scenarios should be placed on top of the class, it is the first and only thing that a developer should read to understand the test

Steps

Steps detail scenarios further. Scenarios contain multiple steps that follow a specific pattern. Steps can be defined using one of these keywords:

given - when - then

• given defines the test preconditions, an initial context
• when defines the actions performed, or events
• then describes the effects, the expected outcome

Guidelines for defining steps:

• step methods must be private and separated from the scenarios: public scenarios on top, private steps on the bottom
• steps inside a scenario always follow the given-when-then order
• step methods names must start with one of the keywords
• there can be multiple steps of the same kind inside a single scenario, i.e. 3 given, 1 when, 2 then; to improve readability separate them with a blank line to form a group for the given steps, one for the when steps, and one for the then steps
• steps can take arguments
• steps do not return values
• step methods contain asserts

Example of a scenario with steps:

@Test
public void storeOnNotExistentTable() {
  givenDatabaseConnection();
  givenConfigurationWithWrongTableName();
  
  whenWireEnvelopeArrives();

  thenThrowException();
  thenDataNotStored();
}

Internal State and Helpers

Since step and scenario methods are not allowed to return any value, it is sometimes necessary to maintain an internal state inside the feature class. Where the tested features require complex dependencies, it might be useful to define an abstract helper class which will be inherited by all the feature classes.

The Gherkin reference: https://cucumber.io/docs/gherkin/reference/

Example unit test implementation: https://github.com/eclipse/kura/blob/develop/kura/test/org.eclipse.kura.log.filesystem.provider.test/src/test/java/org/eclipse/kura/log/filesystem/provider/FilesystemLogProviderTest.java

Example integration test implementation: https://github.com/eurotech/com.eurotech.framework.modbus/blob/feature_abb-scale-offset/tests/org.eclipse.kura.driver.modbus.provider.test/src/main/java/org/eclipse/kura/driver/modbus/provider/test/ScaleOffsetTest.java