0
# Jest Matchers
1
2
Jest Matchers is a comprehensive matcher library for the Jest testing framework providing assertion utilities for test expectations. It offers a complete set of assertion methods including equality matchers, comparison operators, collection matchers, spy/mock verifications, and asynchronous testing support with detailed error messages and visual diffs.
3
4
## Package Information
5
6
- **Package Name**: jest-matchers
7
- **Package Type**: npm
8
- **Language**: JavaScript (with Flow types)
9
- **Installation**: `npm install jest-matchers`
10
11
## Core Imports
12
13
```javascript
14
const expect = require('jest-matchers');
15
```
16
17
ES modules:
18
19
```javascript
20
import expect from 'jest-matchers';
21
```
22
23
## Basic Usage
24
25
```javascript
26
const expect = require('jest-matchers');
27
28
// Basic equality assertions
29
expect(2 + 2).toBe(4);
30
expect({name: 'John'}).toEqual({name: 'John'});
31
32
// Truthiness checks
33
expect(true).toBeTruthy();
34
expect(null).toBeFalsy();
35
36
// Collection assertions
37
expect(['apple', 'banana']).toContain('apple');
38
expect([1, 2, 3]).toHaveLength(3);
39
40
// Numeric comparisons
41
expect(10).toBeGreaterThan(5);
42
expect(3.14).toBeCloseTo(3.1, 1);
43
44
// String matching
45
expect('Hello World').toMatch(/World/);
46
47
// Spy/mock verification
48
const mockFn = jest.fn();
49
mockFn('arg1', 'arg2');
50
expect(mockFn).toHaveBeenCalledWith('arg1', 'arg2');
51
52
// Exception testing
53
expect(() => {
54
throw new Error('Something went wrong');
55
}).toThrow('Something went wrong');
56
```
57
58
## Architecture
59
60
Jest Matchers is built around several core components:
61
62
- **Expect Function**: Main entry point that creates expectation objects with all available matchers
63
- **Matcher System**: Extensible matcher framework supporting custom matchers via `expect.extend()`
64
- **Negation Support**: All matchers support `.not` for inverted assertions
65
- **Promise Support**: All matchers support `.resolves` and `.rejects` for asynchronous testing
66
- **Global State Management**: Centralized state for assertion counting and configuration
67
- **Error Handling**: Rich error messages with visual diffs using jest-diff, jest-matcher-utils
68
69
## Capabilities
70
71
### Core Matchers
72
73
Essential assertion methods for equality, truthiness, and basic comparisons. These form the foundation of most test assertions.
74
75
```javascript { .api }
76
// Main expect function
77
function expect(actual: any): ExpectationObject;
78
79
// Core equality matchers
80
ExpectationObject.toBe(expected: any): void;
81
ExpectationObject.toEqual(expected: any): void;
82
ExpectationObject.toMatchObject(expected: Object): void;
83
84
// Truthiness matchers
85
ExpectationObject.toBeTruthy(): void;
86
ExpectationObject.toBeFalsy(): void;
87
ExpectationObject.toBeDefined(): void;
88
ExpectationObject.toBeUndefined(): void;
89
ExpectationObject.toBeNull(): void;
90
```
91
92
[Core Matchers](./core-matchers.md)
93
94
### Numeric and Comparison Matchers
95
96
Specialized matchers for numeric comparisons and floating-point precision testing.
97
98
```javascript { .api }
99
ExpectationObject.toBeGreaterThan(expected: number): void;
100
ExpectationObject.toBeGreaterThanOrEqual(expected: number): void;
101
ExpectationObject.toBeLessThan(expected: number): void;
102
ExpectationObject.toBeLessThanOrEqual(expected: number): void;
103
ExpectationObject.toBeCloseTo(expected: number, precision?: number): void;
104
ExpectationObject.toBeNaN(): void;
105
```
106
107
[Numeric Matchers](./numeric-matchers.md)
108
109
### Collection and String Matchers
110
111
Matchers for arrays, objects, strings, and other iterable collections.
112
113
```javascript { .api }
114
ExpectationObject.toContain(item: any): void;
115
ExpectationObject.toContainEqual(item: any): void;
116
ExpectationObject.toHaveLength(length: number): void;
117
ExpectationObject.toHaveProperty(path: string, value?: any): void;
118
ExpectationObject.toMatch(pattern: string | RegExp): void;
119
ExpectationObject.toBeInstanceOf(constructor: Function): void;
120
```
121
122
[Collection and String Matchers](./collection-string-matchers.md)
123
124
### Spy and Mock Matchers
125
126
Verification matchers for Jest mock functions and spies, essential for testing function calls and interactions.
127
128
```javascript { .api }
129
ExpectationObject.toBeCalled(): void;
130
ExpectationObject.toHaveBeenCalled(): void;
131
ExpectationObject.toBeCalledWith(...args: any[]): void;
132
ExpectationObject.toHaveBeenCalledWith(...args: any[]): void;
133
ExpectationObject.toHaveBeenCalledTimes(number: number): void;
134
ExpectationObject.lastCalledWith(...args: any[]): void;
135
ExpectationObject.toHaveBeenLastCalledWith(...args: any[]): void;
136
```
137
138
[Spy and Mock Matchers](./spy-mock-matchers.md)
139
140
### Exception Matchers
141
142
Matchers for testing error conditions and exception handling.
143
144
```javascript { .api }
145
ExpectationObject.toThrow(expected?: string | Error | RegExp): void;
146
ExpectationObject.toThrowError(expected?: string | Error | RegExp): void;
147
```
148
149
[Exception Matchers](./exception-matchers.md)
150
151
### Asymmetric Matchers
152
153
Special matchers for flexible pattern matching and partial object comparison.
154
155
```javascript { .api }
156
expect.anything(): Anything;
157
expect.any(constructor: Function): Any;
158
expect.objectContaining(object: Object): ObjectContaining;
159
expect.arrayContaining(array: Array): ArrayContaining;
160
expect.stringContaining(string: string): StringContaining;
161
expect.stringMatching(pattern: string | RegExp): StringMatching;
162
```
163
164
[Asymmetric Matchers](./asymmetric-matchers.md)
165
166
### Configuration and Extension
167
168
Methods for extending Jest Matchers with custom matchers and configuring test behavior.
169
170
```javascript { .api }
171
expect.extend(matchers: MatchersObject): void;
172
expect.assertions(expected: number): void;
173
expect.hasAssertions(): void;
174
expect.setState(state: Object): void;
175
expect.getState(): Object;
176
expect.addSnapshotSerializer(): void;
177
```
178
179
[Configuration and Extension](./configuration-extension.md)
180
181
## Types
182
183
```javascript { .api }
184
interface ExpectationObject {
185
// All matchers are available on the expectation object
186
// Plus special properties for negation and promise handling
187
not: ExpectationObject;
188
resolves: ExpectationObject;
189
rejects: ExpectationObject;
190
}
191
192
interface MatchersObject {
193
[matcherName: string]: RawMatcherFn;
194
}
195
196
interface ExpectationResult {
197
pass: boolean;
198
message?: string | (() => string);
199
}
200
201
class JestAssertionError extends Error {
202
matcherResult: any;
203
}
204
```