0
# OpenZeppelin Test Helpers
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @openzeppelin/test-helpers
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install --save-dev @openzeppelin/test-helpers`
10

11
## Core Imports
12

13
```javascript
14
const {
15
  BN,           // Big Number support
16
  constants,    // Common constants
17
  expectEvent,  // Event assertions
18
  expectRevert, // Revert assertions
19
  balance,      // Balance tracking
20
  time,         // Time manipulation
21
  ether,        // Unit conversion
22
  snapshot,     // State snapshots
23
} = require('@openzeppelin/test-helpers');
24
```
25

26
For Hardhat users:
27

28
```bash
29
npm install --save-dev @nomiclabs/hardhat-web3 web3
30
```
31

32
## Basic Usage
33

34
```javascript
35
const {
36
  BN,
37
  constants,
38
  expectEvent,
39
  expectRevert,
40
  balance,
41
  ether,
42
} = require('@openzeppelin/test-helpers');
43

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

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

57
  it('emits Transfer event on successful transfers', async function () {
58
    const receipt = await this.erc20.transfer(receiver, this.value, { from: sender });
59
    
60
    expectEvent(receipt, 'Transfer', {
61
      from: sender,
62
      to: receiver,
63
      value: this.value,
64
    });
65
  });
66
});
67
```
68

69
## Architecture
70

71
OpenZeppelin Test Helpers is built around several key components:
72

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

79
## Capabilities
80

81
### Transaction Revert Testing
82

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

85
```javascript { .api }
86
function expectRevert(promise, expectedError);
87
expectRevert.assertion(promise);
88
expectRevert.outOfGas(promise);
89
expectRevert.unspecified(promise);
90
```
91

92
[Revert Testing](./revert-testing.md)
93

94
### Event Emission Testing
95

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

98
```javascript { .api }
99
function expectEvent(receipt, eventName, eventArgs = {});
100
expectEvent.inConstruction(contract, eventName, eventArgs = {});
101
expectEvent.inTransaction(txHash, emitter, eventName, eventArgs = {});
102
expectEvent.notEmitted(receipt, eventName);
103
```
104

105
[Event Testing](./event-testing.md)
106

107
### Balance Tracking
108

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

111
```javascript { .api }
112
async function balance.current(account, unit = 'wei');
113
async function balance.tracker(owner, unit = 'wei');
114

115
interface BalanceTracker {
116
  get(unit?): Promise<BN>;
117
  delta(unit?): Promise<BN>;
118
  deltaWithFees(unit?): Promise<{ delta: BN, fees: BN }>;
119
}
120
```
121

122
[Balance Tracking](./balance-tracking.md)
123

124
### Time Manipulation
125

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

128
```javascript { .api }
129
function time.advanceBlock();
130
async function time.advanceBlockTo(target);
131
async function time.latest();
132
async function time.latestBlock();
133
async function time.increase(duration);
134
async function time.increaseTo(target);
135

136
const time.duration = {
137
  seconds: (val) => BN,
138
  minutes: (val) => BN,
139
  hours: (val) => BN,
140
  days: (val) => BN,
141
  weeks: (val) => BN,
142
  years: (val) => BN,
143
};
144
```
145

146
[Time Manipulation](./time-manipulation.md)
147

148
### Constants and Utilities
149

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

152
```javascript { .api }
153
const constants = {
154
  ZERO_ADDRESS: string,
155
  ZERO_BYTES32: string,
156
  MAX_UINT256: BN,
157
  MAX_INT256: BN,
158
  MIN_INT256: BN,
159
};
160

161
function ether(n);
162
function makeInterfaceId.ERC165(functionSignatures = []);
163
function makeInterfaceId.ERC1820(interfaceName);
164
```
165

166
[Constants and Utilities](./constants-utilities.md)
167

168
### Advanced Features
169

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

172
```javascript { .api }
173
async function singletons.ERC1820Registry(funder);
174
async function snapshot();
175
async function send.ether(from, to, value);
176
async function send.transaction(target, name, argsTypes, argsValues, opts = {});
177
```
178

179
[Advanced Features](./advanced-features.md)
180

181
## Types
182

183
```javascript { .api }
184
// BN (BigNumber) from web3.utils
185
class BN {
186
  constructor(value: string | number | BN);
187
  toString(): string;
188
  add(other: BN): BN;
189
  sub(other: BN): BN;
190
  mul(other: BN): BN;
191
  div(other: BN): BN;
192
  // ... additional BN methods
193
}
194

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

200
interface ContractInstance {
201
  abi: Array<object>;
202
  address: string;
203
  transactionHash?: string;
204
}
205
```