0
# Test Name Plugin
1

2
The test name plugin provides interactive test name-based filtering with typeahead functionality. Users can type partial test names to filter which individual tests run during Jest watch mode.
3

4
## Capabilities
5

6
### TestNamePlugin Class
7

8
Main plugin class implementing Jest's WatchPlugin interface for test name-based filtering.
9

10
```typescript { .api }
11
/**
12
 * Jest watch plugin for filtering individual tests by test name patterns
13
 */
14
export default class TestNamePlugin implements WatchPlugin {
15
  constructor(options: {
16
    stdin: NodeJS.ReadStream;
17
    stdout: NodeJS.WriteStream;
18
    config?: PluginConfig;
19
  });
20
  
21
  /** Hook into Jest lifecycle events to receive test results */
22
  apply(jestHooks: JestHookSubscriber): void;
23
  
24
  /** Handle keypress events from user input */
25
  onKey(key: string): void;
26
  
27
  /** Execute plugin functionality and update Jest configuration */
28
  run(
29
    globalConfig: Config.GlobalConfig,
30
    updateConfigAndRun: UpdateConfigCallback
31
  ): Promise<void>;
32
  
33
  /** Return plugin usage information for Jest's help display */
34
  getUsageInfo(): UsageData;
35
}
36
```
37

38
**Usage Example:**
39

40
```typescript
41
import TestNamePlugin from "jest-watch-typeahead/testname";
42

43
// Plugin is typically instantiated by Jest
44
const plugin = new TestNamePlugin({
45
  stdin: process.stdin,
46
  stdout: process.stdout,
47
  config: {
48
    key: 'n',
49
    prompt: 'filter by test name'
50
  }
51
});
52
```
53

54
### TestNamePatternPrompt Class
55

56
Interactive prompt class for test name pattern input and typeahead display.
57

58
```typescript { .api }
59
/**
60
 * Pattern prompt for test name-based filtering with typeahead functionality
61
 */
62
export default class TestNamePatternPrompt extends PatternPrompt {
63
  constructor(pipe: NodeJS.WritableStream, prompt: Prompt);
64
  
65
  /** Update cached test results from previous test runs */
66
  updateCachedTestResults(results: Array<TestResult>): void;
67
  
68
  /** Handle pattern changes and update display */
69
  protected _onChange(pattern: string, options: ScrollOptions): void;
70
  
71
  /** Display typeahead results for current pattern */
72
  protected _printTypeahead(pattern: string, options: ScrollOptions): void;
73
  
74
  /** Get test names matching the current pattern */
75
  protected _getMatchedTests(pattern: string): Array<any>;
76
}
77
```
78

79
### Pattern Matching System
80

81
The test name plugin uses regex-based pattern matching to filter individual tests:
82

83
- **Case-insensitive matching**: Patterns match test names regardless of case
84
- **Partial matching**: Type partial test names to see matching tests
85
- **Real-time filtering**: Results update as you type
86
- **Highlighting**: Matching portions of test names are highlighted in terminal output
87
- **Multi-line support**: Test names with newlines are displayed with ⏎ symbols
88

89
**Pattern Examples:**
90

91
```bash
92
# Match tests containing "should"
93
should
94

95
# Match specific test descriptions
96
user.*authentication
97

98
# Match multiple test patterns
99
(login|signup).*success
100

101
# Match tests with specific keywords
102
error.*handling
103
```
104

105
## Integration with Jest
106

107
### Plugin Registration
108

109
```javascript
110
// jest.config.js
111
module.exports = {
112
  watchPlugins: [
113
    'jest-watch-typeahead/testname'
114
  ]
115
};
116
```
117

118
### Runtime Behavior
119

120
1. **Activation**: Press the configured key (default: 't') in Jest watch mode
121
2. **Pattern Input**: Type partial test name patterns to filter tests
122
3. **Visual Feedback**: See matching test names highlighted in real-time
123
4. **Selection**: Press Enter to apply filter and run matching tests
124
5. **Exit**: Press Escape to cancel and return to main watch menu
125

126
### Hook Integration
127

128
The plugin integrates with Jest's hook system:
129

130
```typescript { .api }
131
interface JestHookSubscriber {
132
  /** Called when test runs complete */
133
  onTestRunComplete(callback: (data: { testResults: Array<TestResult> }) => void): void;
134
}
135
```
136

137
The test name plugin subscribes to `onTestRunComplete` to cache test results and extract available test names for filtering.
138

139
## Test Name Processing
140

141
### Formatting and Display
142

143
```typescript { .api }
144
/**
145
 * Format test names with pattern highlighting for terminal display
146
 * @param testName - Original test name string
147
 * @param pattern - Search pattern to highlight
148
 * @param width - Terminal display width
149
 * @returns Formatted test name with highlighting and truncation
150
 */
151
function formatTestNameByPattern(
152
  testName: string,
153
  pattern: string,
154
  width: number
155
): string;
156
```
157

158
**Test Name Processing:**
159

160
- **Newline Replacement**: Multi-line test names are converted to single lines with ⏎ symbols
161
- **Pattern Highlighting**: Matching text is highlighted with ANSI colors
162
- **Truncation**: Long test names are truncated with "..." when they exceed terminal width
163
- **Smart Truncation**: Ensures highlighted portions remain visible when possible
164

165
### Test Result Integration
166

167
```typescript { .api }
168
interface TestResult {
169
  /** Test file path */
170
  testFilePath: string;
171
  /** Individual test results */
172
  testResults: Array<{
173
    title: string;
174
    fullName: string;
175
    status: 'passed' | 'failed' | 'pending' | 'skipped';
176
    duration?: number;
177
  }>;
178
}
179
```
180

181
The plugin extracts test names from `TestResult` objects to build a searchable index of available tests.
182

183
## Utility Functions
184

185
### String Processing
186

187
```typescript { .api }
188
/**
189
 * Remove leading trimming dots from display strings
190
 * @param value - Input string that may contain trimming dots
191
 * @returns String with leading trimming dots removed
192
 */
193
function removeTrimmingDots(value: string): string;
194
```
195

196
### Display Helpers
197

198
```typescript { .api }
199
/**
200
 * Print pattern match summary to terminal
201
 * @param count - Number of matches found
202
 * @param entity - Entity type being searched ("tests")
203
 * @param pipe - Output stream for writing
204
 * @param extraText - Additional text to append
205
 */
206
function printPatternMatches(
207
  count: number,
208
  entity: string,
209
  pipe: NodeJS.WritableStream,
210
  extraText?: string
211
): void;
212

213
/**
214
 * Print start typing instruction message
215
 * @param entity - Entity type being searched ("tests")
216
 * @param pipe - Output stream for writing
217
 */
218
function printStartTyping(
219
  entity: string,
220
  pipe: NodeJS.WritableStream
221
): void;
222

223
/**
224
 * Print indicator for additional hidden matches
225
 * @param entity - Entity type being searched ("tests")
226
 * @param pipe - Output stream for writing
227
 * @param more - Number of additional matches
228
 */
229
function printMore(
230
  entity: string,
231
  pipe: NodeJS.WritableStream,
232
  more: number
233
): void;
234

235
/**
236
 * Print individual typeahead item to terminal
237
 * @param item - Item text to display
238
 * @param pipe - Output stream for writing
239
 */
240
function printTypeaheadItem(
241
  item: string,
242
  pipe: NodeJS.WritableStream
243
): void;
244

245
/**
246
 * Format typeahead selection items with highlighting for active selection
247
 * @param item - Item text to format
248
 * @param index - Current item index
249
 * @param activeIndex - Index of currently active selection
250
 * @param prompt - Jest prompt instance for selection tracking
251
 * @returns Formatted item string with selection highlighting
252
 */
253
function formatTypeaheadSelection(
254
  item: string,
255
  index: number,
256
  activeIndex: number,
257
  prompt: Prompt
258
): string;
259
```
260

261
## Scrolling and Navigation
262

263
```typescript { .api }
264
/**
265
 * Calculate scroll positioning for long lists of test names
266
 * @param size - Total number of items
267
 * @param options - Scroll configuration with offset and max display items
268
 * @returns Scroll position information with start, end, and current index
269
 */
270
function scroll(
271
  size: number,
272
  options: ScrollOptions
273
): {
274
  index: number;
275
  end: number;
276
  start: number;
277
};
278
```
279

280
The test name plugin supports keyboard navigation through long lists of matching tests:
281

282
- **Arrow Keys**: Navigate up/down through matches
283
- **Page Up/Down**: Scroll through multiple pages of results
284
- **Home/End**: Jump to first/last match
285

286
## Types
287

288
```typescript { .api }
289
interface UpdateConfigCallback {
290
  (config: {
291
    mode: 'watch';
292
    testNamePattern: string;
293
  }): void;
294
}
295

296
interface ScrollOptions {
297
  /** Current scroll offset */
298
  offset: number;
299
  /** Maximum displayable items */
300
  max: number;
301
}
302
```