0
# Transaction Revert Testing
1

2
Comprehensive assertion utilities for testing transaction failures with specific error messages, gas limit errors, and invalid opcodes. Essential for ensuring smart contracts fail gracefully under invalid conditions.
3

4
## Capabilities
5

6
### Expect Revert
7

8
Tests that a transaction reverts with a specific error message.
9

10
```javascript { .api }
11
/**
12
 * Assert that a promise rejects with a specific revert reason
13
 * @param {Promise} promise - Promise that should revert
14
 * @param {string} expectedError - Expected revert reason string
15
 * @returns {Promise<void>} - Resolves if assertion passes
16
 */
17
async function expectRevert(promise, expectedError);
18
```
19

20
**Usage Example:**
21

22
```javascript
23
const { expectRevert } = require('@openzeppelin/test-helpers');
24

25
// Test with specific revert reason
26
await expectRevert(
27
  token.transfer(constants.ZERO_ADDRESS, 100),
28
  'ERC20: transfer to the zero address'
29
);
30

31
// Test with custom contract error
32
await expectRevert(
33
  myContract.restrictedFunction({ from: unauthorizedUser }),
34
  'Ownable: caller is not the owner'
35
);
36
```
37

38
### Expect Revert Assertion
39

40
Tests that a transaction reverts due to an assertion failure (invalid opcode).
41

42
```javascript { .api }
43
/**
44
 * Assert that a promise rejects with an assertion failure
45
 * @param {Promise} promise - Promise that should fail with assertion
46
 * @returns {Promise<void>} - Resolves if assertion passes
47
 */
48
function expectRevert.assertion(promise);
49
```
50

51
**Usage Example:**
52

53
```javascript
54
// Test assertion failure (invalid opcode)
55
await expectRevert.assertion(
56
  myContract.functionWithAssert()
57
);
58
```
59

60
### Expect Revert Out of Gas
61

62
Tests that a transaction reverts due to running out of gas.
63

64
```javascript { .api }
65
/**
66
 * Assert that a promise rejects due to out of gas error
67
 * @param {Promise} promise - Promise that should run out of gas
68
 * @returns {Promise<void>} - Resolves if assertion passes
69
 */
70
function expectRevert.outOfGas(promise);
71
```
72

73
**Usage Example:**
74

75
```javascript
76
// Test out of gas scenario
77
await expectRevert.outOfGas(
78
  myContract.expensiveFunction({ gas: 21000 })
79
);
80
```
81

82
### Expect Revert Unspecified
83

84
Tests that a transaction reverts without checking the specific error message.
85

86
```javascript { .api }
87
/**
88
 * Assert that a promise rejects with any revert reason
89
 * @param {Promise} promise - Promise that should revert
90
 * @returns {Promise<void>} - Resolves if assertion passes
91
 */
92
function expectRevert.unspecified(promise);
93
```
94

95
**Usage Example:**
96

97
```javascript
98
// Test any revert without specific message
99
await expectRevert.unspecified(
100
  myContract.unstableFunction()
101
);
102
```
103

104
## Provider Compatibility
105

106
The library automatically detects and validates revert reason support:
107

108
- **Ganache >=2.2.0**: Full revert reason support
109
- **Hardhat**: Full revert reason support  
110
- **Other providers**: Limited support with warnings
111

112
**Note**: For providers without revert reason support, use `expectRevert.unspecified()` to avoid false negatives.
113

114
## Error Handling
115

116
The library provides detailed error messages when assertions fail:
117

118
```javascript
119
// If wrong revert reason is encountered:
120
// AssertionError: Wrong kind of exception received
121
// Expected: "ERC20: transfer to the zero address"
122
// Actual: "ERC20: insufficient balance"
123
```