0
# Core Matchers
1

2
Essential assertion methods for equality, truthiness, and basic comparisons. These form the foundation of most test assertions in Jest.
3

4
## Capabilities
5

6
### Equality Matchers
7

8
#### toBe
9

10
Performs exact equality comparison using `===` (referential equality).
11

12
```javascript { .api }
13
/**
14
 * Tests exact equality using === comparison
15
 * @param expected - Expected value for strict equality
16
 */
17
ExpectationObject.toBe(expected: any): void;
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
expect(1).toBe(1);
24
expect('hello').toBe('hello');
25
expect(true).toBe(true);
26

27
// Objects and arrays check reference equality
28
const obj = {name: 'John'};
29
expect(obj).toBe(obj);  // passes
30
expect({name: 'John'}).toBe({name: 'John'});  // fails - different references
31
```
32

33
#### toEqual
34

35
Performs deep equality comparison with recursive checking of object properties and array elements.
36

37
```javascript { .api }
38
/**
39
 * Tests deep equality using custom equality logic
40
 * @param expected - Expected value for deep equality comparison
41
 */
42
ExpectationObject.toEqual(expected: any): void;
43
```
44

45
**Usage Examples:**
46

47
```javascript
48
expect({name: 'John', age: 30}).toEqual({name: 'John', age: 30});
49
expect([1, 2, 3]).toEqual([1, 2, 3]);
50
expect(new Date('2023-01-01')).toEqual(new Date('2023-01-01'));
51

52
// Works with nested objects
53
expect({
54
  user: {name: 'John', preferences: {theme: 'dark'}}
55
}).toEqual({
56
  user: {name: 'John', preferences: {theme: 'dark'}}
57
});
58
```
59

60
#### toMatchObject
61

62
Checks if the received object contains the expected properties (subset matching).
63

64
```javascript { .api }
65
/**
66
 * Matches if received object contains expected properties
67
 * @param expected - Object with properties that should be present
68
 */
69
ExpectationObject.toMatchObject(expected: Object): void;
70
```
71

72
**Usage Examples:**
73

74
```javascript
75
const user = {
76
  id: 1,
77
  name: 'John',
78
  email: 'john@example.com',
79
  preferences: {theme: 'dark'}
80
};
81

82
expect(user).toMatchObject({name: 'John'});  // passes
83
expect(user).toMatchObject({name: 'John', id: 1});  // passes
84
expect(user).toMatchObject({preferences: {theme: 'dark'}});  // passes
85

86
// Received object can have additional properties
87
expect(user).toMatchObject({name: 'John'});  // passes even though user has more properties
88
```
89

90
### Truthiness Matchers
91

92
#### toBeTruthy
93

94
Checks if a value is truthy (not false, 0, "", null, undefined, or NaN).
95

96
```javascript { .api }
97
/**
98
 * Checks if value is truthy in JavaScript context
99
 */
100
ExpectationObject.toBeTruthy(): void;
101
```
102

103
**Usage Examples:**
104

105
```javascript
106
expect(true).toBeTruthy();
107
expect(1).toBeTruthy();
108
expect('hello').toBeTruthy();
109
expect([]).toBeTruthy();  // empty array is truthy
110
expect({}).toBeTruthy();  // empty object is truthy
111
```
112

113
#### toBeFalsy
114

115
Checks if a value is falsy (false, 0, "", null, undefined, or NaN).
116

117
```javascript { .api }
118
/**
119
 * Checks if value is falsy in JavaScript context
120
 */
121
ExpectationObject.toBeFalsy(): void;
122
```
123

124
**Usage Examples:**
125

126
```javascript
127
expect(false).toBeFalsy();
128
expect(0).toBeFalsy();
129
expect('').toBeFalsy();
130
expect(null).toBeFalsy();
131
expect(undefined).toBeFalsy();
132
expect(NaN).toBeFalsy();
133
```
134

135
#### toBeDefined
136

137
Checks that a value is not `undefined`.
138

139
```javascript { .api }
140
/**
141
 * Checks that value is not undefined
142
 */
143
ExpectationObject.toBeDefined(): void;
144
```
145

146
**Usage Examples:**
147

148
```javascript
149
expect('hello').toBeDefined();
150
expect(0).toBeDefined();
151
expect(null).toBeDefined();  // null is defined, just not undefined
152
expect(false).toBeDefined();
153

154
let x;
155
expect(x).not.toBeDefined();  // x is undefined
156
```
157

158
#### toBeUndefined
159

160
Checks that a value is `undefined`.
161

162
```javascript { .api }
163
/**
164
 * Checks that value is undefined
165
 */
166
ExpectationObject.toBeUndefined(): void;
167
```
168

169
**Usage Examples:**
170

171
```javascript
172
let x;
173
expect(x).toBeUndefined();
174

175
const obj = {name: 'John'};
176
expect(obj.age).toBeUndefined();
177

178
expect(undefined).toBeUndefined();
179
```
180

181
#### toBeNull
182

183
Checks that a value is `null`.
184

185
```javascript { .api }
186
/**
187
 * Checks that value is null
188
 */
189
ExpectationObject.toBeNull(): void;
190
```
191

192
**Usage Examples:**
193

194
```javascript
195
expect(null).toBeNull();
196

197
function findUser(id) {
198
  return id > 0 ? {id, name: 'User'} : null;
199
}
200

201
expect(findUser(-1)).toBeNull();
202
expect(findUser(1)).not.toBeNull();
203
```
204

205
## Negation Support
206

207
All core matchers support negation using `.not`:
208

209
```javascript
210
expect(1).not.toBe(2);
211
expect({a: 1}).not.toEqual({a: 2});
212
expect('hello').not.toBeFalsy();
213
expect(null).not.toBeDefined();
214
expect('defined').not.toBeUndefined();
215
expect('not null').not.toBeNull();
216
```
217

218
## Promise Support
219

220
All core matchers work with promises using `.resolves` and `.rejects`:
221

222
```javascript
223
// Testing resolved values
224
await expect(Promise.resolve(42)).resolves.toBe(42);
225
await expect(Promise.resolve({name: 'John'})).resolves.toEqual({name: 'John'});
226
await expect(Promise.resolve('hello')).resolves.toBeTruthy();
227

228
// Testing rejected values
229
await expect(Promise.reject(new Error('fail'))).rejects.toBeDefined();
230
```