« Table of Contents »
Previous « Effective Behaviour Specification Descriptions

The Behaviour Specification Handbook

Effective Behaviour Specification Descriptions

Start Behaviour Descriptions With “Should”

In order to write an effective Behaviour Specification Description, describe each behaviour in a sentence, beginning with the word “Should”.

The word “Should” at the beginning of a sentence helps to focus both the author and reader on the actual intent of the behaviour. In the English language, behaviours generally are described with verbs. The next set of words grammatically after “Should” typically is a verb or adverb. By starting with “Should”, the structure of the English language is forcing the optimisation of the descriptions so that we can immediately focus on the intent of the actual behaviour and more quickly understand how it may differ from other behaviours.

A template format for the recommended wording of a Behaviour Specification Description is:

1    Should [action] when [criteria]

The first part of the description is the action to perform, and the second part is the criteria for the action to occur.

For example:

1    Should calculate the invoice amount when an order item is added to an order

This description is clear and intention-revealing about the behaviour. A reader immediately knows and understands that the behaviour is to “calculate the invoice amount”, and the criteria for this occurring is “when an order item is added to an order”.

Applying a standard such as beginning Behaviour Specification Descriptions with the word “Should” helps teams to write more useful and intention-revealing descriptions and naturally fall into the “pit of success”.

Different From A Test Case

A Behaviour Specification Description is subtly different from a description of a Test Case. A traditionally written description of a Test Case is authored from a different perspective that typically aims to summarise the scenario and steps that are taken.

For example, a contrasting traditional Test Case description for the example behaviour above would typically be:

1    Adding an order item

Hopefully you can appreciate the subtle differences between Behaviour Specification Descriptions and Test Case descriptions. The description of the Test Case is often shorter and at a higher summary level.

Behaviour Specifications Are Not Legal Requirements

As has been stated previously in this handbook, requirements are a prerequisite to the identification and writing of Behaviour Specifications.

The Internet Engineering Task Force (IETF) identifies an Internet Best Current Practice (BCP) of “Key words for use in Requests for Comments (RFCs) to Indicate Requirement Levels” - BCP 14 / RFC 2119. This document defines a number of key words as they are to be interpreted in IETF documents.

Of particular note is their definition of word “SHOULD”, meaning that:

"there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.“

I acknowledge that a pedantic reader of a Behaviour Specification Description could choose to interpret “Should do XYZ always” in English as “it should do XYZ always, BUT because you said the word ‘should’, it does not always have to… and therefore there is space for unintended behaviour”. This same type of reader would suggest tightening the terminology in order to make it completely unambiguous and fit for a formally signed business or legal contract — by prefixing the description with the word “Must”, “Shall” or “Will” instead of “Should”.

Behaviour Specifications however, are not part of a formal business contract (such as a requirements document) that requires legally precise wording and change management. Behaviour Specifications are only as-built, living documentation and test assets, and using the word “Should” is perfectly acceptable. There is therefore no need to be concerned about the IETF definition and its irrelevance to Behaviour Specifications.

The Subtle Aspect of “Should”

In case you need any more convincing, Dan North, the originator of BDD, in Introducing BDD, eloquently adds more weight to the argument for using the word “Should”:

"A more subtle aspect of the word ‘should’ becomes apparent when compared with the more formal alternatives of ‘will’ or ‘shall’. ‘Should’ implicitly allows you to challenge the premise of the test: “Should it? Really?” This makes it easier to decide whether a test is failing due to a bug you have introduced or simply because your previous assumptions about the system’s behaviour are now incorrect.“

Next » Indicate Positive or Negative Behaviour

« Table of Contents »
Previous « Avoid “I”

The Behaviour Specification Handbook

Effective Behaviour Specification Steps

Terminology Guidelines

As previously discussed, it is best to avoid the usage of the word “I”. In addition, it is best to avoid the following list of User Interface-focused words, as they indicate and represent implementation details that are unnecessary and should be avoided in Behaviour Specifications.

The list of User Interface words to avoid includes, but is not limited to: “show”, “view”, “see”, “hear”, “screen”, “page”, “button”, “click”, “tap”, and “navigate”.

Many computer programming languages have the concept of a “null” value. A variable with a “string” data type typically can have a value of “null” or could contain an empty string that has a length of zero characters. Following the guideline to use everyday natural language, I recommend using the terminology “not specified” instead of the word “null”, and “blank value” instead of “empty string”.

I also recommend using the words “error” and/or “notification” to specify behaviours related to when an “exception” occurs in a program. An “exception” is a technical programming concept and is not typical business vocabulary. If the business does regularly refer to business process exceptions, then care must be taken to ensure everyone in the team has a clear understanding of the meaning and how it differs from a technical exception.

Next » Reuse Steps, If Possible

The Behaviour Specification Handbook

Overview

As a long-time advocate of Behaviour-Driven Development (BDD) and having been a technical lead and coach of BDD enterprise software development teams since 2010, I have tried many different variations of the process of BDD and the writing and implementation of Behaviour Specifications.

This handbook is my suggested practical, prescriptive methodology for writing Behaviour Specifications (also known as ‘scenarios’ in the Gherkin language), including tips and suggestions that have repeatedly proven to me to be worthwhile practices in both small and large-scale solutions.

I hope they help you and your team to write better Behaviour Specifications and deliver successful solutions!

Table of Contents

Chapter 1: Background

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

Chapter 2: Behaviour Specifications

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?

Chapter 3: The Behaviour Specification Writing Process

1. Prerequisites
2. The Behaviour Specification Writing Meeting
3. Meeting Milestone 1 — Background Context and Requirements Overview
4. Meeting Milestone 2 — Technical Design Overview
5. Meeting Milestone 3 — Checkpoint
6. What’s Happening In Our Minds?
7. Meeting Milestone 4 — Behaviour Identification
8. Meeting Milestone 5 — Step Writing
9. Meeting Milestone 6 — Determine Test Types
10. About End-To-End Behaviours
11. About Outsourcing Delivery

Chapter 4: General Tips

1. The Software Component Context Is King
2. Avoid Specifying Internal Technical Implementation Details
3. Specify Relevant Business Capabilities
4. Specify Component Interaction Behaviours
5. Write One Specification For One Behaviour
6. Use Present Tense
7. Avoid Generic Verbs
8. Write In Everyday Business Language
9. SpecFlow/Cucumber Is Only The Name Of A Tool
10. Have Different Feature Files For Different User Interfaces

Chapter 5: Effective Behaviour Specification Descriptions

1. Start With Should
2. Indicate Positive or Negative Behaviour
3. Indicate Primary or Secondary Behaviour
4. Unique Within Their Feature File
5. Unique Without Their Feature File
6. Follow This Template

Chapter 6: Effective Behaviour Specification Steps

1. Work Backwards: Then-When-Given
2. Avoid “I”
3. Terminology Guidelines
4. Reuse Steps, If Possible
5. Understand Technical Tool Constraints
6. Single When
7. Guidelines For Examples and Data Tables

Chapter 7: The Implementation Process

1. Behaviour Specifications Before Implementation
2. The Roles of Developers and Test Analysts
3. Identify Which Developers Will Code Each Behaviour
4. Identify Who Will Code The Automation Or Manually Perform Each Test
5. Code!
6. Separate Implementation of Unit Test Steps From Integration Test Steps
7. Review Test Outputs

« Table of Contents »
Previous « Prerequisites

The Behaviour Specification Handbook

The Behaviour Specification Writing Process

The Behaviour Specification Writing Meeting

After all the previously described prerequisites have been satisfied (i.e. all the “core business requirements” are known and the initial, low-level technical design is understood), it is now time to identify and write the Behaviour Specifications — so go and schedule a Behaviour Specification writing meeting!

Meeting Attendees

You might be wondering about who to invite to this session?

The attendees of the Behaviour Specification writing meeting should include a holistic cross-section of the solution development team, including all the actual people who will be developing and testing the given functionality. I will come back to this point later.

The types of roles that should attend the meeting include:

• Technical Architect;
• Technical/Developer Lead;
• Business Analysts;
• Test Analysts; and
• Developers.

Actual business representatives are welcome to attend and are especially useful if the requirements need further clarification. Assuming however that the requirements are reasonably clear, the business representative would only attend predominantly for their own benefit and understanding, or for team building reasons.

Next » Meeting Milestone 1 — Background Context and Requirements Overview

« Table of Contents »
Previous Chapter « Behaviour Specifications

The Behaviour Specification Handbook

The Behaviour Specification Writing Process

This chapter in The Behaviour Specification Handbook discusses the prerequisites and procedure involved in identifying and writing Behaviour Specifications, and how to effectively host the Behaviour Specification writing meeting.

1. Prerequisites
2. The Behaviour Specification Writing Meeting
3. Meeting Milestone 1 — Background Context and Requirements Overview
4. Meeting Milestone 2 — Technical Design Overview
5. Meeting Milestone 3 — Checkpoint
6. What’s Happening In Our Minds?
7. Meeting Milestone 4 — Behaviour Identification
8. Meeting Milestone 5 — Step Writing
9. Meeting Milestone 6 — Determine Test Types
10. About End-To-End Behaviours
11. About Outsourcing Delivery

Next » Prerequisites

Next Chapter » General Tips

« Table of Contents »
Previous Chapter « Effective Behaviour Specification Steps

The Behaviour Specification Handbook

The Implementation Process

This final chapter in The Behaviour Specification Handbook provides various tips for implementing Behaviour Specifications.

1. Behaviour Specifications Before Implementation
2. The Roles Of Developers and Test Analysts
3. Identify Which Developers Will Code Each Behaviour
4. Identify Who Will Code The Automation Or Manually Perform Each Test
5. Code!
6. Separate Implementation Of Unit Test Steps From Integration Test Steps
7. Review Test Outputs

Next » Behaviours Before Implementation

« Table of Contents »
Previous « Behaviour Specifications Before Implementation

The Behaviour Specification Handbook

The Implementation Process

The Roles Of Developers And Test Analysts

During development of a software component, the developers should implement, as automated tests, all the tests that the team has agreed to be Unit Tests. Depending on the team, the developers ideally also would implement the Integration Tests as automated tests. However, team composition and other delivery practicalities can dictate otherwise, and perhaps there might be other test automation engineers available to implement the automated Integration Tests.

Regardless of whether the developers implement both the Unit and Integration Tests as automated tests, test analysts still play a vital role in team. Below is a list of some of the important activities that test analysts perform.

• Behaviour Specification writing – during the Behaviour Specification writing sessions, the test analysts provide their unique, test-focused perspective, which helps the team to ensure that all the positive and negative behaviours have been identified;
• Test analysis — determining the types and structure of the test data that will be required and helping the developers understand that for mocking data in Unit Tests, or for dynamically setting up and tearing down test data as part of automated Integration Tests;
• Reviewing test output — as each developer finishes implementing an automated test, a test analyst should sit down with the developer and peer review the test output. During this review, the test analyst is ensuring that they understand the output and can agree that the test has been performed just as if they would have performed it. Thus the test analyst can, with their hand on their heart, record in the Test Management tool that the Behaviour Specification is complete;
• Verifying that the automated tests are actually doing what they are supposed to do in a specific environment, by picking a couple of automated Integration Tests on an adhoc basis, performing them manually and comparing the output of the automated test with the results of the manual execution. This type of adhoc manual testing can, for instance, highlight issues where some of the configuration of the automated tests might be incorrectly pointing to a wrong environment;
• Setting up test data for manual Integration Tests or manual End-to-End Tests;
• Performing manual Integration Tests — depending on the situation, there could be quite a few Behaviour Specifications that the team has tagged to be tested manually;
• Performing manual End-to-End Tests;
• Performing higher-value, adhoc, exploratory testing;
• Performing test management activities;
• Gently assisting developers to remain focused and on-track; and
• Performing analysis in preparation for the next sprint.

As you can see, there is plenty of work for everyone in the team!

Next » Identify Which Developers Will Code Each Behaviour

« Table of Contents »
Previous « Overview Of The Gherkin Language

The Behaviour Specification Handbook

Behaviour Specifications

Thoughts On Gauge

The relatively new kid on the street is Gauge. Gauge is an alternative and similar way of specifying behaviours, but it does not follow the Gherkin syntax. In Gauge, behaviours are defined in “Specification” files that follow the Markdown syntax. Each Behaviour Specification is described with a heading and description, and then is defined further as a series of executable steps.

The main difference between the syntaxes used in Gauge and Gherkin is that there is no specific syntax in Gauge that must be followed to define each step. In Gauge, each step can be written completely in free-text. There is no “Given”, “When”, “Then” restrictive syntax like in Gherkin, and this flexibility can be a powerful drawcard for some people.

However when used in real life within the context of a business, this flexibility and power can be counter-productive. In a business, teams need to act responsibly and in a cost effective manner — which means teams should have agreed standards that are consistently followed. Consistency in language, communication patterns and style is important in a business in order to minimise the overall costs of development, maintenance and staff training. If a business decided to use Gauge as their Behaviour Specification and execution tool of choice, the first thing the business should do, in order to keep costs to a minimum, is to create a standard style guide to promote consistency. An effective standard more than likely will significantly restrict the syntax of the steps — so the drawcard of free-text becomes a moot point. In the end, you may as well have just used Gherkin. The Gherkin syntax “ain’t broke” and is quite effective — although as you will see later, I recommend an even more restricted style!

Sure, there are many cross-language features in the Gauge tooling that may pique your interest, and if you need that functionality then go for it — but please don’t base your decision on the flexibility of free-text steps!

I have found that the Gherkin syntax is an excellent foundational structure, and I will continue to recommend it. Since the Gauge syntax is unrestricted, the recommendations presented here can be applied easily within Gauge specifications as well.

Next » Feature Files

« Table of Contents »
Previous « Reuse Steps, If Possible

The Behaviour Specification Handbook

Effective Behaviour Specification Steps

Understand Technical Tool Constraints

At the end of the day, the developers and/or testers must be able to successfully implement the Behaviour Specifications as automated tests. If they cannot do so because of reasons related to the technical tool that enables the execution of the Behaviour Specifications (e.g. Cucumber, SpecFlow, etcetera), then either the style of writing the Behaviour Specifications must be altered or the tool must be changed.

There is a constraint with the tool Cucumber that may prevent a team from following some of the recommendations in this handbook. With Cucumber, each step within a set of feature files that are executed together is unique and only can have one corresponding implementation. Because of this, when using Cucumber, there cannot be Behaviour Specification steps with the exact same wording in more than one feature file, and with different implementations that are specific to the context of their software component. For example, it would not be possible to implement the suggested approach of having different feature files for the different User Interface mechanisms of voice or touch. With Cucumber, in order to make the wording of each step unique, there would be no choice but to embed specific technical implementation details into the wording of each step, so that each step can be precisely implemented as necessary. The other alternative would be to execute the feature files separately — but for the example of voice and touch interfaces, that does not seem like a good approach since they all relate to the same logical grouping of functionality.

This constraint is an intentional design decision made by the Cucumber development team, with the idea that it forces the usage of a ubiquitous language and fosters better reusability and clarity of steps. Here is one discussion about it, in case you are interested. However, defining more precise steps (in most cases, by specifying implementation details) with the goal that it increases pressure to grow a business’s ubiquitous language (more than likely with technical terminology) is not, in my opinion, a desirable goal or outcome.

The approach I recommend both embraces and highlights the context of a software component and feature file as the key to understanding each behaviour, and also strongly emphasises the usage of an accepted everyday business language. This also probably is another reason that many common behaviour examples follow practices that I do not recommend, because the idea of context is either not well understood or not embraced.

The Cucumber Backgrounder interestingly goes so far as to say that relating the step definition files to specific feature files is considered an anti-pattern – although quickly and wisely advises that you may depart from that advice when you are experienced enough to evaluate the trade-offs. Over the years I have given this a great amount of thought, attention and real-life practise, and with the guidelines in this handbook, I have witnessed many more benefits than negatives. Unfortunately, Cucumber does not appear to be the right tool for the job. There are however other suitable tools available.

In the world of Ruby, Turnip partly was created because of a desire to have step implementations scoped to behaviours.

In the .NET world, the open source tool SpecFlow provides the test automation developer with the option of reusing existing step implementations where useful and desired, and also the ability to have different implementations for the same step wording in different feature files. This choice is made in the implementation code via SpecFlow’s “scope” mechanism, based on criteria such as the title of the feature or “@tags” that are specified at the top of the feature file or on each individual Behaviour Specification.

I strongly recommend the usage of a tool like SpecFlow because of this enabling capability that allows experienced people to make their own choice, without being forced to push a square peg into a round hole. Having said that, many kudos must go to the Cucumber team for their continued effort and dedication over the years, and the community they have inspired.

Next » Single When

« Table of Contents »
Previous « Indicate Primary or Secondary Behaviour

The Behaviour Specification Handbook

Effective Behaviour Specification Descriptions

Unique Within Their Feature File

Helpful, intention-revealing Behaviour Specification Descriptions can become a little verbose. As such, it can be very useful for team members to have a mechanism to easily identify or refer to a specific Behaviour Specification from the long list of specifications in the same feature file.

In my experience, it is beneficial for each Behaviour Specification Description to have a numeric-based identifier that is unique within the scope of the feature file. This helps team members to quickly find or reference specific specifications in that feature file.

It also is better if the numeric-based identifier is not a consecutive, sequential number. By intentionally leaving gaps between the numbers, new Behaviour Specifications easily can be inserted in between the existing behaviours, without causing people to have the desire to do any time-wasting renumbering.

In addition it is benficial to prefix the numeric-based identifer with an acronym that represents the type of test - such as UT for a Unit Test or IT for an Integration Test. This is in addition to the @tag above the scenario description.

It also can be helpful and meaningful to logically group a specific positive behaviour with its related negative behaviours. All the related behaviours can be given the same numeric identifer, and then be suffixed with a different letter of the alphabet to make them each unique. See further below for an example.

Next » Unique Without Their Feature File