When we talk about BDD a “way to automate tests” comes to mind, but actually Behavior Driven Development goes much further. This engineering practice includes techniques and tools that we apply since we raise our product’s requirements (not our tests’ requirements).

Certainly we define requirements in a more “testable” way but our goals when implementing BDD are “Building the right software” and “Building the software right“.

Almost no software that we create is isolated; it’s part of a business strategy and as such, it must be aligned with the business objectives. “Building the right software” is about building the correct software, the one that will meet the user’s expectations and that will solve their problem / need and that is perfectly aligned with the business objectives.

Building the software right” is about building it well, with the best practices and making sure that it is properly designed and developed, that will give us software that is more reliable and effective.


  • What is exactly Behaviour Driven Development?
  • How do we raise requirements in BDD?
  • How do we go from examples and requirements to Gherkin (Given / When / Then)?
  • and then… how do we go from Gherkin to code (scenarios, steps, step definitions)?
  • Is BDD useful as documentation?


If you prefer video format, you can watch it here


What is exactly Behaviour Driven Development?

Let’s start by defining what BDD is not. It isn’t a software development methodology. In no way does it replace Scrum or XP or whatever methodology we decide to use.

It’s an engineering practice (a set of practices and techniques) that we can implement in our development process, regardless of which methodology we use. We apply these practices to:

  1. Generate conversations around concrete examples to understand how the features provide value to the business.
  2. Express requirements in a more “testable” way, in a language that both stakeholders and development team can understand.
  3. Convert requirements into automated tests that guide development, verify / validate the feature and become documentation.


What do we want to achieve with BDD?

We want:

  • To Build the right software” and “To Build the software right” (concepts mentioned above).
  • Collaboration and collective understanding (stakeholders, business analysts, software developers, and testers). When we all collaborate on the design of the solution, we guarantee that all the capabilities of our team are being used to the maximum. Many times the client / user / sponsor comes to us not only with the problem but with what they consider to be the solution, and during the definition of requirements (and refinement) more ideas arise from UX designers, developers (who contribute their technical know-how to design the most optimal) and testers (and thus we have the opportunity to verify and validate from the beginning) to build this solution.
  • Deliver more value by identifying, understanding and building what matters most for the business.
  • Deliver more reliable and effective software (ensure that it is well designed and developed).


What do we test?

We test that the product behaves as we expect. Our tests describe how the product is expected to behave (from the users point of view); it doesn’t describe implementation details.

Our tests are written in a language that a user / stakeholder can understand and give us feedback about the expected behavior of the System Under Test.

We test features (or bugs), not components (or classes). To test components and classes we have the integration and the unit tests.

It is important to highlight that BDD is not a substitute for unit tests or integration tests. We want to ensure the quality of our software and, in order to achieve that, we require different types of tests as well as a full view of the quality of our product.


Defining requirements in BDD

To talk about requirements, let’s start defining 2 important concepts: Capabilities and features.

Capabilities give users / stakeholders the ability to perform some useful task or complete some business objective. The ability to “do something” (regardless of how we are going to implement it). For example, “the ability to purchase a foreign currency” is a capability.

Feature represents software functionality that we built to support the capability. “Purchase a foreign currency cash” is a feature.

A feature is a tangible and deliverable functionality that helps the business achieve its objectives. How do we identify whether or not it is a feature? It’s:

  • A specific action that the user can perform on the system.
  • Something that changes the state of the system.
  • Something that causes the system to interact with a third-party.

To define requirements with BDD we use the technique of “the 3 amigos” in requirements’ workshops. The 3 amigos are:

  • Product team: business analysts, product owner. It also extends to clients / users / sponsors who actively participate in the construction of our software.
  • Developers: development team.
  • Testers.

In these requirements’ definition workshops we use Example Mapping (a techinque which allows us to use examples to guide development). Many times we are trying to define requirements and we ask “could you give me an example?”

Imagine that we are a bank and our clients want to buy foreign currency.


In this post we go further into example mapping. The goal of this technique is to discover examples, group them in Business rules and features.

From these examples and features we are going to create our user stories.

Our user story to work on this example:

When we design the user story, the examples and rules already identified become our User Acceptance Criteria.


From Examples to Gherkin (Given / When / Then)

When we have our examples, we design our test scenario. Each scenario has steps that we express in Gherkin language: Given, When, Then, And, and But.

Gherkin is a non-technical language that can be read by anyone (as natural language) and that allows us to express behaviors.

The most important steps are:

  • Given: these are the preconditions for a scenario and preparation of the environment to execute our test.
  • When: the action to be performed by the user (the action under test).
  • Then: the expected result. What is the response we expect from the system?

Following our example of the bank and our clients who want to buy foreign currency, we designed this scenario:

Our example with example data in Gherkin language:

Then we write a more generic test, separating the data and converting it into variables that will allow us to run the same test with different data sets:

From Gherkin to source code (scenarios, steps, step definitions)

When we have our tests written in Gherkin, we can convert them into executable specifications (source code). In that way, we can automate our acceptance criteria.

To create these executable specifications, we use:

  • Feature file
  • Page Object Model
  • Step definitions


Here you can delve into Gerkin in source code by following the same case study as in this post.


Using BDD tests as documentation

  • Our tests written in Gherkin are one part of the documentation. They aren’t a complete documentation by themself, but they contribute to our documentation base.
  • Our tests are always up to date respect to our system under test (or “almost always” updated) and working. We can trust that this documentation is constantly being updated.
  • It’s easy to read and it’s illustrated with examples. This means that someone who joins our team can understand how it works, what we do (from a business point of view) and what users / customers expect from our product / service. In some cases it also helps us to know how our features were implemented.
  • It also helps us to get status on our project. At a certain moment we can know how many features we have (in our system under test) and how many scenarios are automated vs how many are still manual.


It is an engineering practice, not a methodology.

We test behaviors (features and / or bugs), not components nor classes.

We all collaborate: testers, developers and product team with clients / users / stakeholders in order to create the best solutions.

We deliver well-designed and built software that, in turn, is the correct software, the one that will meet the user’s expectations and will solve their problem / need and is perfectly aligned with the business objectives


Book BDD in Action. John Ferguson Smart.

Book Agile Testing Condensed. Lisa Crispin and Janet Gregory.

Web Zerobank (used to automate tests for this post).

Source code BDD Currency