About End-To-End Behaviours

« Table of Contents »
Previous « Meeting Milestone 6 — Test Types

The Behaviour Specification Handbook

The Behaviour Specification Writing Process

About End-To-End Behaviours

In addition to specifying the behaviours for an individual component, there also should be only a small number of behaviours (please remember the Testing Pyramid!) specified for end-to-end functionality.

I suggest specifying these end-to-end behaviours in their own feature file, separate from the feature file for each component, since these behaviours span multiple components. I also recommend adding the tag “@E2ETest” at the top of the feature file.

Next » About Outsourcing Delivery

About Outsourcing Delivery

« Table of Contents »
Previous « About End-To-End Behaviours

The Behaviour Specification Handbook

The Behaviour Specification Writing Process

About Outsourcing Delivery

What would happen in the situation where a business project team outsources the analysis, development and testing effort?

First things first, the requirements and scope should be formalised with a signed business contract between the business and the outsourced delivery team.

In the case of having an outsourced delivery team, working on-site or off-site, the business project team is unlikely to be the appropriate team to be running the Behaviour Specification writing session, because they are unlikely to have all the necessary resources, nor a holistic perspective of the solution.

A better approach is to have the outsourced delivery team own and organise workshops to collaborate with the business and other team members in order to perform the business analysis and Behaviour Specification writing sessions. With the outsourced delivery team producing the Behaviour Specifications, they should handover back to the business the completed Behaviour Specifications as part of their documentation and test assets. The Behaviour Specifications and software components also can be used as a metric to track the progress of the delivery team.

In any case, with the requirements and scope already formalised, there is no need to also formalise the Behaviour Specifications with a signed business contract. Please see What Are Behaviour Specifications? for more information on what a Behaviour Specification is, and importantly, is not.

Next Chapter » General Tips

Avoid "I"

« 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.

1When I click on the Submit button
2Then 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”.

1When the Submit button is clicked
2Then 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.

1When a trigger occurs to submit the transaction details
2Then 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

Avoid Generic Verbs

« Table of Contents »
Previous « Use Present Tense

The Behaviour Specification Handbook

General Tips

Avoid Generic Verbs

Avoid the word “handle” or any other verb that is generic and hides or obfuscates the actual behaviour.

For instance, let us pretend that someone wrote the following inadvisable description:

1    Should handle the situation when the total amount is not equal to the sum of all item amounts

The above description has both positive and negative points. On the positive side, the “when” section is descriptive and is an easily understandable, differentiating condition or entry criteria. On the negative side however, “handle” is not actually describing the behaviour that occurs in that situation. What instead is actually meant by “handle”?

A better description is more specific about the behaviour. For instance:

1    Should provide a notification of an error when the total amount is not equal to the sum of all item amounts

This much more clearly describes the actual type of behaviour to be performed.

Next » Write In Everyday Business Language

Avoid Specifying Internal Technical Implementation Details

« Table of Contents »
Previous « Software Component Context Is King

The Behaviour Specification Handbook

General Tips

Avoid Specifying Internal Technical Implementation Details

There is no need to specify the internal technical implementation details of a software component in the Behaviour Specifications. To be very clear, let me emphasise the word “internal”, in contrast with any publicly exposed, outward-facing behaviour or other mandated functionality, such as business rules.

If the implementation of a component needs to be refactored or changed, the words used in the Behaviour Specifications should NOT need to be changed. The words used in a Behaviour Specification should only need to change if there is a change to a “core business requirement”.

Behaviour Specifications can become unnecessarily brittle and potentially short-lived due to tight coupling that is created when any internal technical implementation concerns are specified. In other words, if internal technical implementation details are specified in the Gherkin, then the cost of maintenance and future enhancements will increase unnecessarily, since it could have been avoided in the first place.

Internal Technical Details — Example #1

For example, say that the low-level technical design has identified there is a component that must store and retrieve items in memory. Perhaps the component uses a Dictionary data structure to store the data, or alternatively, perhaps it uses an Ordered List data structure.

In this example, the type of data structure internally used by the component is completely irrelevant, and the fact that a data structure exists at all also is completely irrelevant in the Behaviour Specification. The only concerns that are relevant are the behaviours related to successfully and unsuccessfully adding and retrieving items, and also perhaps some non-functional performance requirements.

Internal Technical Details — Example #2

In this example, say that there is a behaviour specifying that a component should persist its data, but it unfortunately also says the words “in a database”. The word “database” is an internal implementation detail that makes the Behaviour Specification unnecessarily brittle. If in the future, the implementation is changed to store the data in a file in a file system, the wording of this Behaviour Specification also would have to be changed. This is inefficient, costly and can be avoided!

Alternatively, the wording “data store” is an example of a preferred, generic term that cleverly encapsulates any changes or volatility in implementation. When using the words “data store”, if the internal technical design of the component changes from using a database to storing the data in a file, the wording of the Behaviour Specification does not need to be changed. A behaviour that says “data store” instead of “database” is more resilient to future implementation changes.

Internal Technical Details — Example #3

In the example descriptions in the earlier section What Is A Behaviour Specification Description?, hopefully you noted that there is no indication of how the behaviours are technically implemented internally. In fact, just by reading those descriptions, you would not even know that they are specifically describing the behaviour of a User Interface component. That is intentional! Unlike many Gherkin examples that can be found in BDD literature, there is no typical User Interface wording about “screens”, “pages”, “fields”, “buttons”, “clicks”, or “navigation” etcetera, nor is there any need for those types of words.

These same behaviour descriptions could be copied as-is and used to specify a Web Service component as well as a User Interface! This is a prime example of why the software component context is king — the Behaviour Specifications of related functionality that exists in components separated by an architectural tier can be the same, and it is only the technical implementation specific to that tier that is different.

Internal Technical Details — Example #4

The example descriptions in the earlier section What Is A Behaviour Specification Description? also do not specify the particular technical mechanism by which the address validation service is invoked — for instance, as a Web Service call. That would be internal implementation detail!

It is possible that the solution delivery team could decide it is best in the short-term to implement a tactical solution. In this example, that tactical solution is chosen to be a monkey that physically runs down the corridor and hands a human a piece of paper that has an address printed on it which is to be verified. Whatever tactical or strategic approach is taken, the Behaviour Specification wording should not need to be altered!

To recap, it does not matter how the behaviour is implemented internally within a component. The wording of the Behaviour Specification should only need to change if there is a change to the core business requirement. Behaviour Specifications should be long-lasting and resilient by encapsulating internal implementation volatility. For anyone who is interested in the current, actual technical implementation details, that can be understood from and seen in the test run output.

Next » Specify Relevant Business Capabilities


« Table of Contents »
Previous « The Behaviour Specification Handbook

The Behaviour Specification Handbook


This first chapter in The Behaviour Specification Handbook provides a quick overview of Behaviour-Driven Development (BDD), how it can help to reduce the costs of software development, and how to scale it to large solutions.

  1. Behaviour-Driven Development (BDD) Overview
  2. Scaling BDD To Large Solutions
  3. What Is A Software Component?

Next » Behaviour-Driven Development (BDD) Overview

Next Chapter » Behaviour Specifications

Behaviour Specifications Before Implementation

« Table of Contents »
Previous « The Implementation Process

The Behaviour Specification Handbook

The Implementation Process

Behaviour Specifications Before Implementation

Behaviour Specifications are actual program specifications, and as such, it is common sense that the Behaviour Specifications should be written before attempting to do any coding of a software component.

If however, you are retrofitting behaviours for an existing software component, then you are in an interesting and potentially dangerous situation. The danger is that the team, when writing the specifications, could be too heavily influenced by the existing code and known internal implementation details, rather than writing Behaviour Specifications that better represent the core business requirements. Unless the team is at a mature level of writing Behaviour Specifications in common business language, I recommend that, at least for a large portion of the time allocated to write the specifications, pretend as if the code has not been written already. Either way, the team should keep referring back to the core business requirements, and perhaps only using the code to ensure that everything remains on track. Be careful and do not assume that the code is correct! Do not be surprised if you discover some defects!

Next » The Roles Of Developers and Test Analysts

Behaviour Specifications

« Table of Contents »
Previous Chapter « Background

The Behaviour Specification Handbook

Behaviour Specifications

This chapter in The Behaviour Specification Handbook provides a definition of Behaviour Specifications, and an overview of the Gherkin language and feature files.

  1. What Are Behaviour Specifications?
  2. No Other Test Cases Are Necessary!
  3. Developers: No Other Automated Tests!
  4. Overview Of The Gherkin Language
  5. Thoughts On Gauge
  6. Feature Files
  7. Feature Names
  8. What Is A Behaviour Specification Description?

Next » What Are Behaviour Specifications?

Next Chapter » The Behaviour Specification Writing Process

Behaviour-Driven Development (BDD) Overview

« Table of Contents »
Previous « Background

The Behaviour Specification Handbook


Behaviour-Driven Development (BDD) Overview

The software engineering practices and processes of Behaviour-Driven Development (BDD) that I promote focuses a team on delivering software solutions with high business value, higher quality and less defects. BDD encourages and helps to facilitate close collaboration and clear communication between team members and with business stakeholders.

With BDD, it is possible to deliver solutions that better satisfy actual business requirements and have a lower on-going maintenance and total cost to the business. This can only be achieved however, if the team maintains professional discipline, follows the processes and performs the software development activities, in the recommended order.

One of the key practices in BDD, and the focus of this handbook, is the Behaviour Specification writing sessions. Behaviour Specification writing sessions should be attended by multiple roles in the team, before the coding of a specific piece of functionality is started. This one practice, guided by concrete examples or use cases, has the simple and significant effects of optimising the design, review, and testing feedback cycle by:

  • Ensuring what is to be delivered is actually required;
  • Ensuring what is to be delivered is valuable to the business;
  • Ensuring what is to be delivered is within the agreed scope of functionality;
  • Ensuring what is to be delivered is well understood by the team;
  • Clearly specifying the required behaviour of each software component in everyday common business language that anyone in the team (including business stakeholders) can understand; and
  • Each attendee mentally testing the requirements and software component specifications against the proposed design.

The Behaviour Specification writing sessions encourage and cause important discussions, questions and healthy debates to take place. The result is a common and well-understood, mentally tested and agreed solution — before development has started. There is therefore a significant reduction in the risk of defects and missing or ambiguous functionality early in the software development lifecycle, when it is the cheapest and most appropriate time to have those discussions and identify potential issues.

The clear communication is achieved by everyone in the team discussing required software behaviour or functionality in the business’s everyday common language. If for some reason the common business language unfortunately is ambiguous in some areas, then that is a wonderful opportunity to highlight the risk and show leadership to the business by suggesting and helping to implement some positive, clarifying terminology changes!

As you know, team members will come and go over time. Current and future team members however, may not have the same level of competency, business analysis capability or technical skills. This is why the software specifications are written in the everyday language of the business. Every team member (or interested business stakeholder) who understands the business (the lowest common denominator) — regardless of their technical competency — should be able to understand the functionality that is to be or has been delivered. The total cost over time of software development, maintenance, resourcing and on-boarding is reduced because of this simple concept.

The resulting artefacts typically produced in the process of BDD include living documentation (also known as executable program specifications) and other test assets, such as the test run reports for the executed specifications.

There are many articles available that introduce and discuss the beginnings and benefits of BDD. Instead repeating similar information, below is some recommended reading material:

Next » Scaling To Large Solutions


« Table of Contents »
Previous « Identify Who Will Code The Automation Or Manually Perform Each Test

The Behaviour Specification Handbook

The Implementation Process


It is time to code — and all the developers in the team roll their eyes and mutter “finally”!

A developer should choose one of the Behaviour Specifications they agreed to implement and do just enough coding to fulfil that specification and also implement the automated test for it. Simple – rinse and repeat with the next behaviour.

Whether or not a developer follows the Test-Driven Development (TDD) practice of Red-Green-Refactor is a personal choice. If a developer wants to, then they can implement the test automation code first. That approach has no effect on the practice of BDD, but depending on the skill of the developer, it can result in code that is more easily testable.

Developers also should remember not to write any automated tests other than those specified by the behaviours.

Next » Separate Implementation Of Unit Test Steps From Integration Test Steps