0
# @jest/expect-utils
1

2
@jest/expect-utils provides essential utility functions for Jest's expect assertion library, including deep equality comparisons, object property traversal, and type checking utilities. It serves as the foundational layer for Jest's matcher system and custom assertions.
3

4
## Package Information
5

6
- **Package Name**: @jest/expect-utils
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @jest/expect-utils`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  equals, 
16
  isA, 
17
  isError,
18
  getPath, 
19
  getObjectKeys,
20
  pathAsArray,
21
  getObjectSubset, 
22
  subsetEquality,
23
  iterableEquality,
24
  typeEquality,
25
  arrayBufferEquality,
26
  sparseArrayEquality,
27
  partition,
28
  emptyObject,
29
  isOneline
30
} from "@jest/expect-utils";
31
```
32

33
For CommonJS:
34

35
```javascript
36
const { 
37
  equals, 
38
  isA, 
39
  isError,
40
  getPath, 
41
  getObjectKeys,
42
  pathAsArray,
43
  getObjectSubset, 
44
  subsetEquality,
45
  iterableEquality,
46
  typeEquality,
47
  arrayBufferEquality,
48
  sparseArrayEquality,
49
  partition,
50
  emptyObject,
51
  isOneline
52
} = require("@jest/expect-utils");
53
```
54

55
## Basic Usage
56

57
```typescript
58
import { equals, getPath, iterableEquality, subsetEquality } from "@jest/expect-utils";
59

60
// Deep equality comparison
61
const result = equals({ a: 1, b: [2, 3] }, { a: 1, b: [2, 3] });
62
// Result: true
63

64
// Safe property path traversal
65
const pathResult = getPath({ user: { name: "Alice" } }, "user.name");
66
// Result: { hasEndProp: true, value: "Alice", traversedPath: ["user", "name"] }
67

68
// Object subset comparison for partial matching
69
const isSubset = subsetEquality(
70
  { name: "Alice", age: 30, city: "NYC" },
71
  { name: "Alice", age: 30 }
72
);
73
// Result: true
74
```
75

76
## Capabilities
77

78
### Deep Equality Comparison
79

80
Core deep equality function with support for circular references, custom testers, and complex data structures.
81

82
```typescript { .api }
83
/**
84
 * Deep equality comparison function with support for custom testers
85
 * @param a - First value to compare
86
 * @param b - Second value to compare
87
 * @param customTesters - Optional array of custom tester functions
88
 * @param strictCheck - Optional strict comparison mode
89
 * @returns boolean indicating equality
90
 */
91
function equals(
92
  a: unknown,
93
  b: unknown,
94
  customTesters?: Array<Tester>,
95
  strictCheck?: boolean
96
): boolean;
97

98
type EqualsFunction = (
99
  a: unknown,
100
  b: unknown,
101
  customTesters?: Array<Tester>,
102
  strictCheck?: boolean,
103
) => boolean;
104
```
105

106
### Type Checking
107

108
Type guard functions for runtime type validation.
109

110
```typescript { .api }
111
/**
112
 * Type guard that checks if value matches given type name
113
 * @param typeName - String representation of type (e.g., "Array", "Object")
114
 * @param value - Value to check
115
 * @returns Type predicate indicating if value is of specified type
116
 */
117
function isA<T>(typeName: string, value: unknown): value is T;
118

119
/**
120
 * Type guard for Error objects including subclasses
121
 * @param value - Value to check
122
 * @returns Type predicate indicating if value is an Error
123
 */
124
function isError(value: unknown): value is Error;
125
```
126

127
### Object Property Traversal
128

129
Safe property path navigation with detailed result information.
130

131
```typescript { .api }
132
/**
133
 * Safely traverses object property paths with detailed results
134
 * @param object - Object to traverse
135
 * @param propertyPath - Property path as string or array
136
 * @returns GetPath object with traversal information
137
 */
138
function getPath(
139
  object: Record<string, any>,
140
  propertyPath: string | Array<string>
141
): GetPath;
142

143
interface GetPath {
144
  hasEndProp?: boolean;
145
  endPropIsDefined?: boolean;
146
  lastTraversedObject: unknown | null;
147
  traversedPath: Array<string>;
148
  value?: unknown;
149
}
150

151
/**
152
 * Retrieves object's enumerable string and symbol keys
153
 * @param object - Object to get keys from
154
 * @returns Array of string and symbol keys
155
 */
156
function getObjectKeys(object: object): Array<string | symbol>;
157

158
/**
159
 * Converts dot-notation property path to array of property names
160
 * @param propertyPath - Property path string (e.g., "user.name")
161
 * @returns Array of property names
162
 */
163
function pathAsArray(propertyPath: string): Array<any>;
164
```
165

166
### Object Subset Operations
167

168
Functions for extracting and comparing object subsets.
169

170
```typescript { .api }
171
/**
172
 * Strips properties from object that are not present in the subset
173
 * @param object - Source object
174
 * @param subset - Subset pattern object
175
 * @param customTesters - Optional custom tester functions
176
 * @param seenReferences - Internal circular reference tracking
177
 * @returns Object containing only properties present in subset
178
 */
179
function getObjectSubset(
180
  object: any,
181
  subset: any,
182
  customTesters?: Array<Tester>,
183
  seenReferences?: WeakMap<object, boolean>
184
): any;
185

186
/**
187
 * Checks if object contains all properties from subset with matching values
188
 * @param object - Object to check
189
 * @param subset - Subset pattern to match
190
 * @param customTesters - Optional custom tester functions
191
 * @returns boolean or undefined if not applicable
192
 */
193
function subsetEquality(
194
  object: unknown,
195
  subset: unknown,
196
  customTesters?: Array<Tester>
197
): boolean | undefined;
198
```
199

200
### Equality Testers
201

202
Specialized equality comparison functions for different data types.
203

204
```typescript { .api }
205
/**
206
 * Compares iterables (Sets, Maps, iterators) with circular reference detection
207
 * @param a - First iterable
208
 * @param b - Second iterable
209
 * @param customTesters - Optional custom tester functions
210
 * @param aStack - Internal circular reference stack for a
211
 * @param bStack - Internal circular reference stack for b
212
 * @returns boolean or undefined if not applicable
213
 */
214
function iterableEquality(
215
  a: any,
216
  b: any,
217
  customTesters?: Array<Tester>,
218
  aStack?: Array<any>,
219
  bStack?: Array<any>
220
): boolean | undefined;
221

222
/**
223
 * Compares constructor types with special handling for arrays and null
224
 * @param a - First value
225
 * @param b - Second value
226
 * @returns boolean or undefined if not applicable
227
 */
228
function typeEquality(a: any, b: any): boolean | undefined;
229

230
/**
231
 * Compares ArrayBuffers and typed arrays byte-by-byte
232
 * @param a - First buffer
233
 * @param b - Second buffer
234
 * @returns boolean or undefined if not applicable
235
 */
236
function arrayBufferEquality(
237
  a: unknown,
238
  b: unknown
239
): boolean | undefined;
240

241
/**
242
 * Compares sparse arrays by checking both values and key patterns
243
 * @param a - First array
244
 * @param b - Second array
245
 * @param customTesters - Optional custom tester functions
246
 * @returns boolean or undefined if not applicable
247
 */
248
function sparseArrayEquality(
249
  a: unknown,
250
  b: unknown,
251
  customTesters?: Array<Tester>
252
): boolean | undefined;
253
```
254

255

256
### Utility Functions
257

258
General-purpose utility functions for common operations.
259

260
```typescript { .api }
261
/**
262
 * Splits array into two arrays based on predicate function
263
 * @param items - Array to partition
264
 * @param predicate - Function to determine which partition items belong to
265
 * @returns Tuple of [truthy items, falsy items]
266
 */
267
function partition<T>(
268
  items: Array<T>,
269
  predicate: (arg: T) => boolean
270
): [Array<T>, Array<T>];
271

272
/**
273
 * Checks if object is empty (has no own properties)
274
 * @param obj - Object to check
275
 * @returns boolean indicating if object is empty
276
 */
277
function emptyObject(obj: unknown): boolean;
278

279
/**
280
 * Checks if both values are strings without multiline content
281
 * @param expected - First string value
282
 * @param received - Second string value
283
 * @returns boolean indicating if both are single-line strings
284
 */
285
function isOneline(expected: unknown, received: unknown): boolean;
286
```
287

288

289
## Types
290

291
```typescript { .api }
292
/**
293
 * Function type for custom equality testers used in equals() function
294
 */
295
type Tester = (
296
  this: TesterContext,
297
  a: any,
298
  b: any,
299
  customTesters: Array<Tester>,
300
) => boolean | undefined;
301

302
/**
303
 * Context object passed to custom testers
304
 */
305
interface TesterContext {
306
  equals: EqualsFunction;
307
}
308

309
/**
310
 * Type for the main equals function
311
 */
312
type EqualsFunction = (
313
  a: unknown,
314
  b: unknown,
315
  customTesters?: Array<Tester>,
316
  strictCheck?: boolean,
317
) => boolean;
318
```