If you work with software development I’m sure that you’ve already heard words like BDD, TDD, ATDD, etc. But, have you heard about SBE? SBE or Specification by Example is a collaborative method for specifying requirements and test. It is a set of process patterns that helps teams build the right software product by writing just enough documentation to facilitate change effectively in short iterations or in flow-based development.

This method springs from the Agile Acceptance Testing and it’s based on defining software requirements by illustrating executable specification with precise examples. SBE is spoken by the Gherkin language. This is a syntax for writing test scenarios that implement BDD methodology. It’s designed to be easy-to-learn by non-programmers, yet structured enough to allow the concise description of examples to illustrate business rules in many real-world domains. 

The structure of Gherkin is the following:

Given - precondition

(and - optional precondition)

When - action/event

Then - outcome

(and - optional outcome)

Before we continue let’s explain some terms from the software quality assurance world and how the testing process goes by the exact order.

Two colleagues working together on a mac in a modern office environment.

If we need to implement something or make some changes, first, we need to create Living Documentation. Gojko Adzic defined the Living Documentation in his book “Specification by Example” as a source of information about system functionality that’s as reliable as programming language code but much easier to access and understand. Living documentation allows teams to collaboratively analyze the impact of proposed changes and discuss potential solutions. 

It also allows them to make use of existing documentation by extending it for new requirements. The Living Documentation helps you to analyze the impact of the changes and to share the knowledge better, so, it makes specifying and implementing more efficient over time.

The Living Documentation consists of a user story, acceptance criteria, and test scenario.

The specification starts with a user story. A user story is an outgrowth of agile methodologies and is used to state requirements without writing endless pages of documentation by break down customer’s requirements into small pieces that are easier to understand and build.

The structure of the  user story is the following:

As a - user role/persona

I want to - feature/functionality

So that - goal/benefit


User stories consist of:

  1. Title - a short explanation of the feature

  2. Body - brief description of who wants the functionality, why and what is the purpose.

  3. Acceptance criteria - defines what you will walk through to make sure that the story is completed.

Now it seems that we have a new open question. What is an acceptance criteria? Acceptance criteria is a specific and well-defined list of conditions that we must meet before the project is considered completed and the project deliverables are accepted by the client. Having clearly defined acceptance criteria can help you in many ways. It triggers the thought process for the team to think how a feature will work from the end user perspective, helps the team to write accurate test cases without any ambiguity to understand the business value, and keeps the right content.

So, first, we create a product specification with user stories. After that, every user story has his own acceptance criteria with one or more test scenarios. The test scenario is created with the Gherkin syntax mentioned above - Given, When, Then.

test scenario is a narrative, which describes how a user might interact with a website or software application. In these scenarios, a specific task is specified and a narrative is written describing how a user might accomplish this task.

Diverse group of people working on their laptops n a conference room.

Summing up, the SBE method is a set of process patterns, such as:

  • Deriving scope from goals - Instead of asking the client for project scope, make sure to understand the business goals and derive the scope from them. Understand the “why” and “who”, understand where the value is coming from, and understand what outputs the business users expect.

  • Specifying collaboratively - Successful teams collaborate with the business users in order to build a shared understanding of what needs to be done and to ensure that different aspects of a system are covered by the specification.

  • Illustrating specifications using examples - Maintain one source of truth. The illustrated examples should describe the entire feature. Data should be included, and don’t use yes/no answers in your examples.

  • Refining the specifications - Never use raw examples, but refine the specification from them. The idea is to use the specification without changing it in order to preserve the value of refining it.

  • Automating the specifications - When the team agrees on a specification with key examples they need to be automated as tests, so you can validate the system many times during the development to ensure that it meets the business goals. It would not be effective if you do these tests manually, it would introduce unnecessary delays and the feedback would be slow.

  • Validating frequently - The system and the executable specification need to be constantly synchronized. After the automation of the validations, you need to validate the system. If this validation is frequent the team get quick feedback. They identify the defects and any differences between the system and the specification early, so they are cheaper to fix.

  • Evolving living documentation - Software products keep evolving and changing after the initial release. That’s why the specifications need to be well organized, easy to find and access and the teams need to update the specifications with these changes, making it a living documentation system that evolves with the code, and it’s a reliable and authoritative source of information, easy to read and understand.

By applying the Specification by Example method you can bridge the communication gap between stakeholders and implementation teams, ensure the software quality from the start, design, develop and deliver the right (software) product.