JavaScript testing helpers for Ethereum smart contract development. These are specially suited for truffle 5 (using web3 1.0). chai bn.js assertions using chai-bn are also included.
npm install --save-dev openzeppelin-test-helpers
const { BN, constants, expectEvent, shouldFail } = require('openzeppelin-test-helpers');
const ERC20 = artifacts.require('ERC20');
contract('ERC20', ([sender, receiver]) => {
beforeEach(async function () {
this.erc20 = ERC20.new();
this.value = new BN(1);
});
it('reverts when transferring tokens to the zero address', async function () {
await shouldFail.reverting(this.erc20.transfer(constants.ZERO_ADDRESS, this.value, { from: sender }));
});
it('emits a Transfer event on successful transfers', async function () {
const { logs } = this.erc20.transfer(receiver, this.value, { from: sender });
expectEvent.inLogs(logs, 'Transfer', { from: sender, to: receiver, value: this.value });
});
it('updates balances on successful transfers', async function () {
this.erc20.transfer(receiver, this.value, { from: sender });
(await this.token.balanceOf(receiver)).should.be.bignumber.equal(this.value);
});
});
This documentation is a work in progress: if in doubt, head over to the tests directory to see examples of how each helper can be used.
All returned numbers are of type BN.
Returns the current Ether balance of an account.
Returns the change in the Ether balance of an account caused by executing promiseFunc
(which will be awaited on).
(await balance.difference(receiver, () =>
send.ether(sender, receiver, ether('1')))
).should.be.bignumber.equal(ether('1'));
A bn.js object. Use new BN(number)
to create BN
instances.
Converts a value in Ether to wei.
A chai expect instance, containing the bignumber
property (via chai-bn).
expect(new BN('2')).to.be.bignumber.equal('2');
Asserts logs
contains an entry for an event with name eventName
, for which all entries in eventArgs
match.
Same as inLogs
, but for events emitted during the construction of contract
.
const contract = await MyContract.new(5);
await expectEvent.inConstruction(contract, 'Created', { value: 5 });
Same as inLogs
, but for events emitted in an arbitrary transaction (of hash txHash
), by an arbitrary contract (emitter
), even if it was indirectly called (i.e. if it was called by another smart contract and not an externally owned account).
Calculates the EIP 165 interface ID of a contract, given a series of function signatures.
Sends value
Ether from from
to to
.
Sends a transaction to contract target
, calling method name
with argValues
, which are of type argTypes
(as per the method's signature).
A chai should instance, containing the bignumber
property (via chai-bn).
Collection of assertions for failures (similar to chai's throw
). shouldFail
will accept any exception type, but more specific functions exist and their usage is encouraged.
Only accepts failures caused due to an EVM revert (e.g. a failed require
).
Like shouldFail.reverting
, this helper only accepts failures caused due to an EVM revert (e.g. a failed require
). Furthermore, it checks whether revert reason string includes passed message
. For example:
contract Owned {
address private _owner;
constructor () {
_owner = msg.sender;
}
function doOwnerOperation() public view {
require(msg.sender == _owner, "Unauthorized");
....
}
}
Can be tested as follows:
const { shouldFail } = require('openzeppelin-test-helpers');
const Owned = artifacts.require('Owned');
contract('Owned', ([owner, other]) => {
beforeEach(async function () {
this.owned = Owned.new();
});
describe('doOwnerOperation', function() {
it('Fails when called by a non-owner account', async function () {
await shouldFail.reverting.withMessage(this.owned.doOwnerOperation({ from: other }), "Unauthorized");
});
});
...
Use this helper to specify the expected error message, when you're testing a function that can revert for multiple reasons.
Only accepts failures due to a failed assert
(which executes an invalid opcode).
Only accepts failures due to the transaction running out of gas.
Forces a block to be mined, incrementing the block height.
Returns the timestamp of the latest mined block. Should be coupled with advanceBlock
to retrieve the current blockchain time.
Returns the latest mined block number.
Increases the time of the blockchain by duration
(in seconds), and mines a new block with that timestamp.
Same as increase
, but a target time is specified instead of a duration.
Helpers to convert different time units to seconds. Available helpers are: seconds
, minutes
, hours
, days
, weeks
and years
.
await time.increase(time.years(2));