A Stakeholder is a person who gets some value out of the system. Typical stakeholders are representative of groups of users, for example a trader or an administrator. Some teams describe stakeholders with user personae (explained nicely in User Stories Applied[7]). Personae are particularly useful for web based projects as they encourage you to think about how a typical user is likely to interact with the system— for example look at a monitor in despair.

A Feature is a piece of system functionality that delivers value to one or more stakeholders. Executable specifications work best when described from the perspective of stakeholders, not technical infrastructure, since doing so enables business users to understand them better and engage more in discussions about what makes a particular feature complete.

Features are normally vertical functional slices of the system, for example credit card processing. Horizontal infrastructural slices, for example database caching, are not good as features. They do not deliver value directly to any stakeholders. Stakeholders will not be able to engage properly in specifying the acceptance criteria for such functionality, pretty much defeating the point of specification by example.

A User story is a rough description of scope for future work, used as a planning tool. Stories are vertical slices of system functionality that are deliverable independently. Each story should specify the value it brings to one or more stakeholders, the stakeholders that care about the story and the scope of the intended work. A common format for the stories is:

There are alternative formats, such as:

Many a ninja has died in the futile format wars and some silly shoguns will try to convince you that one way of telling stories is significantly better than the other one. Ninja cucumber disagrees! For the purposes of this document all these formats are equivalent and we won't enter into a discussion on which one is better.

Stories often impact several features — a payment story might have an impact on card processing, fraud control and back-office reporting. Stories are often relatively small chunks of work to support frequent delivery. A single feature might be delivered through a large number of stories.

Stories are more than just the format

Many junior ninjas confuse stories with the cards that they are written on. Here is an example of a good user story: In order to reduce fraud, as a financial controller I want the system to automatically send Chuck Norris to beat up suspected fraudsters. This story clearly states who cares about some functinality, why it is important and what it delivers. This provides enough information for a meaningful discussion on the specifications when the time comes to implement it. Here is an example of a bad user story: As a trader I want to enter a trade because I want to trade Although this story obeys the form, it is too broad, too generic and it does not state a clear benefit. It would be much better to specify a full flow of activities that provides some end-to-end value to a stakeholder. We would normally look for thin slices of functionality, for example not supporting all possible trade types or trade workflows from the start but only one type. In this way, once a story is delivered some stakeholders can actually start getting the value from it.

A Feature file describes a feature or a part of a feature with representative examples of expected outcomes. Cucumber uses these files to validate some system functionality against its specifications. Feature files are plain-text files, ideally stored in the same version control system as the related project.

Here is an example of a Cucumber feature file:

Feature: Fight or flight
  In order to increase the ninja survival rate,
  As a ninja commander
  I want my ninjas to decide whether to take on an 
  opponent based on their skill levels

  Scenario: Weaker opponent
    Given the ninja has a third level black-belt 
    When attacked by a samurai
    Then the ninja should engage the opponent

  Scenario: Stronger opponent
    Given the ninja has a third level black-belt 
    When attacked by Chuck Norris
    Then the ninja should run for his life

Later in this chapter we cover how Cucumber interprets this file.

	Feature file extension
	Feature files should have a .feature extension

Each feature should be illustrated with Key Examples. The examples show the expected outcomes in specific representative cases with very precise information. This makes it absolutely clear what the system is expected to do and helps to avoid any misunderstanding and ambiguity. It also makes it possible for an automation tool, such as Cucumber, to check whether the system works according to the specification.

A Scenario captures one key example for a feature in the feature file. It represents a way that the system delivers some value to a stakeholder. Scenarios are units of specifications for Cucumber. They allow us to chop up feature functionality like Sushi, into chunks that can be separately consumed. Examples of good scenarios for credit card processing might be successful transaction authorisation, transaction failure due to lack of funds, transaction failure due to wrong verification code and so on.

Steps are domain language phrases that we can combine to write scenarios. They can either refer to the context of a scenario, an action that the scenario describes or a way to validate the action. The steps that define the context of a scenario generally begin with the Given keyword, for example:

The steps that define an action generally begin with the When keyword, for example:

The steps that define an expected outcome generally start with the Then keyword, for example:

Step Definitions are reusable automation components that execute individual steps. They tell Cucumber what to do when interpreting a particular step (see Figure 5.1, “Cucumber step definitions automate validation”). Programmers or automation specialists write step definitions where necessary when implementing scenarios to validate that they work correctly. Once a step definition is implemented, the step can be reused in other scenarios. We cover how to write step definitions in Ruby, .NET and Java in the following chapters.

Gherkin is the language for describing Cucumber feature files. It is also the name of a separate piece of software that interprets that language.

Gherkin, the language, defines the structure of a feature file and the keywords that can be used to describe features. Gherkin, the software, parses files for Cucumber and related projects, such as Specflow.^[22] You can use it to implement your own version of Cucumber for a platform that is not currently supported, if you can find one.