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// Import all required modules from openzeppelin-test-helpers
const { BN, constants, expectEvent, expectRevert } = require('openzeppelin-test-helpers');
// Import preferred chai flavor: both expect and should are supported
const { expect } = require('chai');
const ERC20 = artifacts.require('ERC20');
contract('ERC20', ([sender, receiver]) => {
beforeEach(async function () {
this.erc20 = await ERC20.new();
this.value = new BN(1); // The bundled BN library is the same one truffle and web3 use under the hood
});
it('reverts when transferring tokens to the zero address', async function () {
// Edge cases that trigger a require statement can be tested for, optionally checking the revert reason as well
await expectRevert.unspecified(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 });
// Log-checking will not only look at the event name, but also the values, which can be addresses, strings, numbers, etc.
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 });
// chai-bn is installed, which means BN values can be tested and compared using the bignumber property in chai
expect(await this.token.balanceOf(receiver)).to.be.bignumber.equal(this.value);
});
});By default, this library will look for a global web3 instance, but you can run a manual configuration and supply a custom one.
require('openzeppelin-test-helpers/configure')({ web3: ... });
const { expectEvent } = require('openzeppelin-test-helpers');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.
Helper to keep track of ether balances of a specific account
Returns the current balance of an account
const balance = await balance.current(account)Returns the current Ether balance of an account.
const balanceTracker = await balance.tracker(account) //instantiation
const accounBalance = await balanceTracker.get() //returns the current balance of accountReturns the change in the Ether since the last check(either get() or delta())
const balanceTracker = await balance.tracker(receiver)
send.ether(sender, receiver, ether('10'))
(await balanceTracker.delta()).should.be.bignumber.equal('10');
(await balanceTracker.delta()).should.be.bignumber.equal('0');Or using get():
const balanceTracker = await balance.tracker(account) //instantiation
const accounBalance = await balanceTracker.get() //returns the current balance of account
(await balanceTracker.delta()).should.be.bignumber.equal('0');A bn.js object. Use new BN(number) to create BN instances.
A collection of useful constants.
The initial value of a type address variable, i.e., address(0) in Solidity.
The maximum unsigned integer 2^256 - 1 represented in BN.
The maximum signed integer 2^255 - 1 represented in BN.
The minimum signed integer -2^255 represented in BN.
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 ERC165 interface ID of a contract, given a series of function signatures.
Calculates the ERC1820 interface hash of a contract, given its name.
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 transaction errors (similar to chai's throw).
This helper asserts that promise was rejected due to a reverted transaction, and it will check that the revert reason includes message. Use expectRevert.unspecified when the revert reason is unknown. 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 { expectRevert } = 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 expectRevert(this.owned.doOwnerOperation({ from: other }), "Unauthorized");
});
});
...This helper asserts that promise was rejected due to a reverted transaction caused by a require or revert statement.
This helper asserts that promise was rejected due to a reverted transaction caused by an assert statement or an invalid opcode.
This helper asserts that promise was rejected due to a transaction running out of gas.
Returns an instance of an ERC1820Registry deployed as per the specification (i.e. the registry is located at the canonical address). This can be called multiple times to retrieve the same instance.
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.duration.years(2));