0
# Jest Watch Typeahead
1

2
Jest Watch Typeahead provides two Jest watch plugins that enable interactive typeahead filtering during test execution. The filename plugin allows filtering test files by typing partial filenames, while the testname plugin allows filtering individual tests by typing partial test names, both providing real-time fuzzy-search-like capabilities.
3

4
## Package Information
5

6
- **Package Name**: jest-watch-typeahead
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev jest-watch-typeahead`
10

11
## Core Imports
12

13
The package exports two distinct plugins accessed via subpath exports. The main entry point intentionally throws an error directing users to the correct import paths:
14

15
```typescript
16
// Import filename plugin (for Jest configuration)
17
import FilenamePlugin from "jest-watch-typeahead/filename";
18

19
// Import testname plugin (for Jest configuration)  
20
import TestnamePlugin from "jest-watch-typeahead/testname";
21
```
22

23
CommonJS:
24

25
```javascript
26
const FilenamePlugin = require("jest-watch-typeahead/filename");
27
const TestnamePlugin = require("jest-watch-typeahead/testname");
28
```
29

30
**Package Exports Structure:**
31
- `"."` → `"./build/index.js"` (throws configuration error)
32
- `"./filename"` → `"./build/file_name_plugin/plugin.js"`
33
- `"./testname"` → `"./build/test_name_plugin/plugin.js"`
34
- `"./package.json"` → `"./package.json"`
35

36
## Basic Usage
37

38
Configure Jest to use the plugins in your `package.json`:
39

40
```json
41
{
42
  "jest": {
43
    "watchPlugins": [
44
      "jest-watch-typeahead/filename",
45
      "jest-watch-typeahead/testname"
46
    ]
47
  }
48
}
49
```
50

51
Or in `jest.config.js`:
52

53
```javascript
54
module.exports = {
55
  watchPlugins: [
56
    'jest-watch-typeahead/filename',
57
    'jest-watch-typeahead/testname',
58
  ],
59
};
60
```
61

62
Run Jest in watch mode to use the plugins:
63

64
```bash
65
npx jest --watch
66
```
67

68
### Advanced Configuration Examples
69

70
**Custom keys and prompts for better workflow integration:**
71

72
```javascript
73
module.exports = {
74
  watchPlugins: [
75
    [
76
      'jest-watch-typeahead/filename',
77
      {
78
        key: 'f',
79
        prompt: 'filter by file pattern',
80
      },
81
    ],
82
    [
83
      'jest-watch-typeahead/testname', 
84
      {
85
        key: 'n',
86
        prompt: 'filter by test name pattern',
87
      },
88
    ],
89
  ],
90
  // Additional Jest configuration
91
  testMatch: ['**/__tests__/**/*.test.{js,ts}'],
92
  collectCoverageFrom: ['src/**/*.{js,ts}'],
93
};
94
```
95

96
**Integration with other Jest watch plugins:**
97

98
```javascript
99
module.exports = {
100
  watchPlugins: [
101
    'jest-watch-typeahead/filename',
102
    'jest-watch-typeahead/testname',
103
    'jest-watch-suspend',
104
    'jest-watch-select-projects',
105
  ],
106
};
107
```
108

109
## Architecture
110

111
Jest Watch Typeahead is built around Jest's plugin architecture with the following key components:
112

113
- **Plugin Classes**: `FileNamePlugin` and `TestNamePlugin` implementing Jest's `WatchPlugin` interface
114
- **Pattern Prompts**: `FileNamePatternPrompt` and `TestNamePatternPrompt` extending Jest's `PatternPrompt` for user interaction
115
- **Utility Functions**: Text formatting, highlighting, and terminal display utilities
116
- **Configuration System**: Customizable key bindings and prompt text through `PluginConfig`
117

118
## Capabilities
119

120
### Filename Filtering Plugin
121

122
Interactive filename-based test filtering with typeahead functionality. Users can type partial filenames to filter which test files run.
123

124
```typescript { .api }
125
export default class FileNamePlugin implements WatchPlugin {
126
  constructor(options: {
127
    stdin: NodeJS.ReadStream;
128
    stdout: NodeJS.WriteStream;
129
    config?: PluginConfig;
130
  });
131
  
132
  apply(jestHooks: JestHookSubscriber): void;
133
  onKey(key: string): void;
134
  run(globalConfig: Config.GlobalConfig, updateConfigAndRun: UpdateConfigCallback): Promise<void>;
135
  getUsageInfo(): UsageData;
136
}
137
```
138

139
[Filename Plugin](./filename-plugin.md)
140

141
### Test Name Filtering Plugin
142

143
Interactive test name-based filtering with typeahead functionality. Users can type partial test names to filter which individual tests run.
144

145
```typescript { .api }
146
export default class TestNamePlugin implements WatchPlugin {
147
  constructor(options: {
148
    stdin: NodeJS.ReadStream;
149
    stdout: NodeJS.WriteStream;
150
    config?: PluginConfig;
151
  });
152
  
153
  apply(jestHooks: JestHookSubscriber): void;
154
  onKey(key: string): void;
155
  run(globalConfig: Config.GlobalConfig, updateConfigAndRun: UpdateConfigCallback): Promise<void>;
156
  getUsageInfo(): UsageData;
157
}
158
```
159

160
[Test Name Plugin](./testname-plugin.md)
161

162
## Types
163

164
```typescript { .api }
165
interface PluginConfig {
166
  /** Custom key binding for plugin activation (default: 'p' for filename, 't' for testname) */
167
  key?: string;
168
  /** Custom prompt text displayed to user */
169
  prompt?: string;
170
}
171

172
type SearchSources = Array<{
173
  config: Config.ProjectConfig;
174
  testPaths: Array<string>;
175
}>;
176

177
interface ScrollOptions {
178
  /** Current scroll offset */
179
  offset: number;
180
  /** Maximum displayable items */
181
  max: number;
182
}
183
```
184

185
## Configuration
186

187
### Custom Key Bindings and Prompts
188

189
```javascript
190
module.exports = {
191
  watchPlugins: [
192
    [
193
      'jest-watch-typeahead/filename',
194
      {
195
        key: 'k',
196
        prompt: 'filter by custom filename pattern',
197
      },
198
    ],
199
    [
200
      'jest-watch-typeahead/testname',
201
      {
202
        key: 'n',
203
        prompt: 'filter by custom test name pattern',
204
      },
205
    ],
206
  ],
207
};
208
```
209

210
Default configurations:
211
- **Filename plugin**: key="p", prompt="filter by a filename regex pattern"
212
- **Test name plugin**: key="t", prompt="filter by a test name regex pattern"
213

214
## Main Entry Point
215

216
The main package entry point (`jest-watch-typeahead`) intentionally throws an error to guide users to the correct usage:
217

218
```typescript { .api }
219
// Importing the main entry point throws this error:
220
throw new Error(`
221
jest-watch-typeahead includes two watch plugins: The filename plugin and the testname plugin.
222
Please configure Jest as follows:
223
"watchPlugins": [
224
  "jest-watch-typeahead/filename",
225
  "jest-watch-typeahead/testname"
226
]
227
`);
228
```
229

230
This prevents accidental incorrect usage and ensures users configure the plugins properly via Jest's `watchPlugins` configuration.