|
How to write stories
Some BDD systems enforce a strict syntax on the stories you write with a customer. Some enforce none. Simon is somewhere between the two, using a basic structure which falls in line with common practives in the BDD community.
Stories are written in plan text files with a .stories extension Here’s an example:
File: example.stories
Story: Example story showing the basic syntax.
Given Simon is working
Then I should be able to see abc and 5 in the log
and say goodby at the end.
Thats pretty simple. The Story: … line gives the story a name. The rest of the lines outline the story and what is expected. Simon does impose some rules about the first word on each line. Ultimately it doesn’t matter, but by imposing some simple rules, it helps to structure and understand the stories. Yes you can have more than one per file. Here’s an outline of the syntax rules:
- Each story must start with a line that begins with the word story or story:. Simon uses this line as the title of the story for reporting.
- This is followed by the story lines and must follow this structure:
- As … (optional) Usually present if you are wanting to express the story in reference to a particular user or part of the system. For example “As a customer”, “As the server”, “As a Blue Superhero”, etc.
- Given … This is the starting point of the story. For example “Given the interface is up”, “Given I have logged in”, “Given the movie has finished”, etc.
- And … (zero or more) The Given … And sequence gives you the ability to qualify the Given statement with one or more criteria. So “Given I have logged in And have added a new record” is a good example.
- When … (zero or more) here is where you express some action you would like to occur. For example “When I click the button”.
- And … (zero or more) Like the Given … And sequence, the When … Add sequence gives you the ability to add further actions to check. ie. “When I enter some text and click the button” is one example.
- Then … (zero or more) here is where you express what you expect. It could be some action or more likely, something you can check to verify that the application has performed as expected. For example “Then the button should say ‘Hello’”, “Then the 2nd field should be editable”, etc.
- And … (zero or more) The Then … Add sequence gives you the ability to add further criteria to check. ie. “Then the switch should be down And the light should be on” is one example.
Here are some examples of stories:
File: MyDatabaseApp.stories
Story: Adding a record shows the new record screen
Given I an on the second page
When the "Add" button is tapped
Then the new record screen should be visible
Story: Adding a record requires a name.
Given I an on the second page
and the new record screen is visible
When the "Add" button is tapped
Then tap the "Save" button
and check for an error message
Story: Adding a record with a name goes back to the home screen
Given the "Add" button is tapped
and the new record screen is visible
When I enter "Name" into the name field
and tap the "Save" button
Then the home screen should be visible
Syntax Notes:
- Leading and trailing blanks are ignored on each line.
- Lines that begin with # are treated as comments and ignored.
- Blank lines are ignored.
- Quotes around text values are not necessary because Simon uses regular expressions to find things. But they can be useful for clarity.
|
