or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-features.mdbalance-tracking.mdconstants-utilities.mdevent-testing.mdindex.mdrevert-testing.mdtime-manipulation.md
tile.json

tessl/npm-openzeppelin--test-helpers

JavaScript testing helpers for Ethereum smart contract development with assertions, event verification, balance tracking, and time manipulation.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@openzeppelin/test-helpers@0.5.x

To install, run

npx @tessl/cli install tessl/npm-openzeppelin--test-helpers@0.5.0

index.mddocs/

OpenZeppelin Test Helpers

OpenZeppelin Test Helpers is a comprehensive JavaScript testing library specifically designed for Ethereum smart contract development. It provides powerful utilities for testing Solidity contracts with assertions for transaction reverts, event emission verification, balance tracking, big number handling, and time manipulation in test environments.

Package Information

  • Package Name: @openzeppelin/test-helpers
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install --save-dev @openzeppelin/test-helpers

Core Imports

const {
  BN,           // Big Number support
  constants,    // Common constants
  expectEvent,  // Event assertions
  expectRevert, // Revert assertions
  balance,      // Balance tracking
  time,         // Time manipulation
  ether,        // Unit conversion
  snapshot,     // State snapshots
} = require('@openzeppelin/test-helpers');

For Hardhat users:

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

Basic Usage

const {
  BN,
  constants,
  expectEvent,
  expectRevert,
  balance,
  ether,
} = require('@openzeppelin/test-helpers');

contract('ERC20', function ([sender, receiver]) {
  beforeEach(async function () {
    this.value = new BN(1);
    this.erc20 = await ERC20.new();
  });

  it('reverts when transferring to zero address', async function () {
    await expectRevert(
      this.erc20.transfer(constants.ZERO_ADDRESS, this.value, { from: sender }),
      'ERC20: transfer to the zero address'
    );
  });

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

Architecture

OpenZeppelin Test Helpers is built around several key components:

  • Big Number Support: Built-in BN (BigNumber) library integration for precise arithmetic operations
  • Assertion Framework: Chai-based assertions with blockchain-specific extensions
  • Web3 Integration: Full compatibility with web3.js and Truffle/Hardhat environments
  • Lazy Loading: Modules are loaded on-demand to improve startup performance
  • Provider Abstraction: Automatic detection and configuration for different blockchain providers

Capabilities

Transaction Revert Testing

Comprehensive assertion utilities for testing transaction failures with specific error messages, gas limit errors, and invalid opcodes.

function expectRevert(promise, expectedError);
expectRevert.assertion(promise);
expectRevert.outOfGas(promise);
expectRevert.unspecified(promise);

Revert Testing

Event Emission Testing

Advanced event assertion utilities for verifying emitted events with parameter validation, supporting both Truffle and web3 receipt formats.

function expectEvent(receipt, eventName, eventArgs = {});
expectEvent.inConstruction(contract, eventName, eventArgs = {});
expectEvent.inTransaction(txHash, emitter, eventName, eventArgs = {});
expectEvent.notEmitted(receipt, eventName);

Event Testing

Balance Tracking

Elegant balance change tracking for Ethereum accounts with support for fee calculation and multiple units.

async function balance.current(account, unit = 'wei');
async function balance.tracker(owner, unit = 'wei');

interface BalanceTracker {
  get(unit?): Promise<BN>;
  delta(unit?): Promise<BN>;
  deltaWithFees(unit?): Promise<{ delta: BN, fees: BN }>;
}

Balance Tracking

Time Manipulation

Blockchain time and block manipulation utilities for testing time-dependent contract behavior in development networks.

function time.advanceBlock();
async function time.advanceBlockTo(target);
async function time.latest();
async function time.latestBlock();
async function time.increase(duration);
async function time.increaseTo(target);

const time.duration = {
  seconds: (val) => BN,
  minutes: (val) => BN,
  hours: (val) => BN,
  days: (val) => BN,
  weeks: (val) => BN,
  years: (val) => BN,
};

Time Manipulation

Constants and Utilities

Common Ethereum constants and utility functions for conversions, interface IDs, and transaction sending.

const constants = {
  ZERO_ADDRESS: string,
  ZERO_BYTES32: string,
  MAX_UINT256: BN,
  MAX_INT256: BN,
  MIN_INT256: BN,
};

function ether(n);
function makeInterfaceId.ERC165(functionSignatures = []);
function makeInterfaceId.ERC1820(interfaceName);

Constants and Utilities

Advanced Features

Singleton contract deployment, state snapshots, and transaction utilities for complex testing scenarios.

async function singletons.ERC1820Registry(funder);
async function snapshot();
async function send.ether(from, to, value);
async function send.transaction(target, name, argsTypes, argsValues, opts = {});

Advanced Features

Types

// BN (BigNumber) from web3.utils
class BN {
  constructor(value: string | number | BN);
  toString(): string;
  add(other: BN): BN;
  sub(other: BN): BN;
  mul(other: BN): BN;
  div(other: BN): BN;
  // ... additional BN methods
}

interface TransactionReceipt {
  logs?: Array<{ event: string, args: object }>;  // Truffle format
  events?: { [eventName: string]: { returnValues: object } }; // web3 format
}

interface ContractInstance {
  abi: Array<object>;
  address: string;
  transactionHash?: string;
}