OpenZeppelin Test Helpers

Assertion library for Ethereum smart contract testing. Make sure your contracts behave as expected.

• Check that transactions revert for the correct reason
• Verify that events were emitted with the right values
• Track balance changes elegantly
• Handle very large numbers
• Simulate the passing of time

Test Helpers integrates seamlessly with OpenZeppelin Test Environment, but it also supports Truffle tests and regular web3 workflows.

Overview

Installation

npm install --save-dev @openzeppelin/test-helpers

Hardhat (formerly Buidler)

Install web3 and the hardhat-web3 plugin.

npm install --save-dev @nomiclabs/hardhat-web3 web3

Remember to include the plugin in your configuration as explained in the installation instructions.

Usage

Import @openzeppelin/test-helpers in your test files to access the different assertions and utilities.

Note: The following snippet uses OpenZeppelin Test Environment: a Truffle-based setup would work the same way.

const { accounts, contract } = require('@openzeppelin/test-environment');

const {
  BN,           // Big Number support
  constants,    // Common constants, like the zero address and largest integers
  expectEvent,  // Assertions for emitted events
  expectRevert, // Assertions for transactions that should fail
} = require('@openzeppelin/test-helpers');

const ERC20 = contract.fromArtifact('ERC20');

describe('ERC20', function () {
  const [sender, receiver] =  accounts;

  beforeEach(async function () {
    // The bundled BN library is the same one web3 uses under the hood
    this.value = new BN(1);

    this.erc20 = await ERC20.new();
  });

  it('reverts when transferring tokens to the zero address', async function () {
    // Conditions that trigger a require statement can be precisely tested
    await expectRevert(
      this.erc20.transfer(constants.ZERO_ADDRESS, this.value, { from: sender }),
      'ERC20: transfer to the zero address',
    );
  });

  it('emits a Transfer event on successful transfers', async function () {
    const receipt = await this.erc20.transfer(
      receiver, this.value, { from: sender }
    );

    // Event assertions can verify that the arguments are the expected ones
    expectEvent(receipt, 'Transfer', {
      from: sender,
      to: receiver,
      value: this.value,
    });
  });

  it('updates balances on successful transfers', async function () {
    this.erc20.transfer(receiver, this.value, { from: sender });

    // BN assertions are automatically available via chai-bn (if using Chai)
    expect(await this.erc20.balanceOf(receiver))
      .to.be.bignumber.equal(this.value);
  });
});

Learn More

• Head to Configuration for advanced settings.
• For detailed usage information, take a look at the API Reference.

License

MIT