0
# Matcher Display
1

2
Functions for creating consistent matcher hints and error messages in test output, providing clear and informative failure messages.
3

4
## Capabilities
5

6
### Matcher Hint
7

8
Generates formatted hint displays for matcher assertions, showing the expected matcher call format.
9

10
```typescript { .api }
11
/**
12
 * Generate hint display for matcher assertions
13
 * @param matcherName - Name of the matcher
14
 * @param received - Text for received value (default: 'received')
15
 * @param expected - Text for expected value (default: 'expected')
16
 * @param options - Display options
17
 * @returns Formatted matcher hint
18
 */
19
function matcherHint(
20
  matcherName: string,
21
  received?: string,
22
  expected?: string,
23
  options?: MatcherHintOptions
24
): string;
25

26
interface MatcherHintOptions {
27
  comment?: string;
28
  expectedColor?: MatcherHintColor;
29
  isDirectExpectCall?: boolean;
30
  isNot?: boolean;
31
  promise?: string;
32
  receivedColor?: MatcherHintColor;
33
  secondArgument?: string;
34
  secondArgumentColor?: MatcherHintColor;
35
}
36

37
type MatcherHintColor = (arg: string) => string;
38
```
39

40
**Usage Examples:**
41

42
```typescript
43
import { matcherHint, EXPECTED_COLOR, RECEIVED_COLOR } from "jest-matcher-utils";
44

45
// Basic matcher hint
46
const hint = matcherHint('toEqual');
47
// Result: 'expect(received).toEqual(expected)'
48

49
// Custom labels
50
const customHint = matcherHint('toContain', 'array', 'value');
51
// Result: 'expect(array).toContain(value)'
52

53
// Negated matcher
54
const notHint = matcherHint('toBe', undefined, undefined, { isNot: true });
55
// Result: 'expect(received).not.toBe(expected)'
56

57
// Promise matcher
58
const promiseHint = matcherHint('resolves.toEqual', undefined, undefined, {
59
  promise: 'resolves'
60
});
61
// Result: 'expect(received).resolves.toEqual(expected)'
62

63
// With comment
64
const commentHint = matcherHint('toEqual', undefined, undefined, {
65
  comment: 'deep equality'
66
});
67
// Result: 'expect(received).toEqual(expected) // deep equality'
68

69
// Direct expect call (no received)
70
const directHint = matcherHint('toHaveBeenCalled', '', '', {
71
  isDirectExpectCall: true
72
});
73
// Result: 'expect.toHaveBeenCalled()'
74

75
// Multiple arguments
76
const multiHint = matcherHint('toBeCloseTo', 'received', 'expected', {
77
  secondArgument: 'precision'
78
});
79
// Result: 'expect(received).toBeCloseTo(expected, precision)'
80
```
81

82
### Matcher Error Message
83

84
Creates formatted error messages for matcher failures with consistent styling.
85

86
```typescript { .api }
87
/**
88
 * Create formatted error message for matcher failures
89
 * @param hint - Assertion returned from call to matcherHint
90
 * @param generic - Condition which correct value must fulfill
91
 * @param specific - Incorrect value returned from call to printWithType
92
 * @returns Formatted error message
93
 */
94
function matcherErrorMessage(
95
  hint: string,
96
  generic: string,
97
  specific?: string
98
): string;
99
```
100

101
**Usage Examples:**
102

103
```typescript
104
import { matcherErrorMessage, matcherHint, printWithType, printReceived } from "jest-matcher-utils";
105

106
// Basic error message
107
const hint = matcherHint('toBeGreaterThan');
108
const error = matcherErrorMessage(
109
  hint,
110
  'expected value must be a number'
111
);
112
// Result: 'expect(received).toBeGreaterThan(expected)\n\nMatcher error: expected value must be a number'
113

114
// With specific details
115
const detailedError = matcherErrorMessage(
116
  hint,
117
  'received value must be a number',
118
  printWithType('Received', 'not a number', printReceived)
119
);
120
// Result includes the specific type information
121

122
// Complete matcher error workflow
123
function customMatcher(received: unknown, expected: number) {
124
  const hint = matcherHint('toBeGreaterThan', 'received', 'expected');
125
  
126
  if (typeof received !== 'number') {
127
    throw new Error(
128
      matcherErrorMessage(
129
        hint,
130
        'received value must be a number',
131
        printWithType('Received', received, printReceived)
132
      )
133
    );
134
  }
135
}
136
```
137

138
### Label Printer
139

140
Creates a function that formats labels with consistent alignment for multi-line output.
141

142
```typescript { .api }
143
/**
144
 * Create a function that formats labels with consistent alignment
145
 * @param strings - Strings to calculate alignment for
146
 * @returns Function that formats labels with padding
147
 */
148
function getLabelPrinter(...strings: Array<string>): PrintLabel;
149

150
type PrintLabel = (string: string) => string;
151
```
152

153
**Usage Examples:**
154

155
```typescript
156
import { getLabelPrinter } from "jest-matcher-utils";
157

158
// Create aligned label printer
159
const printLabel = getLabelPrinter('Expected', 'Received');
160

161
// Use for consistent formatting
162
const expectedLine = printLabel('Expected') + 'value1';
163
const receivedLine = printLabel('Received') + 'value2';
164
console.log(expectedLine);  // 'Expected: value1'
165
console.log(receivedLine);  // 'Received: value2'
166

167
// Handles different label lengths
168
const printer = getLabelPrinter('Short', 'Very Long Label');
169
const short = printer('Short');     // 'Short:          '
170
const long = printer('Very Long Label'); // 'Very Long Label: '
171

172
// Common usage in diff output
173
const diffPrinter = getLabelPrinter('Expected', 'Received');
174
const comparison = [
175
  diffPrinter('Expected') + '{"name": "Alice"}',
176
  diffPrinter('Received') + '{"name": "Bob"}'
177
].join('\n');
178
```
179

180
### Pluralize
181

182
Pluralizes words based on count for grammatically correct test messages.
183

184
```typescript { .api }
185
/**
186
 * Pluralize a word based on count
187
 * @param word - Word to pluralize
188
 * @param count - Count to determine plural form
189
 * @returns Pluralized phrase with count
190
 */
191
function pluralize(word: string, count: number): string;
192
```
193

194
**Usage Examples:**
195

196
```typescript
197
import { pluralize } from "jest-matcher-utils";
198

199
// Basic pluralization
200
const items = pluralize('item', 1);    // 'one item'
201
const manyItems = pluralize('item', 3); // '3 items'
202
const zeroItems = pluralize('item', 0); // 'zero items'
203

204
// Works with numbers 0-13 spelled out
205
const spelled = pluralize('error', 5);  // '5 errors'
206
const written = pluralize('warning', 1); // 'one warning'
207

208
// Common usage in test messages
209
function validateArray(arr: unknown[]) {
210
  if (arr.length === 0) {
211
    throw new Error(`Expected array to have items but received ${pluralize('item', arr.length)}`);
212
  }
213
}
214

215
// In matcher implementations
216
const errorCount = errors.length;
217
const message = `Found ${pluralize('validation error', errorCount)}`;
218
// Results: 'Found one validation error' or 'Found 3 validation errors'
219
```