Writing Automated Smart Contract Tests
In a blockchain environment, a single mistake could cost you all of your funds - or even worse, your users' funds! This guide will help you develop robust applications by writing automated tests that verify your application behaves exactly as you intended.
We’ll cover the following topics:
About Testing
There is a a wide range of testing techniques, from simple manual verifications to complex end-to-end setups, all of them useful in their own way.
When it comes to smart contract development though, practice has shown that contract unit testing is exceptionally worthwhile. These tests are simple to write and quick to run, and let you add features and fix bugs in your code with confidence.
Smart contract unit testing consists of multiple small, focused tests, which each check a small part of your contract for correctness. They can often be expressed in single sentences that make up a specification, such as 'the admin is able to pause the contract', 'transferring tokens emits an event' or 'non-admins cannot mint new tokens'.
Setting up a Testing Environment
You may be wondering how we’re going to run these tests, since smart contracts are executed inside a blockchain. Using the actual Ethereum network would be very expensive, and while testnets are free, they are also slow (with blocktimes between 5 and 20 seconds). If we intend to run hundreds of tests whenever we make a change to our code, we need something better.
What we will use is called a local blockchain: a slimmed down version of the real thing, disconnected from the Internet, running on your machine. This will simplify things quite a bit: you won’t need to get Ether, and new blocks will be mined instantly.
To aid us in this we’ll use the OpenZeppelin Test Environment, a JavaScript library that will take care of setting up our local blockchain.
| If you’ve read the Deploying and Interacting guide, you will already be familiar with Ganache. This is what Test Environment uses under the hood, taking care of its configuration for you. |
To install the OpenZeppelin Test Environment, run:
$ npm install --save-dev @openzeppelin/test-environmentOnce you require the library from your JavaScript code, it will automatically run a local testing blockchain for you. It also exports a list of accounts that have been pre-funded with Ether and convenient ways to load your contracts from their compiled artifacts, among other utilities.
const { accounts, contract } = require('@openzeppelin/test-environment');
// Use the different accounts, which are unlocked and funded with Ether
const [ admin, deployer, user ] = accounts;
// Create a contract object from a compilation artifact
const MyContract = contract.fromArtifact('MyContract');For detailed information on these exported values and their usage, refer to Test Environment’s API reference.
Writing Unit Tests
In order to actually run your tests, you will need to also install a JavaScript test runner. You are free to use any of the recommended ones: for this guide, we’ll pick Mocha with Chai assertions.
$ npm install --save-dev mocha chaiCreate a test directory: this is where you will keep your test files. These are best structured by mirroring the contracts directory: for each .sol file there, create a corresponding .test.js file.
Time to write our first tests! These will test properties of the Box contract from previous guides: a simple contract that lets you retrieve a value the owner previously store d.
// test/Box.test.js
// Load dependencies
const { accounts, contract } = require('@openzeppelin/test-environment');
const { expect } = require('chai');
// Load compiled artifacts
const Box = contract.fromArtifact('Box');
// Start test block
describe('Box', function () {
const [ owner ] = accounts;
beforeEach(async function () {
// Deploy a new Box contract for each test
this.contract = await Box.new({ from: owner });
});
// Test case
it('retrieve returns a value previously stored', async function () {
// Store a value - recall that only the owner account can do this!
await this.contract.store(42, { from: owner });
// Test if the returned value is the same one
// Note that we need to use strings to compare the 256 bit integers
expect((await this.contract.retrieve()).toString()).to.equal('42');
});
});| Many books have been written about how to structure unit tests: for a quick reference, check out the tests for OpenZeppelin Contracts, or the following guide for ERC20 tests. |
We are now ready to run our tests! The best way to do this is by adding a test script to your package.json:
"scripts": {
+ "test": "mocha --exit --recursive test"
}With this, running npm test will execute all tests in the test directory, checking that your contracts work the way you meant them to:
$ npm test
Box
✓ retrieve returns a value previously stored|
Don’t forget to re-compile your contracts if you make changes to them! If you want to do this automatically on each test run, set your
|
Test Environment comes with sensible defaults that should work for most use-cases, but you can always configure it to provide more accounts or use different kinds of contract objects, among others.
It’s also a very good idea at this point to set up a Continuous Integration service such as CircleCI to make your tests run automatically every time you commit your code to GitHub.
Performing Complex Assertions
Many interesting properties of your contracts may be hard to capture, such as:
-
verifying that the contract reverts on errors
-
measuring by how much an account’s Ether balance changed
-
checking that the proper events are emitted
OpenZeppelin Test Helpers is a library designed to help you test all of these properties. It will also simplify the tasks of simulating time passing on the blockchain and handling very large numbers.
$ npm install --save-dev @openzeppelin/test-helpers// test/Box.test.js
const { accounts, contract } = require('@openzeppelin/test-environment');
const { expect } = require('chai');
// Import utilities from Test Helpers
const { BN, expectEvent, expectRevert } = require('@openzeppelin/test-helpers');
const Box = contract.fromArtifact('Box');
describe('Box', function () {
const [ owner, other ] = accounts;
// Use large integers ('big numbers')
const value = new BN('42');
beforeEach(async function () {
this.contract = await Box.new({ from: owner });
});
it('retrieve returns a value previously stored', async function () {
await this.contract.store(value, { from: owner });
// Use large integer comparisons
expect(await this.contract.retrieve()).to.be.bignumber.equal(value);
});
it('store emits an event', async function () {
const receipt = await this.contract.store(value, { from: owner });
// Test that a ValueChanged event was emitted with the new value
expectEvent(receipt, 'ValueChanged', { newValue: value });
});
it('non owner cannot store a value', async function () {
// Test a transaction reverts
await expectRevert(
this.contract.store(value, { from: other }),
'Ownable: caller is not the owner'
);
});
});No configuration is required: Test Environment will detect the Test Helpers and do the hard work for you.
These will test properties of the Box contract from previous guides: a simple contract that lets you retrieve a value the owner previously `store`d.
Run your tests again to see the Test Helpers in action:
$ npm test
Box
✓ retrieve returns a value previously stored
✓ store emits an event
✓ non owner cannot store a valueThe Test Helpers will let you write powerful assertions without having to worry about the low-level details of the underlying Ethereum libraries. To learn more about what you can do with them, head to their API reference.
| The OpenZeppelin Test Environment is not required to use the Test Helpers: to learn how to use them standalone or integrated in other systems, refer to their documentation. |