Writing feature files from Zero to Hero. Part 1
Tags: bdd, gherkin, feature
Published: 2020-08-20 15:37:49

## Context

This article is an introduction to getting Gherkin all the way from User Story.


## What is a gherkin file?
*Gherkin is a Business Readable, Domain Specific Language created especially for behavior descriptions. It gives you the ability to remove logic details from behavior tests. Gherkin serves two purposes: serving as your project’s documentation and automated tests.*[Credit Behat Documentation]

a Gherkin file is defined by two elements a structure and a set of keywords.

here a basic example:

```gherkin
Feature: I want to deposit in my account
  
 Scenario: deposit money in my account;
    Given I have a bank account with balance 5000
    When I am depositing 2000 in my account
    Then my balance must be 7000
```

the key `Feature` defines what your business needs about.
A scenario defines one simple use case it can be a sunny one or even an edge case.
 the rule is to have : 
one or several input(s)/ initial state (`Given` Clause).
one Call/ user interaction to the system/feature (`When` clause) 
multiple expected results (`Then` Clause)

if you’d to go deeper here the [link](https://cucumber.io/docs/gherkin/reference/).

## From User Story to Feature file.

### What is a user story?

![user story](https://images.unsplash.com/photo-1519791883288-dc8bd696e667?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1950&q=80)

User stories are short, simple descriptions of a feature told from the perspective of the person who desires the new capability, usually a user or customer of the system. 

They typically follow a simple template:

**_As a < type of user >, I want < some goal > so that < some reason >._**

*User stories are often written on index cards or sticky notes, stored in a shoebox, and arranged on walls or tables to facilitate planning and discussion.* [Credit Mike Cohn Contributor to Scrum Method]

Example:
_As a Customer, I want to deposit money so that can save me money._


### Example Mapping.

Usually, as developers, we start developing from a user story to start “the work”.
In my opinion “the work” should start away before.
why? because simply we can’t evaluate what needs to be done accurately.

one of the approaches to get there is:
- identify the story.
- identifying business rules of the user story.
- Creating concrete examples based on business rules for the user story.

this approach is called **Example mapping**.

Example mapping is a workshop that permits to get from a user story a multiple concrete 
examples.

the **Example Mapping** workshop goes in this order :
- writing the **user story** and put it in the most upper place of the board using a **yellow card**.
- writing the **acceptance criteria** or **rules** that we already now just under the user story using **blue cards**.
- for each **acceptance criteria** or **rules** write a or **multiple scenarios examples** illustrating it **using green cards**.
- sometimes we have **unanswered questions** so we put on board using **red cards**.

the result should be like this :

![example mappings](https://cucumber.io/cucumber/media/blog/ghost/map.png).

if you'd like to go further on the example mappings workshop.
[here](https://cucumber.io/blog/bdd/example-mapping-introduction/) an excellent of Matt Wynne. 

in the future post I'll talk about writing gherkin files well and all the traps that I've been through in my career.


Credit for the pictures
[unsplash](https://unsplash.com/)
[cucumber.io](https://cucumber.io/)