# gherkin

## Gherkin Style Guide

Cucumber understands the language Gherkin. It is a Business Readable, Domain Specific Language that lets you describe software's behaviour without detailing how that behaviour is implemented.

Gherkin serves two purposes — documentation and automated tests. The third is a bonus feature — when it yells in red it's talking to you, telling you what code you should write.

## Anti-Patterns

Common problems we see in tests are

1. Too many Incidental details
2. Tests that make it hard to understand what is under test. The tests are either testing multiple things at the same time or not creating clear documentation for checking the desired behavior.
3. Lots of interface details. Scenarios that talks about going to a specific url, click a specific link, find an element using a specific css selector etc. Don't really tell us what the purpose of using the program is.

   This causes problems in both understanding the purpose of the test and also creates more maintanence as the user interface will typically change more frequently then the underlying domain level logic.

4. No clear seperation between [Given When Then ](https://github.com/cucumber/cucumber/wiki/Given-When-Then)

   We use the Given-When-Then approach to cucumber features. It should be followed as closely as possible:

   `Given` - Steps used to prepare the environment for the test, but that aren’t the tested interactions with the system under test.  
   `When` - Steps used to interact with the system under test. Avoid the use a passive voice in When steps. Instead of “a wav file is uploaded”, use “the client uploads a wav file to s3”. This helps to clarify what is actually happening in the step.  
   `Then` - Steps used to perform expectations and confirm that the tested interactions had the desired result.

   Examples can be found in our Automation best practices practices [guide](https://docs.google.com/document/d/1-M8R_SUNxUHbiF2fcR-gbKiYHharZMOKuVSbogjCvAk/edit#heading=h.qc7ylepgejec), or in the linked article.

### Double Edged Swords

These aren't necessarily bad but need to be used carefully.

1. Scenario outlines

   These can very easily be overused and lead to a slow test suite.

2. Multiple Then's in the same scenario

   Frequently this means a scenario is trying to validate multiple different business rules and could be split into separate scenarios.

### Anti-Pattern Articles

Here are a couple of good articles on common anti-paterns that we see

[Think-code Anti-patterns](http://www.thinkcode.se/blog/2016/06/22/cucumber-antipatterns)

#### Cucumber blog's take on anti patterns

[Podcast](https://cucumber.io/blog/2016/05/09/cucumber-antipatterns)

[Cucumber podcast text part one](https://cucumber.io/blog/2016/07/01/cucumber-antipatterns-part-one)

[Cucumber podcast text part two](https://cucumber.io/blog/2016/08/31/cucumber-anti-patterns-part-two)

#### Testing pyramid \(Where cucumber fits in\)

[Making end to end tests work](https://www.symphonious.net/2015/04/30/making-end-to-end-tests-work/)

[Martin Fowler on the testing pyramid](https://martinfowler.com/bliki/TestPyramid.html)

## Linting

We lint our Gherkin files using [Greener](https://github.com/theorchard/greener)

It can be run by running `rake gherkin:greener`