OpenZeppelin Test Helpers 0.5

OpenZeppelin Test Helpers is a library of functions that come in handy when writing tests for smart contracts.

We’ve recently released a shiny new version. Here’s all the details!

Support for plain Web3.js workflows

The main change introduced in 0.5 is support for plain Web3.js workflows, without the need for a Truffle environment. This essentially means that the helpers that use or return contract abstractions (expectEvent and singletons) now also support instances of web3.eth.Contract. There may still be some small warts in this feature, so please let us know if you run into any issues!

const myContract = new web3.eth.Contract(abi, address);

await expectRevert(myContract.methods.fails().send(), 'Failed for reasons');

This should also open the door to using Test Helpers with other frameworks. If you have a favorite framework that you would like to see supported please let us know!

Revamped expectEvent

To support instances of web3.eth.Contract we’ve revamped the expectEvent helper. The previous expectEvent.inLogs is still available but has been deprecated. We recommend migrating to the new helper expectEvent(receipt, eventName, eventArgs) which will, quite magically :sparkles:, work with both Web3.js and Truffle receipts. (Note: a “receipt” is what’s contained in the Promise returned by contract function calls.)

const web3Receipt = await'bar').send();
expectEvent(web3Receipt, 'Foo', { value: 'bar' });

const truffleReceipt = await'bar');
expectEvent(truffleReceipt, 'Foo', { value: 'bar' });

Balance units

An additional new goodie included in this release is the possibility of reading an account’s balance in any unit. Whereas before these helpers always returned amounts in wei, you can now ask for amounts in ether, gwei, or anything supported by web3.js.

// Web3.js
new BN(web3.utils.fromWei(await web3.eth.getBalance(account), 'ether'))

// Test Helpers
await balance.current(account, 'ether')

Note that this also applies to the cool balance.tracker. If you’ve never heard about this one, it’s a great moment to check it out, since for this release we’ve improved its documentation.

Chai is now optional

As a small quality-of-life improvement, it is no longer necessary to install Chai side by side with Test Helpers. If you want to use it, you can install it, but it will no longer cause an error if it’s not present.


We have released this version under the new @openzeppelin npm scope, like the rest of the packages in the OpenZeppelin suite. So you will need to reinstall the package as @openzeppelin/test-helpers.

If you are using 0.4, we have a short upgrade guide that you can follow. It should be very simple.

All of this is already in use in the Contracts test suite, so feel free to use that as a reference. Also remember to use the documentation in the readme! We will be migrating it to our official docs site soon.


Amazing work! Dying to use. Would be cool if we could run smart contracts on any test framework like jest!:heart_eyes:


I :heart: the Test Helpers. (I am biased :smile:).

I upgraded my tests for and got the following error which had me stumped. Similar tests worked on

TypeError: this.erc1820.setInterfaceImplementer is not a function

I had forgotten that migrations were run as part of truffle test (even though in my tests I create new contract instances in beforeEach).

As per how to upgrade from 0.4 I needed to change in my migrations (2_deploy.js)

require('@openzeppelin/test-helpers/configure')({ web3 });


require('@openzeppelin/test-helpers/configure')({ provider: web3.currentProvider, environment: 'truffle' });
1 Like

wohoooo! Great work @frangio @nventuro


A post was split to a new topic: Has anyone used the OpenZeppelin Test Helpers with OZ SDK?