Before we start, clone the code that is available at https://bitbucket.org/vfarcic/tdd-java-ch08-books-store. It is an empty project that we'll use throughout this chapter. As with previous chapters, it contains branches for each section, in case you miss something.

We'll write one BDD story that will be in a pure text format, in plain English and without any code. That way, all stakeholders can participate and get involved independently of their coding proficiency. Later on, we'll see how to automate the story we're writing.

Let us start by creating a new file called administration.story inside the stories directory:

We already have the narrative that we wrote earlier, so we'll build on top of that:

Narrative: 
In order to manage the book store collection efficiently 
As a store administrator 
I want to be able to add, update, and remove books 

We'll be using JBehave format for writing stories. More details regarding JBehave are coming soon. Until then, visit http://jbehave.org/ for more info.

A narrative always starts with the Narrative line and is followed with the In order to, As a, and I want to lines. We already discussed the meaning of each of them.

Now that we know the answers to why, who, and what, it is time to sit with the rest of the team and discuss possible scenarios. We're still not talking about steps (Given, When, and Then), but simply what would be the outlines or short descriptions of the potential scenarios. The list could be the following:

Scenario: Book details form should have all fields 
Scenario: User should be able to create a new book 
Scenario: User should be able to display book details 
Scenario: User should be able to update book details 
Scenario: User should be able to delete a book 

We're following the JBehave syntax by using Scenario followed by a short description. There is no reason to go into detail at this stage; the purpose of this stage is to serve as a quick brainstorming session. In this case, we came up with those five scenarios. The first one should define fields of the form that we'll use to administer books. The rest of the scenarios are trying to define different administrative tasks. There's nothing truly creative about them. We're supposed to develop an MVP of a very simple application. If it proves to be successful, we can expand and truly employ our creativity. With the current objective, the application will be simple and straightforward.

Now that we know what our scenarios are, in general terms, it is time to properly define each of them. Let us start working on the first one:

Scenario: Book details form should have all fields 
 
Given user is on the books screen 
Then field bookId exists 
Then field bookTitle exists 
Then field bookAuthor exists 
Then field bookDescription exists 

This scenario does not contain any actions; there are no When steps. It can be considered a sanity check. It tells developers what fields should be present in the book form. Through those fields, we can decide what data schema we'll use. IDs are descriptive enough that we know what each field is about (one ID and three text fields). Keep in mind that this scenario (and those that will follow) are pure texts without any code. The main advantage is that anyone can write them, and we'll try to keep it that way.

Let's see what the second scenario should look like:

Scenario: User should be able to create a new book 
 
Given user is on the books screen 
When user clicks the button newBook 
When user sets values to the book form 
When user clicks the button saveBook 
Then book is stored 

This scenario is a bit better formed than the previous one. There is a clear prerequisite (user should be on a certain screen); there are several actions (click on the newBook button, fill in the form, and click on the saveBook button); finally, there is the verification of the outcome (book is stored).

The rest of the scenarios are as follows (since they all work in a similar way, we feel that there is no reason to explain each of them separately):

Scenario: User should be able to display book details 
 
Given user is on the books screen 
When user selects a book 
Then book form contains all data 
 
Scenario: User should be able to update book details 
 
Given user is on the books screen 
When user selects a book 
When user sets values to the book form 
Then book is stored 
 
Scenario: User should be able to delete a book 
 
Given user is on the books screen 
When user selects a book 
When user clicks the deleteBook button 
Then book is removed 

The only thing that might be worth noticing is that we are using the same steps when appropriate (for example, When user selects a book). Since we'll soon try to automate all those scenarios, having the same text for the same step will save us some time by duplicating the code. It is important to strike a balance between the freedom to express scenarios in the best possible way and the ease of automation. There are a few more things that we can modify in our existing scenarios, however, before we refactor them, let us introduce you to JBehave.

The source code can be found in the 00-story branch of the tdd-java-ch08-books-store Git repository, at https://bitbucket.org/vfarcic/tdd-java-ch08-books-store/branch/00-story.