Design of Smart contracts using BDD and Cucumber

Joaquín Alfaro
Published in
4 min readSep 4, 2019


This article shows how to apply BDD with Cucumber to design Smart contracts.

What is BDD?

BDD stands for Behaviour-driven development and it is a development methodology based on:

  • Definition of system behaviour based on stories, rules and examples.
  • Usage of TDD (Test Driven Development) taking as input the scenarios identified in the definition of the behaviour.

What is Cucumber?

Cucumber is a set of tools and mechanisms to apply BDD. It provides libraries to apply BDD for java and many other languages.

Why BBD to design Smart contracts?

  • The main goal of smart contracts is to define behaviour — rules and penalties around an agreement —
  • Boundary between requirements and smart contract design is really thin.
  • Stakeholders, domain owners etc. — lawyers, notaries etc. — need to understand the content of smart contracts and BDD Cucumber provides a high level language — Gherkin — that allows stakeholders to understand smart contracts without knowledge of programming languages.
  • The docs proposed by BDD Cucumber are perfect as documentation of the behaviour of smart contracts, it is not required additional docs.
  • Errors in smart contracts can be catastrophic as they specify an agreement and that agreement can be changed once is signed.

Example: Auction smart contract

In this example we are going to design a smart contract for Auctions using BDD as methodology and Cucumber JS package to specify features for nodejs/javascript.

Example mapping: Features, rules and examples

Example mapping is a technique to define the behaviour of user stories based in examples. The result is a dashboard with cards related to user stories (yellow cards), rules (blue cards) and examples (green cards).

Below you will find the dashboard for the main features of the Auction process that the smart contract must comply.

User story “Auction Opening”

The auctioneer opens the auction by announcing a suggested opening bid, a starting price or reserve for the item on sale.

The above user story is translated to Gherkin in a feature file of cucumber-js. Rules (blue cards) are translated to Scenario and the examples (green cards) to sequences of Given-When-Then

Cucumber feature for user story Auction opening

User story “Bidding”

The auctioneer accepts increasingly higher bids from the floor, consisting of buyers with an interest in the item. The auctioneer usually determines the minimum increment of bids, often raising it when bidding goes high.

Cucumber feature for user story Auction opening

The above user story is translated to Gherkin in a feature file of cucumber-js. Rules (blue cards) correspond to Scenario blocks and examples (green cards) to sequences of Given-When-Then

Smart contract

The Auction smart contract or Dapp will be developed in Solidity for Ethereum and it will packaged in a nodejs project.

The nodejs project depends on the following modules:

  • cucumber to specify testings grouped in features.
  • ganache-cli to simulate an Ethereum node for testing purpose.
  • web3 as the client with Ethereum.
  • solc for compilation of the smart contract. It is posible to compile smart contracts with truffle or from the terminal.
$ npm install cucumber ganache-cli web3 solc --save-dev

Folders structure

  • contracts. Sources of smart contracts
  • features. This folder contains the files that define features and it will be a feature file by user story. The language for features Gherkin
  • features/step_definitions. This folder depends on features and it includes by feature a file with the tests Given-When-Then applied for the feature. The language of step_definitions is similar to any javascript test — think of chain, mocha etc. —

For example auction_opening.feature references the user story “Auction opening” and step_definitions/auction_opening_steps.js contains the tests for the feature auction_opening

Execution of tests

  1. Compile smart contracts (it is possible to compile contracts using truffle or solc from the terminal I use solc-js to avoid additional steps and focus on BDD and cucumber)
$ npm run compile

2. Launch tests

$ npm test

Recommended stack

VS Code with Cucumber (Gherkin) Full Support plugin as editor of Smart contracts as digital dashboard for features —”Analog” dashboards and post it are nicer but less eco friendly —

Github repository


Get Best Software Deals Directly In Your Inbox