Visual Specification By Example

Big Thoughts

3 November 2014 • Written by Nigel Charman

Specification By Example (SBE) improves your development process through collaborative discussion, discovery, documentation and automation of examples.

The discussion of examples reveals misunderstandings and uncertainty early in the process, leading to a higher quality solution with fewer defects and a significant reduction in rework costs. Automating the examples can help development teams automatically check when the examples are implemented, and be used for checking of regressions.

In some cases, visualisations provide a powerful way to concisely discuss examples. A picture really can be worth a thousand words.

However, the current tools for documentation and automation of examples rely on text format or tables to describe the examples. If visualisations are the best way to discuss the examples, why not carry those through the documentation and automation?

Discussing the examples

A great way to discuss the specific examples of desired behaviour is to collaborate around a whiteboard.

Often, teams converge on visual structures to describe their examples, especially when describing complex business rules. Here’s a team describing a Theoretical Standards Grading System...


In this case, the team are visualising examples of complex business rules using Venn diagrams. The richness of the visualisation helps us wrap our brains around the complexity, acting as a shorthand form for discussion.

Documenting and automating

The primary benefit of SBE is improved understanding before development and a set of examples to check when development is complete.

Many teams also document and automate the examples as tests to provide ongoing feedback, confidence and improved maintainability.

However, these benefits are reduced when teams let their automation tools dictate the format of their examples. Most teams document the examples using the Gherkin language, which enforces a plain language description using Given-When-Then steps. As an example:

Scenario - domain and subject overlap

Given I have achieved 12 credits in the Calculus subject outside the Algebra domain

And I have achieved 3 credits in the Calculus subject inside the Algebra domain

And I have achieved 14 credits in the Algebra domain outside the Calculus subject

And I have achieved 14 credits in the Biology subject

When the grading system is run

Then my grade is Failed

Compared to the Venn diagram, this text adds a lot of accidental complexity, introducing extraneous cognitive load. The mental effort to process the extraneous detail impacts on our capacity to understand the examples.

In one case, we witnessed business analysts creating separate documents to describe the examples so that the team can make sense of them. This introduced duplication, extra work and synchronisation issues. The business ended up reviewing one set of examples, while the automation checked another set.

Sharing the visualisation

One simple way to address this is to embed a photo of the whiteboard alongside our examples. This allows us to quickly understand the examples and makes it easy to scan through and compare examples.

There is duplication between the photo and the example, but since they are alongside, they are easy to compare.

scenario with photo

Visual examples

Taking this concept further, why not remove the duplication by altering our specification to have the Venn diagram driving the example?

In this case, we have embedded a diagram and instrumented the test to retrieve the values directly from the diagram. This makes it even more concise, removes the duplication and ensures we have a single source of truth.

scenario with svg

This proof of concept was developed using SVG diagrams with the Concordion tool.

We’re keen to see this concept developed further and extended to other tools.

Key takeaways

While the Given-When-Then (Gherkin) format helps us consider the context, action and outcome of scenarios, it easily becomes bloated and difficult to read.

In some cases, visualisations reduce our cognitive load, increasing our capacity for understanding and proving the old adage “a picture is worth a thousand words”.

Don’t be frightened to use alternative techniques to explore and document your scenarios.

When automating, explore the boundaries of your tool and then break them!

To find out more about Specification by Example, see our other thoughts and resources, or better still, request details of our training course and mentored learning.

Search the Assurity website (Hit ESC to cancel)