0
# Event Emission Testing
1

2
Advanced event assertion utilities for verifying emitted events with parameter validation, supporting both Truffle and web3 receipt formats. Essential for comprehensive smart contract testing.
3

4
## Capabilities
5

6
### Expect Event
7

8
Asserts that a specific event was emitted in a transaction receipt with optional parameter verification.
9

10
```javascript { .api }
11
/**
12
 * Assert that an event was emitted in a transaction receipt
13
 * @param {TransactionReceipt} receipt - Transaction receipt to check
14
 * @param {string} eventName - Name of the event to look for
15
 * @param {object} eventArgs - Optional object with expected event parameters
16
 * @returns {object} - The matching event object
17
 */
18
function expectEvent(receipt, eventName, eventArgs = {});
19
```
20

21
**Usage Examples:**
22

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

26
// Basic event assertion
27
const receipt = await token.transfer(recipient, amount);
28
expectEvent(receipt, 'Transfer');
29

30
// Event with parameter validation
31
expectEvent(receipt, 'Transfer', {
32
  from: sender,
33
  to: recipient,
34
  value: amount,
35
});
36

37
// Partial parameter matching
38
expectEvent(receipt, 'Approval', {
39
  owner: owner,
40
  // spender and value not checked
41
});
42
```
43

44
### Expect Event in Construction
45

46
Asserts that an event was emitted during contract construction.
47

48
```javascript { .api }
49
/**
50
 * Assert that an event was emitted during contract construction
51
 * @param {ContractInstance} contract - Truffle contract instance
52
 * @param {string} eventName - Name of the event to look for
53
 * @param {object} eventArgs - Optional object with expected event parameters
54
 * @returns {Promise<object>} - The matching event object
55
 */
56
async function expectEvent.inConstruction(contract, eventName, eventArgs = {});
57
```
58

59
**Usage Example:**
60

61
```javascript
62
// Check event emitted in constructor
63
const myContract = await MyContract.new(initialValue);
64
await expectEvent.inConstruction(myContract, 'Initialized', {
65
  value: initialValue,
66
});
67
```
68

69
### Expect Event in Transaction
70

71
Asserts that an event was emitted in a specific transaction by hash.
72

73
```javascript { .api }
74
/**
75
 * Assert that an event was emitted in a transaction by hash
76
 * @param {string} txHash - Transaction hash to check
77
 * @param {ContractInstance} emitter - Contract that should have emitted the event
78
 * @param {string} eventName - Name of the event to look for
79
 * @param {object} eventArgs - Optional object with expected event parameters
80
 * @returns {Promise<object>} - The matching event object
81
 */
82
async function expectEvent.inTransaction(txHash, emitter, eventName, eventArgs = {});
83
```
84

85
**Usage Example:**
86

87
```javascript
88
// Check event in external transaction
89
const tx = await web3.eth.sendTransaction({
90
  from: sender,
91
  to: contract.address,
92
  data: encodedData,
93
});
94

95
await expectEvent.inTransaction(tx.transactionHash, contract, 'DataReceived', {
96
  sender: sender,
97
  data: expectedData,
98
});
99
```
100

101
### Expect Event Not Emitted
102

103
Asserts that a specific event was NOT emitted in a transaction receipt.
104

105
```javascript { .api }
106
/**
107
 * Assert that an event was NOT emitted in a transaction receipt
108
 * @param {TransactionReceipt} receipt - Transaction receipt to check
109
 * @param {string} eventName - Name of the event that should not be present
110
 * @returns {void}
111
 */
112
function expectEvent.notEmitted(receipt, eventName);
113
```
114

115
**Usage Example:**
116

117
```javascript
118
// Ensure event was not emitted
119
const receipt = await token.approve(spender, 0);
120
expectEvent.notEmitted(receipt, 'Transfer');
121
```
122

123
### Expect Event Not Emitted in Construction
124

125
Asserts that an event was NOT emitted during contract construction.
126

127
```javascript { .api }
128
/**
129
 * Assert that an event was NOT emitted during contract construction
130
 * @param {ContractInstance} contract - Truffle contract instance
131
 * @param {string} eventName - Name of the event that should not be present
132
 * @returns {Promise<void>}
133
 */
134
async function expectEvent.notEmitted.inConstruction(contract, eventName);
135
```
136

137
### Expect Event Not Emitted in Transaction
138

139
Asserts that an event was NOT emitted in a specific transaction by hash.
140

141
```javascript { .api }
142
/**
143
 * Assert that an event was NOT emitted in a transaction by hash
144
 * @param {string} txHash - Transaction hash to check
145
 * @param {ContractInstance} emitter - Contract to check for events
146
 * @param {string} eventName - Name of the event that should not be present
147
 * @returns {Promise<void>}
148
 */
149
async function expectEvent.notEmitted.inTransaction(txHash, emitter, eventName);
150
```
151

152
## Receipt Format Support
153

154
The library automatically handles both receipt formats:
155

156
**Truffle Format:**
157
```javascript
158
{
159
  logs: [
160
    {
161
      event: 'Transfer',
162
      args: { from: '0x...', to: '0x...', value: BN }
163
    }
164
  ]
165
}
166
```
167

168
**Web3 Format:**
169
```javascript
170
{
171
  events: {
172
    'Transfer': {
173
      returnValues: { from: '0x...', to: '0x...', value: '1000' }
174
    }
175
  }
176
}
177
```
178

179
## Parameter Matching
180

181
Event parameter matching supports:
182

183
- **Exact matching**: String, number, and boolean values
184
- **Big Number matching**: Automatic BN comparison using chai-bn
185
- **Partial matching**: Only specified parameters are checked
186
- **Null values**: Explicit null parameter checking
187

188
```javascript
189
// Big Number parameter matching
190
expectEvent(receipt, 'Transfer', {
191
  value: new BN('1000000000000000000'), // 1 ether in wei
192
});
193

194
// Null parameter checking
195
expectEvent(receipt, 'Approval', {
196
  spender: constants.ZERO_ADDRESS,
197
  value: null, // explicitly check for null
198
});
199
```
200

201
## Error Messages
202

203
Detailed error messages help debug test failures:
204

205
```javascript
206
// When event not found:
207
// AssertionError: No 'Transfer' events found
208

209
// When parameters don't match:
210
// AssertionError: expected event argument 'value' to have value 1000 but got 500
211
```