Example User Stories with Gherkin - the start of the BDD process

First, I recommend you to read about BDD.  The point of this post is to show you variations in user stories that use Gherkin as the basis to name the feature and write the scenarios (Acceptance Criteria).

I do BDD on everything I code now.  It just works too well and makes too much sense because it guides you and also everyone understands what work is to be done, and what business requirements are expected of the developer.

Gherkin is usually written by product owners in Agile Stories.  And companies do do this, and they do like it a lot contrary to popular belief that nobody uses BDD, and PMs or business people won't do it.   That "won't do it" debate is when companies try to have the PMs or QA do the actual BDD code.  That's not what we're talking about here and that's not the right way to go about it.  No wonder there is so much confusion out there.  If you have QA doing your BDD code or PMs doing the BDD code, sorry to tell ya but your doing it all wrong and that's the source of frustration and the anti-BDD ranting posts out there.

What you do is you have your PMs or business owners write the Gherkin.  If for some reason you're doing something like I had to this week at work which is a few stories that just relate to my own setup environment, I write the Gherkin myself in some stories I just create for me.

I just wanted to share them, in hopes that it helps you understand how to start off doing BDD and how you can write good maintainable, and clear user stories for all.

For the stories that do require code for Gherkin, then developers will take the Gherkin and literally copy it right out of the user stories and into Cucumber.js features and scenarios for example...or whatever framework you're using.

Story #1 Setup Initial OS X Local Developer Environment on Laptop
(btw, the "feature" is the overall story itself, it's the title above)

As a new Software Engineer
I need to setup an initial basic local development environment for OS X
So that I can start coding SomeFramework, AnotherFramework, etc.

(scenarios might "seem" overkill for this but adding them anyway to explain requirements for creating a local environment for starters)

Acceptance Criteria

(minimal possible setup, the following tests that we have things "working")

Scenario: Able to Run a NodeJS app
Given I have installed NodeJS
When In my favorite Code Editor (e.g. Webstorm)
Then I should be able to spin up a new Node app

Scenario: Able to Run ExpressJS and a web app
Given I have installed NodeJS and Express installed
When In my favorite Code Editor (e.g. Webstorm)
Then I should be able to run a website locally

Scenario: Able to Run Cucumber.js BDD Tests
Given I have installed NodeJS and Cucumber.js
When In my favorite Code Editor (e.g. Webstorm)
Then I should be able to create 1 BDD test (see the test fail (red) then make it pass (green))

Scenario: Able to Run Mocha TDD Tests
Given I have installed NodeJS and Mocha.js
When In my favorite Code Editor (e.g. Webstorm)
Then I should be able to create 1 TDD test (see the test fail (red), then make it pass (green))

As you can see, everything is very clear.  It's a no brainer, Gherkin is a great way to communicate all this; it makes sure it's short, and everyone will be happy, and it's something developers can run with and know they're doing what they're supposed to be doing.  And it also then guides us and truly gives us a precise starting point in our BDD code.  And we need this because the BDD code guides us down to the very first TDD tests we'll do in order to implement (complete) this story before passing it to QA for final integration tests & closure.

Here is another example

In this case, I don't really have scenarios or need any for this, so I just write the feature and that's it:

Story #2 Basic Documentation of OS X Local Development Environment Setup

As a new Software Engineer
I believe it would be helpful along the way to be document the setup
So that myself or anyone new or existing could get up to speed, learn, or save some time possibly

Note: Maybe some of it would be helpful in the future also if we ever created an OS X developer image for laptops?

And here is a story where I'll be spiking some code and later scrapping the code.

It'll only be used for some short-term temporary testing with some new automation tools we're proofing out...so since I'm spiking then will literally remove the code later on in our source control, there's no need to be doing BDD or TDD here...we do not plan to use it as a base for any code or use it in production:

(note that the italics below are to replace real words as to keep this generic for public viewing purposes)

Story #3 Simple NodeJS Web App Rendering Static Content

Feature: Simple NodeJS Web App Rendering Static Content

As an admin of SomeAutomationSystem
I want to have available a very lean NodeJS app running static content
So that the team can work on figuring out how to take that code and DoSomethingWithIt in SomeAutomationSystem 

Acceptance Criteria

Scenario: Web Page loads and shows static content
Given I run the NodeJS web application in the browser
When The page is done loading
Then I should see the the content "This is a Web Page Running on Node and Express"

So you can see how User Stories (features) coincides with BDD and how the Gherkin syntax is IMO the best way to be writing stories not only because it's clear, consistent, and concise, but because devs can straight up copy and start working with them in whatever BDD framework they are using that uses Gherkin, usually it's Cucumber.  I am using Cucumber.js.