Submit to Reddit      

<< Table of Contents >>
Previous << Work Backwards: Then-When-Given

The Behaviour Specification Handbook

Effective Behaviour Specification Steps

Avoid "I"

A quick search for example Behaviour Specifications predominantly reveals behaviours that use the word "I". If you ever come across this, please ask the following question:

In the context of that software component, who really is 'I' and are they important?

As discussed further below, a Behaviour Specification that uses the word "I" is generally not focused or specific enough on the actual behaviour and introduces potential ambiguity and confusion. Just avoid the word "I"!

There are a few reasons why the usage of the word "I" could be so common:

  • Due to having a mindset of "testing" versus "specification";
  • Due to having a prevalent focus on specifying User Interface or End-to-End behaviours; and
  • Due to copying the style of User Stories.

Due To A Mindset Of Testing

For instance, the Agile Alliance website has a description of the Given-When-Then syntax, and their example uses the word "I". The same page interestingly states that the Given-When-Then syntax is "intended to guide the writing of acceptance tests for a User Story". By using the word "test" in their description of the Given-When-Then syntax, their mindset is clearly still focused on testing — rather than specification.

Acceptance Tests pre-date Behaviour-Driven Development, with BDD being an evolution of previous methods, focusing more on "specifying behaviour" rather than talking about "tests". There is a powerful and yet subtle conceptual difference in perspective between "writing tests" and "specifying behaviour".

This is one reason why my recommendations differ, as my guidelines come from a mindset focused on specifications — not just testing.

Due To A Focus On User Interfaces

Another possible reason for the common usage of the word "I" is the significant amount of User Interface-focused behaviour examples, where there is an actor interacting with the system.

The following "When" step illustrates a typical, inadvisable, easily found example of a User Interface-focused step.

When I click on the Submit button
Then the transaction details are sent to the service that records the transaction

One reason why I recommend against using the word "I" is because it subtly focuses attention on the actor’s actions and focuses less on the behaviour of the component being specified. In the above example, in the English language, the subject of the phrase is "I". The primary focus is thus needlessly on the actor performing the action of clicking, rather than the subject being the more important aspect that the button’s click behaviour was triggered.

Another reason to avoid "I" is because it begs many other questions to be asked, such as:

  • Who actually is "I"? Is "I" a guest user to the system, or my logged-in user profile?
  • What would be the behaviour if someone else performed the action? For instance, what happens if John does it? How should the component behave then? That information unfortunately is not specified and is therefore ambiguous.

If the purpose of the Behaviour Specification was however to define the behaviour that occurs when a user profile with a specific security role or permission performs the action, then at least the logical name of the security role should be specified, and the word "I" still is unnecessary and not beneficial.

Let us now take this example to the next level – and remove the word "I".

When the Submit button is clicked
Then the transaction details are sent to the service that records the transaction

The wording above is much better focused on the action of clicking the Submit button, without the distraction and unimportant details (in this case) of who clicks the button.

We can do even better than this though! Remembering that the software component context is key to the understanding of Behaviour Specifications, and understanding that this particular behaviour is written in and from the context of a User Interface component, we can rewrite the "When" step as follows.

When a trigger occurs to submit the transaction details
Then the transaction details are sent to the service that records the transaction

Within the context of a User Interface component and feature file, the information about a "Submit button" and "clicking" is unnecessary implementation detail. With the exception of specifying security rules, it does not matter who clicks the button, what type of button it is, whether it is a button or any other type of User Interface widget, and whether the widget is mouse clicked, tapped or keyboard, voice or thought activated. What is important for this behaviour however, is that something happened to trigger the recording of transaction details and that there was an attempt to invoke an appropriate business service.

Now that I have just opened the door to further questions about User Interface specifications, please see Have Different Feature Files For Different User Interfaces for details.

Due To Copying The Style Of User Stories

A User Story is a precise and short expression of a requirement by a particular type of business role. As such, the syntax begins by specifying the role of the actor — for instance, "As an accounts manager" — and the rest of the story is written and understood from within the context and perspective of an actor with that specified role. Additionally, a User Story can encompass the functionality provided by multiple software components and systems.

In contrast, a Behaviour Specification is a specification about part of one software component, and that behaviour may apply to many User Stories. Within the context and perspective of that software component, if the word "I" was used, it should only refer to the software component itself. The problem is that it really does not make sense to refer to a software component in that way in the first place.

User Stories and Behaviour Specifications have different purposes. Confusion ensues if one incorrectly mixes the concepts and tries to think about and understand a Behaviour Specification from within the context of a specified role of a User Story.

For the sake of simplicity, and to reduce potential confusion and ambiguity, avoid using the word "I" in the Behaviour Specifications.

Next >> Terminology Guidelines