0
# jest-expect-message
1
2
jest-expect-message extends Jest's expect function to support custom error messages, allowing developers to provide more descriptive failure messages when assertions fail. It provides seamless integration with existing Jest test suites and maintains full compatibility with all Jest matchers.
3
4
## Package Information
5
6
- **Package Name**: jest-expect-message
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript support)
9
- **Installation**: `npm install --save-dev jest-expect-message`
10
11
## Core Imports
12
13
This package is a Jest setup extension and is imported through Jest configuration rather than direct import statements:
14
15
**Jest v24+ Configuration:**
16
```json
17
{
18
"jest": {
19
"setupFilesAfterEnv": ["jest-expect-message"]
20
}
21
}
22
```
23
24
**Jest v23- Configuration:**
25
```json
26
{
27
"jest": {
28
"setupTestFrameworkScriptFile": "jest-expect-message"
29
}
30
}
31
```
32
33
**Custom Setup File:**
34
```javascript
35
import 'jest-expect-message';
36
```
37
38
**TypeScript Configuration:**
39
```json
40
{
41
"files": ["node_modules/jest-expect-message/types/index.d.ts"]
42
}
43
```
44
45
## Basic Usage
46
47
```javascript
48
// Basic custom message
49
test('should add numbers correctly', () => {
50
expect(1 + 1, 'Addition should work correctly').toBe(2);
51
});
52
53
// Custom message with options
54
test('should validate user input', () => {
55
const user = { name: 'Alice', age: 25 };
56
expect(user.age, 'Age should be a valid number', {
57
showPrefix: false
58
}).toBeGreaterThan(18);
59
});
60
61
// Works with all Jest matchers
62
test('should handle arrays', () => {
63
const items = ['apple', 'banana'];
64
expect(items, 'Array should contain expected items').toContain('apple');
65
});
66
67
// Async expectations
68
test('should handle promises', async () => {
69
await expect(
70
Promise.resolve('success'),
71
'Promise should resolve with success message'
72
).resolves.toBe('success');
73
});
74
```
75
76
## Capabilities
77
78
### Enhanced Expect Function
79
80
The core functionality that enhances Jest's expect function to accept custom messages.
81
82
```javascript { .api }
83
/**
84
* Enhanced expect function with custom message support
85
* @param actual - The value to test (same as standard Jest expect)
86
* @param message - Optional custom error message to display on failure
87
* @param options - Optional configuration for message display
88
* @returns Jest matchers with custom message support
89
*/
90
expect(actual, message?, options?);
91
```
92
93
**Parameters:**
94
- `actual`: `any` - The value you would normally pass into an expect to assert against
95
- `message`: `string` (optional) - Custom message displayed when the expectation fails
96
- `options`: `MessageOptions` (optional) - Configuration object controlling message display
97
98
**Returns:** Standard Jest matchers (`JestMatchers<T>`) with custom message functionality
99
100
### Message Display Options
101
102
Configuration object for controlling how custom messages are displayed in test failures.
103
104
```javascript { .api }
105
interface MessageOptions {
106
/** Show "Custom message:" prefix before the message. Default: true */
107
showPrefix?: boolean;
108
/** Show the original matcher error message. Default: true */
109
showMatcherMessage?: boolean;
110
/** Show the stack trace in error output. Default: true */
111
showStack?: boolean;
112
}
113
```
114
115
**Properties:**
116
- `showPrefix`: `boolean` - Controls whether "Custom message:" prefix is shown (default: `true`)
117
- `showMatcherMessage`: `boolean` - Controls whether original Jest matcher message is shown (default: `true`)
118
- `showStack`: `boolean` - Controls whether stack trace is included in error output (default: `true`)
119
120
### Enhanced Expect.extend Method
121
122
The enhanced expect function preserves Jest's `extend` functionality for adding custom matchers.
123
124
```javascript { .api }
125
/**
126
* Extend Jest with custom matchers while preserving message functionality
127
* @param matchers - Object containing custom matcher functions
128
*/
129
expect.extend(matchers);
130
```
131
132
**Parameters:**
133
- `matchers`: `object` - Custom matchers to add to Jest's expect function
134
135
**Usage Example:**
136
```javascript
137
expect.extend({
138
toBeDivisibleBy(received, argument) {
139
const pass = received % argument === 0;
140
const message = pass
141
? () => `expected ${received} not to be divisible by ${argument}`
142
: () => `expected ${received} to be divisible by ${argument}`;
143
return { message, pass };
144
}
145
});
146
147
// Use custom matcher with custom message
148
test('custom matcher with message', () => {
149
expect(100, '100 should be divisible by 10').toBeDivisibleBy(10);
150
});
151
```
152
153
## Message Display Examples
154
155
### Default Message Display
156
157
```javascript
158
test('default message display', () => {
159
expect(1 + 1, 'Math should work correctly').toBe(3);
160
});
161
```
162
163
**Error Output:**
164
```
165
Custom message:
166
Math should work correctly
167
168
expect(received).toBe(expected) // Object.is equality
169
170
Expected: 3
171
Received: 2
172
```
173
174
### Hide Message Prefix
175
176
```javascript
177
test('hide prefix', () => {
178
expect(1 + 1, 'Math should work correctly', {
179
showPrefix: false
180
}).toBe(3);
181
});
182
```
183
184
**Error Output:**
185
```
186
Math should work correctly
187
188
expect(received).toBe(expected) // Object.is equality
189
190
Expected: 3
191
Received: 2
192
```
193
194
### Hide Original Matcher Message
195
196
```javascript
197
test('hide matcher message', () => {
198
expect(1 + 1, 'Math should work correctly', {
199
showMatcherMessage: false
200
}).toBe(3);
201
});
202
```
203
204
**Error Output:**
205
```
206
Custom message:
207
Math should work correctly
208
```
209
210
### Hide Stack Trace
211
212
```javascript
213
test('hide stack trace', () => {
214
expect(1 + 1, 'Math should work correctly', {
215
showStack: false
216
}).toBe(3);
217
});
218
```
219
220
**Error Output:**
221
```
222
Custom message:
223
Math should work correctly
224
225
expect(received).toBe(expected) // Object.is equality
226
227
Expected: 3
228
Received: 2
229
```
230
231
## TypeScript Support
232
233
The package includes comprehensive TypeScript definitions for type safety and IntelliSense support.
234
235
```typescript { .api }
236
declare namespace jest {
237
interface Expect {
238
<T = any>(
239
actual: T,
240
message?: string,
241
options?: {
242
showMatcherMessage?: boolean;
243
showPrefix?: boolean;
244
showStack?: boolean
245
}
246
): JestMatchers<T>;
247
}
248
}
249
```
250
251
**TypeScript Usage:**
252
```typescript
253
test('TypeScript example', () => {
254
const user: { name: string; age: number } = { name: 'Alice', age: 25 };
255
expect(user.age, 'Age should be valid').toBeGreaterThan(0);
256
});
257
```
258
259
## Compatibility and Integration
260
261
### Jest Matcher Compatibility
262
263
- **All Standard Matchers**: Works with `toBe`, `toEqual`, `toContain`, `toBeGreaterThan`, etc.
264
- **Negation Matchers**: Compatible with `.not` modifiers
265
- **Async Matchers**: Supports `.resolves` and `.rejects` for Promise testing
266
- **Custom Matchers**: Integrates seamlessly with `expect.extend()` custom matchers
267
- **Asymmetric Matchers**: Works with `expect.any()`, `expect.objectContaining()`, etc.
268
269
### ESLint Configuration
270
271
When using ESLint with jest rules, configure to allow 2 arguments for expect:
272
273
```json { .api }
274
{
275
"rules": {
276
"jest/valid-expect": [
277
"error",
278
{
279
"maxArgs": 2
280
}
281
]
282
}
283
}
284
```
285
286
### Setup Requirements
287
288
The package must be loaded before Jest runs tests. It modifies the global `expect` function to add message support while preserving all existing functionality.
289
290
**Important Notes:**
291
- No runtime dependencies
292
- Compatible with all Jest versions
293
- Preserves all existing Jest functionality
294
- Adds zero overhead when messages are not used
295
- Maintains full TypeScript type safety