Test your Blockchain business network using Hyperledger Composer

Firstly, some quick background. What is Hyperledger Composer? It’s a framework for rapidly building Blockchain business networks on top of a Blockchain platform, such as Hyperledger Fabric. It’s pretty cool. You can find some more information here: http://hyperledger.github.io/composer/

Blockchain is a technology for building networks that connect organizations together. Once started, a Blockchain network allows participants to transfer assets between each other by submitting transactions, and those transactions are recorded in an immutable ledger.

Smart contracts define the rules for transactions in a Blockchain network. These rules are written in code, by a Blockchain developer. In Hyperledger Composer, these rules are written in JavaScript and they are known as transaction processor functions; other Blockchain technologies may require different languages, but the smart contract concept is always the same.

And this is where the importance of testing comes in for Blockchain; if your smart contracts — your code — are faulty in any way, the participants in that network are at risk of losing assets. Worst case scenario, a bug in your code could put the participants at risk of breaking the terms of a legal contract, or you could turn into the next DAO.

When writing smart contracts, you should always be writing accompanying tests that confirm the behaviour of your smart contract under a wide range of different conditions:

  • How does it handles valid and invalid inputs?
  • How does it cope with a wide range of input data?
  • How does it handle missing state, or existing state?
  • How does it handle error cases?
  • How does it handle security and access control?

Hyperledger Composer includes features that allow you to easily write and automate tests for your smart contracts, or business network definitions. These tests can automatically deploy the business network definition, and then interact with it by submitting queries and transactions in order to test how that business network really behaves.

This weeks release, v0.7.4, includes a new Node.js module that I’m hoping will make the implementation of this testing much more accessible to a wider range of developers — composer-cucumber-steps — which allows a tester to write tests in a natural language style that more closely reflects the business use case and requirements.

But before we go into that, lets look at the functionality that existed prior to this release — the ability to write business network tests in JavaScript using any standard JavaScript testing library, for example Mocha and Chai.

Hyperledger Composer is mostly written in JavaScript; at a guesstimate, 90% of our code is Blockchain platform independent JavaScript. This means that we can run the core “runtime” in any JavaScript engine, even outside of a real Blockchain platform. We have an “embedded runtime” that persists data in memory for exactly this purpose: composer-runtime-embedded.

However, you can also execute tests against a business network definition that has been deployed to a real Blockchain platform. This shouldn’t be a choice of one or the other — you should be testing against the embedded runtime first for near-immediate feedback during the development cycle, and then retest against the real thing once you’re happy that it looks good.

Our basic-sample-network provides a fully featured example of using the embedded runtime to test a business network definition. You can find a version of the tests written using Mocha and Chai here: sample.js

Note that the tests are quite code-heavy, and that the behaviour and the assertions in the tests are not immediately clear to someone who is not familiar with JavaScript testing.

We have a “business analyst” persona in mind when building Hyperledger Composer; a user who is not really that technical, but who is intimately familiar with the business use cases and requirements — and I suspect that our business analyst would struggle to either write or validate tests written by a JavaScript developer in this style.

So, now we have an alternative, Cucumber, which allows you to write BDD (Behaviour Driven Development) tests using Gherkin, a language which lets you produce tests in natural language that are easy to read and comprehend.

The structure of these tests is very simple. Here’s an example:

Feature: Marbles marketplace

Scenario: I can sell two marbles
Given I have 5 dollars
And I have 2 marbles
When I sell my marbles for 10 dollars each
Then I should have 25 dollars
And I should have no marbles

The specification for the Gherkin language itself is smaller than you might expect. It provides a few options for declaring and describing tests, Feature and Scenario, and a few keywords for declaring test steps: Given, When, Then, And. Looks pretty easy right?

The gotcha is that somebody has to write code for the steps that maps the natural language into actual executing code. There’s no magic here!

The good news is that in this case, we are your somebody. We have already done that work for Hyperledger Composer, and you can benefit today. The new composer-cucumber-steps library is a small, reusable collection of Cucumber steps for writing business network definition tests.

To demonstrate this, our basic-sample-network now also provides a version of the tests written using Cucumber. This version is a duplicate of the same tests written using Mocha — so that you can compare the two approaches. You can find the Cucumber version of the tests here: sample.feature

I am hoping that this new Cucumber style of test appeals to a much wider selection of our users, and even might appeal to those who are regularly writing Mocha style tests — but it’s still early days. So I’d love to hear what you think of this new style of test, and what additional step definitions do you think we should provide in the steps library?

Note that the documentation on the available steps is lacking a bit at the moment — expect something to go up on the documentation site over the next week!

If you fancy looking at the source code that sits behind the step definitions themselves, or you want to take a stab at contributing new step definitions, then you can find the source code for the step definitions in the Hyperledger Composer GitHub repository here: composer-cucumber-steps

Finally, the execution of both of these style of tests can be easily automated and you should be thinking about integrating the execution of the tests into your continuous integration system of choice, for example Travis CI.

The basic-sample-network has standard npm test automation for running both styles of tests, using either the mocha or cucumber-js test driver programs: package.json

If the tests for this business network fail — either because the tests are bad, or we break the business network definition — then the build breaks, the changes do not get merged, the changes do not get pushed into production, and we get to sleep soundly in our beds at night knowing all should be well with our Blockchain business network.

Make sure you are writing tests for your Blockchain business network and not losing any sleep.