@provino/dialect-jest 0.0.0-stage → 0.1.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +8 -2
- package/THIRD_PARTY_NOTICES.md +266 -0
- package/dist/affected/index.d.ts +13 -0
- package/dist/affected/index.js +424 -0
- package/dist/failure-message.d.ts +245 -0
- package/dist/failure-message.js +125 -0
- package/dist/global-setup/index.d.ts +11 -0
- package/dist/global-setup/index.js +40 -0
- package/dist/index.d.ts +41 -0
- package/dist/index.js +528 -0
- package/dist/inline-snapshots/index.d.ts +6 -0
- package/dist/inline-snapshots/index.js +263 -0
- package/dist/jest-require.js +42 -0
- package/dist/node/index.d.ts +1716 -0
- package/dist/node/index.js +7307 -0
- package/dist/results/index.d.ts +248 -0
- package/dist/results/index.js +844 -0
- package/dist/runtime/index.d.ts +450 -0
- package/dist/runtime/index.js +3455 -0
- package/package.json +97 -3
|
@@ -0,0 +1,1716 @@
|
|
|
1
|
+
import { t as StackTraceConfig } from "../failure-message.js";
|
|
2
|
+
import { AggregatedResult, AssertionResult, JestResults, ProjectConfigLike, SnapshotSummary, Test, TestCaseStartInfo, TestContext, TestResult } from "@provino/dialect-jest/results";
|
|
3
|
+
import { CliDialect, ConfigReader, ConfigSource, Diagnostic, Dialect, FlagSpec, NeutralProject, Reporter, RunCoverageOptions, RunRequest, SerializedCoverageConfig, TextStyle } from "@provino/types";
|
|
4
|
+
export * from "@provino/dialect-jest/results";
|
|
5
|
+
/**
|
|
6
|
+
* Where Jest's built-in packages resolve from: a function like `require.resolve` from jest-config's
|
|
7
|
+
* directory. The default finds the project's own Jest (`jest-config`, else `jest` → `jest-cli` →
|
|
8
|
+
* `jest-config`, each from the one before, which also works under pnpm) from `rootDir`.
|
|
9
|
+
* @public
|
|
10
|
+
*/
|
|
11
|
+
type JestRequireResolve = (specifier: string) => string | undefined;
|
|
12
|
+
/**
|
|
13
|
+
* Finds the `jest-config` a project would run with, from its root: `jest-config` itself, else
|
|
14
|
+
* through `jest`, `jest-cli` (and `@jest/core`). Returns a `require.resolve` from there.
|
|
15
|
+
* @public
|
|
16
|
+
*/
|
|
17
|
+
export declare function projectJestRequireResolve(rootDir: string): JestRequireResolve;
|
|
18
|
+
/**
|
|
19
|
+
* `findNodeModule`'s options.
|
|
20
|
+
* @public
|
|
21
|
+
*/
|
|
22
|
+
interface FindNodeModuleOptions {
|
|
23
|
+
readonly basedir: string;
|
|
24
|
+
readonly extensions?: readonly string[] | undefined;
|
|
25
|
+
/** The project's custom `resolver` module (absolute), preloaded. */
|
|
26
|
+
readonly resolver?: string | null | undefined;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Module resolution as `jest-config` sees it.
|
|
30
|
+
* @public
|
|
31
|
+
*/
|
|
32
|
+
interface JestResolution {
|
|
33
|
+
/** `Resolver.findNodeModule`: the resolved path, or `null` on a miss. */
|
|
34
|
+
findNodeModule(path: string, options: FindNodeModuleOptions): string | null;
|
|
35
|
+
/**
|
|
36
|
+
* `require.resolve` from jest-config's own install: where Jest's built-in packages come from.
|
|
37
|
+
* `undefined` when no Jest install is known or it can't resolve the name.
|
|
38
|
+
*/
|
|
39
|
+
requireResolve(specifier: string): string | undefined;
|
|
40
|
+
/** `preloadResolver`: loads a custom resolver module before resolution uses it. */
|
|
41
|
+
preloadResolver(path: string): Promise<void>;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Builds the resolution a normalize run uses. `requireResolve` is where Jest's built-in packages
|
|
45
|
+
* come from (see `JestRequireResolve`).
|
|
46
|
+
* @public
|
|
47
|
+
*/
|
|
48
|
+
export declare function createJestResolution(requireResolve: JestRequireResolve, nodePaths?: readonly string[]): JestResolution;
|
|
49
|
+
/**
|
|
50
|
+
* A Jest config as a file gives it (`Config.InitialOptions`), before validation. The loader sets
|
|
51
|
+
* `rootDir`.
|
|
52
|
+
* @public
|
|
53
|
+
*/
|
|
54
|
+
type JestInitialOptions = Readonly<Record<string, unknown>>;
|
|
55
|
+
/** @public */
|
|
56
|
+
interface JestDisplayName {
|
|
57
|
+
readonly name: string;
|
|
58
|
+
readonly color: string;
|
|
59
|
+
}
|
|
60
|
+
/** A transform rule after normalization: pattern, resolved transformer, options. @public */
|
|
61
|
+
type JestTransformEntry = readonly [pattern: string, path: string, options: Readonly<Record<string, unknown>>];
|
|
62
|
+
/** A `moduleNameMapper` rule after normalization: pattern, target(s). @public */
|
|
63
|
+
type JestMapperEntry = readonly [pattern: string, target: string | readonly string[]];
|
|
64
|
+
/** A reporter after normalization: name or resolved path, options. @public */
|
|
65
|
+
type JestReporterEntry = readonly [name: string, options: Readonly<Record<string, unknown>>];
|
|
66
|
+
/**
|
|
67
|
+
* One project's normalized config: what `readConfig(...).projectConfig` returns.
|
|
68
|
+
* @public
|
|
69
|
+
*/
|
|
70
|
+
interface JestProjectConfig {
|
|
71
|
+
readonly automock: boolean;
|
|
72
|
+
readonly cache: boolean;
|
|
73
|
+
readonly cacheDirectory: string;
|
|
74
|
+
readonly clearMocks: boolean;
|
|
75
|
+
readonly collectCoverage: boolean;
|
|
76
|
+
readonly collectCoverageFrom: readonly string[];
|
|
77
|
+
readonly coverageDirectory: string;
|
|
78
|
+
readonly coveragePathIgnorePatterns: readonly string[];
|
|
79
|
+
readonly coverageProvider: string;
|
|
80
|
+
readonly cwd: string;
|
|
81
|
+
readonly dependencyExtractor: string | undefined;
|
|
82
|
+
readonly detectLeaks: boolean;
|
|
83
|
+
readonly detectOpenHandles: boolean;
|
|
84
|
+
readonly displayName: JestDisplayName | undefined;
|
|
85
|
+
readonly errorOnDeprecated: boolean;
|
|
86
|
+
readonly extensionsToTreatAsEsm: readonly string[];
|
|
87
|
+
readonly fakeTimers: Readonly<Record<string, unknown>>;
|
|
88
|
+
readonly filter: string | undefined;
|
|
89
|
+
readonly forceCoverageMatch: readonly string[];
|
|
90
|
+
readonly globalSetup: string | undefined;
|
|
91
|
+
readonly globalTeardown: string | undefined;
|
|
92
|
+
readonly globals: Readonly<Record<string, unknown>>;
|
|
93
|
+
readonly haste: Readonly<Record<string, unknown>>;
|
|
94
|
+
readonly id: string;
|
|
95
|
+
readonly injectGlobals: boolean;
|
|
96
|
+
readonly moduleDirectories: readonly string[];
|
|
97
|
+
readonly moduleFileExtensions: readonly string[];
|
|
98
|
+
readonly moduleNameMapper: readonly JestMapperEntry[];
|
|
99
|
+
readonly modulePathIgnorePatterns: readonly string[];
|
|
100
|
+
readonly modulePaths: readonly string[] | undefined;
|
|
101
|
+
readonly openHandlesTimeout: number;
|
|
102
|
+
readonly prettierPath: string | null;
|
|
103
|
+
readonly resetMocks: boolean;
|
|
104
|
+
readonly resetModules: boolean;
|
|
105
|
+
readonly resolver: string | undefined;
|
|
106
|
+
readonly restoreMocks: boolean;
|
|
107
|
+
readonly rootDir: string;
|
|
108
|
+
readonly roots: readonly string[];
|
|
109
|
+
readonly runner: string;
|
|
110
|
+
readonly runnerOptions: Readonly<Record<string, unknown>>;
|
|
111
|
+
readonly runtime: string | undefined;
|
|
112
|
+
readonly sandboxInjectedGlobals: readonly string[];
|
|
113
|
+
readonly setupFiles: readonly string[];
|
|
114
|
+
readonly setupFilesAfterEnv: readonly string[];
|
|
115
|
+
readonly silent: boolean | undefined;
|
|
116
|
+
readonly skipFilter: boolean;
|
|
117
|
+
readonly skipNodeResolution: boolean | undefined;
|
|
118
|
+
readonly slowTestThreshold: number;
|
|
119
|
+
readonly snapshotFormat: Readonly<Record<string, unknown>>;
|
|
120
|
+
readonly snapshotResolver: string | undefined;
|
|
121
|
+
readonly snapshotSerializers: readonly string[];
|
|
122
|
+
readonly testEnvironment: string;
|
|
123
|
+
readonly testEnvironmentOptions: Readonly<Record<string, unknown>>;
|
|
124
|
+
readonly testLocationInResults: boolean;
|
|
125
|
+
readonly testMatch: readonly string[];
|
|
126
|
+
readonly testPathIgnorePatterns: readonly string[];
|
|
127
|
+
readonly testRegex: readonly string[];
|
|
128
|
+
readonly testRunner: string;
|
|
129
|
+
readonly testTimeout: number | undefined;
|
|
130
|
+
readonly transform: readonly JestTransformEntry[];
|
|
131
|
+
readonly transformIgnorePatterns: readonly string[];
|
|
132
|
+
readonly unmockedModulePathPatterns: readonly string[] | undefined;
|
|
133
|
+
readonly verbose: boolean | undefined;
|
|
134
|
+
readonly waitForUnhandledRejections: boolean;
|
|
135
|
+
readonly watchPathIgnorePatterns: readonly string[];
|
|
136
|
+
}
|
|
137
|
+
/**
|
|
138
|
+
* The run-wide config: what `readConfig(...).globalConfig` returns. `testPathPatterns` holds the
|
|
139
|
+
* patterns (Jest wraps them in a `TestPathPatterns` object).
|
|
140
|
+
* @public
|
|
141
|
+
*/
|
|
142
|
+
interface JestGlobalConfig {
|
|
143
|
+
readonly bail: number;
|
|
144
|
+
readonly changedFilesWithAncestor: boolean;
|
|
145
|
+
readonly changedSince: string | undefined;
|
|
146
|
+
readonly ci: boolean;
|
|
147
|
+
readonly collectCoverage: boolean;
|
|
148
|
+
readonly collectCoverageFrom: readonly string[];
|
|
149
|
+
readonly collectTests: boolean;
|
|
150
|
+
readonly coverageDirectory: string;
|
|
151
|
+
readonly coverageProvider: string;
|
|
152
|
+
readonly coverageReporters: readonly unknown[];
|
|
153
|
+
readonly coverageThreshold: Readonly<Record<string, unknown>> | undefined;
|
|
154
|
+
readonly detectLeaks: boolean;
|
|
155
|
+
readonly detectOpenHandles: boolean;
|
|
156
|
+
readonly errorOnDeprecated: boolean;
|
|
157
|
+
readonly expand: boolean;
|
|
158
|
+
readonly filter: string | undefined;
|
|
159
|
+
readonly findRelatedTests: boolean;
|
|
160
|
+
readonly forceExit: boolean;
|
|
161
|
+
readonly globalSetup: string | undefined;
|
|
162
|
+
readonly globalTeardown: string | undefined;
|
|
163
|
+
readonly json: boolean;
|
|
164
|
+
readonly lastCommit: boolean;
|
|
165
|
+
readonly listTests: boolean;
|
|
166
|
+
readonly logHeapUsage: boolean;
|
|
167
|
+
readonly maxConcurrency: number;
|
|
168
|
+
readonly maxWorkers: number;
|
|
169
|
+
readonly noSCM: undefined;
|
|
170
|
+
readonly noStackTrace: boolean;
|
|
171
|
+
readonly nonFlagArgs: readonly string[];
|
|
172
|
+
readonly notify: boolean;
|
|
173
|
+
readonly notifyMode: string;
|
|
174
|
+
readonly onlyChanged: boolean;
|
|
175
|
+
readonly onlyFailures: boolean;
|
|
176
|
+
readonly openHandlesTimeout: number;
|
|
177
|
+
readonly outputFile: string | undefined;
|
|
178
|
+
readonly passWithNoTests: boolean;
|
|
179
|
+
readonly projects: readonly (string | Readonly<Record<string, unknown>>)[];
|
|
180
|
+
readonly randomize: boolean | undefined;
|
|
181
|
+
readonly replname: string | undefined;
|
|
182
|
+
readonly reporters: readonly JestReporterEntry[] | undefined;
|
|
183
|
+
readonly rootDir: string;
|
|
184
|
+
readonly runInBand: boolean;
|
|
185
|
+
readonly runTestsByPath: boolean;
|
|
186
|
+
readonly seed: number;
|
|
187
|
+
readonly shard: {
|
|
188
|
+
readonly shardIndex: number;
|
|
189
|
+
readonly shardCount: number;
|
|
190
|
+
} | undefined;
|
|
191
|
+
readonly showSeed: boolean | undefined;
|
|
192
|
+
readonly silent: boolean | undefined;
|
|
193
|
+
readonly skipFilter: boolean;
|
|
194
|
+
readonly snapshotFormat: Readonly<Record<string, unknown>>;
|
|
195
|
+
readonly testFailureExitCode: number;
|
|
196
|
+
readonly testNamePattern: string | undefined;
|
|
197
|
+
readonly testPathPatterns: readonly string[];
|
|
198
|
+
readonly testResultsProcessor: string | undefined;
|
|
199
|
+
readonly testSequencer: string;
|
|
200
|
+
readonly testTimeout: number | undefined;
|
|
201
|
+
readonly updateSnapshot: "all" | "new" | "none";
|
|
202
|
+
readonly useStderr: boolean;
|
|
203
|
+
readonly verbose: boolean | undefined;
|
|
204
|
+
readonly waitForUnhandledRejections: boolean;
|
|
205
|
+
readonly watch: boolean;
|
|
206
|
+
readonly watchAll: boolean;
|
|
207
|
+
readonly watchPlugins: readonly {
|
|
208
|
+
readonly path: string;
|
|
209
|
+
readonly config: unknown;
|
|
210
|
+
}[] | undefined;
|
|
211
|
+
readonly watchman: boolean;
|
|
212
|
+
readonly workerGracefulExitTimeout: number | undefined;
|
|
213
|
+
readonly workerIdleMemoryLimit: number | undefined;
|
|
214
|
+
readonly workerThreads: boolean | undefined;
|
|
215
|
+
}
|
|
216
|
+
/**
|
|
217
|
+
* The CLI values the config reader honours, as Jest's `argv` carries them (`Config.Argv`). B14b's
|
|
218
|
+
* reader passes `{}` unless a caller sets some; the CLI parser (T11.7) fills it.
|
|
219
|
+
* @public
|
|
220
|
+
*/
|
|
221
|
+
type JestArgv = Readonly<Record<string, unknown>> & {
|
|
222
|
+
readonly _?: readonly (string | number)[];
|
|
223
|
+
};
|
|
224
|
+
/**
|
|
225
|
+
* A config as `loadJestConfig` loads it (the reader's `load` step): the file's options with
|
|
226
|
+
* `rootDir` set, and its path (`null` for inline JSON).
|
|
227
|
+
* @public
|
|
228
|
+
*/
|
|
229
|
+
interface JestLoadedConfig {
|
|
230
|
+
readonly options: JestInitialOptions;
|
|
231
|
+
readonly configPath: string | null;
|
|
232
|
+
}
|
|
233
|
+
/**
|
|
234
|
+
* One read config: `readConfig`'s result.
|
|
235
|
+
* @public
|
|
236
|
+
*/
|
|
237
|
+
interface JestReadConfig {
|
|
238
|
+
readonly configPath: string | null;
|
|
239
|
+
readonly globalConfig: JestGlobalConfig;
|
|
240
|
+
readonly projectConfig: JestProjectConfig;
|
|
241
|
+
readonly hasDeprecationWarnings: boolean;
|
|
242
|
+
}
|
|
243
|
+
type Options$1 = Record<string, unknown>;
|
|
244
|
+
/**
|
|
245
|
+
* How the normalizer runs. Everything is optional: the defaults are a CLI run in the current
|
|
246
|
+
* directory with no flags, and Jest's packages found through the project's own Jest.
|
|
247
|
+
* @public
|
|
248
|
+
*/
|
|
249
|
+
interface NormalizeOptions {
|
|
250
|
+
/** Jest's `argv` (CLI values). Default: none. */
|
|
251
|
+
readonly argv?: JestArgv;
|
|
252
|
+
/** The working directory Jest runs in. Default: `process.cwd()`. */
|
|
253
|
+
readonly cwd?: string;
|
|
254
|
+
/**
|
|
255
|
+
* Where Jest's built-in packages (`babel-jest`, `jest-environment-node`, `jest-circus/runner`,
|
|
256
|
+
* `jest-runner`, `@jest/test-sequencer`) resolve from. Default: the project's own Jest
|
|
257
|
+
* (`projectJestRequireResolve(rootDir)`); without one, each stays its bare name.
|
|
258
|
+
*/
|
|
259
|
+
readonly requireResolve?: JestRequireResolve;
|
|
260
|
+
/** The environment variables Jest reads (`CI`, `NODE_PATH`). Default: `process.env`. */
|
|
261
|
+
readonly env?: NodeJS.ProcessEnv;
|
|
262
|
+
/** Whether this is a CI run (Jest's `ci-info`). Default: from `env`. */
|
|
263
|
+
readonly ci?: boolean;
|
|
264
|
+
/** Jest's random seed when `argv.seed` is unset. Default: random. */
|
|
265
|
+
readonly seed?: number;
|
|
266
|
+
/**
|
|
267
|
+
* Reporter names the host builds itself (`provino` gives `['provino', 'html']`, D141): a bare
|
|
268
|
+
* name in this list, in `reporters` or `--reporters`, is kept as given and never resolved as a
|
|
269
|
+
* module, so `jestReporterPlan` makes it a `host` step. A path (`./provino`) is still a module.
|
|
270
|
+
* Default: none.
|
|
271
|
+
*/
|
|
272
|
+
readonly hostReporters?: readonly string[];
|
|
273
|
+
}
|
|
274
|
+
/**
|
|
275
|
+
* One normalized config before the split, with what validation reported.
|
|
276
|
+
* @public
|
|
277
|
+
*/
|
|
278
|
+
interface NormalizedJestOptions {
|
|
279
|
+
readonly options: Readonly<Options$1>;
|
|
280
|
+
/** Whether the config (its preset, or `--cacheDirectory`) named a `cacheDirectory` (D70). */
|
|
281
|
+
readonly cacheDirectorySet: boolean;
|
|
282
|
+
readonly hasDeprecationWarnings: boolean;
|
|
283
|
+
readonly diagnostics: readonly Diagnostic[];
|
|
284
|
+
}
|
|
285
|
+
/**
|
|
286
|
+
* `Defaults.ts`: Jest 30.5's defaults, before normalization.
|
|
287
|
+
* @public
|
|
288
|
+
*/
|
|
289
|
+
export declare function jestDefaults(ci: boolean): Readonly<Options$1>;
|
|
290
|
+
/**
|
|
291
|
+
* Normalizes one config as Jest's `normalize(initialOptions, argv, configPath, projectIndex,
|
|
292
|
+
* isProjectOptions)` does: validation, `rootDir`, the preset, Jest's defaults, `<rootDir>` and
|
|
293
|
+
* every path resolved. Throws `JestConfigError` where Jest throws.
|
|
294
|
+
* @public
|
|
295
|
+
*/
|
|
296
|
+
export declare function normalizeJestConfig(initialOptions: JestInitialOptions, context: {
|
|
297
|
+
readonly configPath: string | null;
|
|
298
|
+
readonly projectIndex?: number;
|
|
299
|
+
readonly isProjectOptions?: boolean;
|
|
300
|
+
}, options?: NormalizeOptions): Promise<NormalizedJestOptions>;
|
|
301
|
+
/**
|
|
302
|
+
* Splits normalized options into the global and project configs (`groupOptions`, `index.ts`
|
|
303
|
+
* L123-L245).
|
|
304
|
+
* @public
|
|
305
|
+
*/
|
|
306
|
+
export declare function groupJestOptions(options: Readonly<Options$1>): {
|
|
307
|
+
readonly globalConfig: JestGlobalConfig;
|
|
308
|
+
readonly projectConfig: JestProjectConfig;
|
|
309
|
+
};
|
|
310
|
+
/**
|
|
311
|
+
* `readConfig`'s options beside `NormalizeOptions` (its positional arguments, by name).
|
|
312
|
+
* @public
|
|
313
|
+
*/
|
|
314
|
+
interface ReadJestConfigOptions extends NormalizeOptions {
|
|
315
|
+
/** Read the config from the path, ignoring `argv.config` (Jest's `skipArgvConfigOption`). */
|
|
316
|
+
readonly skipArgvConfigOption?: boolean;
|
|
317
|
+
/** For an inline project object: its parent config's directory. */
|
|
318
|
+
readonly parentConfigDirname?: string | null;
|
|
319
|
+
readonly projectIndex?: number;
|
|
320
|
+
readonly skipMultipleConfigError?: boolean;
|
|
321
|
+
/** Validate as a project of `projects` (Jest's `isProjectOptions`). */
|
|
322
|
+
readonly isProjectOptions?: boolean;
|
|
323
|
+
}
|
|
324
|
+
/**
|
|
325
|
+
* `readConfig`'s result, with the warnings validation produced.
|
|
326
|
+
* @public
|
|
327
|
+
*/
|
|
328
|
+
interface JestReadOutcome extends JestReadConfig {
|
|
329
|
+
/** Whether the config named a `cacheDirectory` (see `NormalizedJestOptions`). */
|
|
330
|
+
readonly cacheDirectorySet: boolean;
|
|
331
|
+
readonly diagnostics: readonly Diagnostic[];
|
|
332
|
+
}
|
|
333
|
+
/**
|
|
334
|
+
* Normalizes a config `loadJestConfig` read: the second half of `readConfig`.
|
|
335
|
+
* @public
|
|
336
|
+
*/
|
|
337
|
+
export declare function normalizeLoadedJestConfig(loaded: {
|
|
338
|
+
readonly options: JestInitialOptions;
|
|
339
|
+
readonly configPath: string | null;
|
|
340
|
+
}, options?: ReadJestConfigOptions): Promise<JestReadOutcome>;
|
|
341
|
+
/**
|
|
342
|
+
* Reads and normalizes one config as Jest's `readConfig(argv, packageRootOrConfig, …)` does:
|
|
343
|
+
* `packageRootOrConfig` is a path (a config file, or a directory searched as `jest` would), or an
|
|
344
|
+
* inline project object with `parentConfigDirname`.
|
|
345
|
+
* @public
|
|
346
|
+
*/
|
|
347
|
+
export declare function readJestConfig(packageRootOrConfig: string | JestInitialOptions, options?: ReadJestConfigOptions): Promise<JestReadOutcome>;
|
|
348
|
+
/**
|
|
349
|
+
* `readConfigs`' result, with every project's warnings.
|
|
350
|
+
* @public
|
|
351
|
+
*/
|
|
352
|
+
interface JestReadConfigsOutcome {
|
|
353
|
+
readonly globalConfig: JestGlobalConfig;
|
|
354
|
+
readonly configs: readonly JestProjectConfig[];
|
|
355
|
+
/** Per config, whether it named a `cacheDirectory` (see `NormalizedJestOptions`). */
|
|
356
|
+
readonly cacheDirectorySet: readonly boolean[];
|
|
357
|
+
readonly hasDeprecationWarnings: boolean;
|
|
358
|
+
readonly diagnostics: readonly Diagnostic[];
|
|
359
|
+
}
|
|
360
|
+
/**
|
|
361
|
+
* Reads every project of a run as Jest's `readConfigs(argv, projectPaths)` does: the first path's
|
|
362
|
+
* config, then each entry of its `projects` (globs expanded, paths to directories or config
|
|
363
|
+
* files, inline objects), validated as projects unless one is the root config itself. Running
|
|
364
|
+
* several is `runProjects`'s (D29); this reads them. `root` is the first path's config when the caller has
|
|
365
|
+
* loaded it already (the config reader's `resolve` step), so it isn't loaded again. Each config
|
|
366
|
+
* file is loaded once, and normalized as often as Jest reads it (see `LoadedFiles`).
|
|
367
|
+
* @public
|
|
368
|
+
*/
|
|
369
|
+
export declare function readJestConfigs(projectPaths: readonly string[], options?: NormalizeOptions, root?: JestLoadedConfig): Promise<JestReadConfigsOutcome>;
|
|
370
|
+
/**
|
|
371
|
+
* `runJest.ts` L113-L119 (`getTestPaths`): what Jest logs for a project with no test under `-o`
|
|
372
|
+
* when no root is in a git, hg or sl repository.
|
|
373
|
+
* @public
|
|
374
|
+
*/
|
|
375
|
+
export declare const JEST_NO_SCM_TEXT: string;
|
|
376
|
+
/**
|
|
377
|
+
* `getNoTestsFoundMessage.ts` L16-L34, for the flags this file is about: under `--onlyFailures`
|
|
378
|
+
* `getNoTestFoundFailed.ts`, under `-o` (and the flags that set it) `getNoTestFoundRelatedToChangedFiles.ts`,
|
|
379
|
+
* each with its hint line only on an interactive terminal (jest-util `isInteractive`). `exitWith0`
|
|
380
|
+
* is `passWithNoTests || lastCommit || onlyChanged`. `undefined` when neither flag is on: the
|
|
381
|
+
* other texts are not this file's.
|
|
382
|
+
* @public
|
|
383
|
+
*/
|
|
384
|
+
export declare function jestChangedNoTestsMessage(globalConfig: Pick<JestGlobalConfig, "passWithNoTests" | "lastCommit" | "onlyChanged" | "onlyFailures" | "changedSince" | "watch">, options: {
|
|
385
|
+
readonly interactive: boolean;
|
|
386
|
+
readonly style: TextStyle;
|
|
387
|
+
}): {
|
|
388
|
+
readonly exitWith0: boolean;
|
|
389
|
+
readonly message: string;
|
|
390
|
+
} | undefined;
|
|
391
|
+
/**
|
|
392
|
+
* `getChangedFilesPromise.ts` L28-L37: a changed-files lookup that failed, as Jest prints it before
|
|
393
|
+
* it exits 1: `formatExecError` without the stack, the lines that hold `Command failed:` left out,
|
|
394
|
+
* after two blank lines, in red. The caller writes it to stderr (`console.error`).
|
|
395
|
+
* @public
|
|
396
|
+
*/
|
|
397
|
+
export declare function jestChangedFilesErrorText(error: unknown, projectConfig: {
|
|
398
|
+
readonly rootDir: string;
|
|
399
|
+
readonly testMatch: readonly string[];
|
|
400
|
+
}, style: Pick<TextStyle, "red">): string;
|
|
401
|
+
/**
|
|
402
|
+
* What Provino does with a flag.
|
|
403
|
+
*
|
|
404
|
+
* - `request`: it becomes a field of the `RunRequest`.
|
|
405
|
+
* - `config`: a Jest config option given on the command line; it reaches the config reader through
|
|
406
|
+
* the parsed argv (`setFromArgv`), so the parser adds nothing.
|
|
407
|
+
* - `accepted`: harmless here; nothing to say.
|
|
408
|
+
* - `warn`: accepted, but has no effect yet (`owner` is the task that will apply it); a warning.
|
|
409
|
+
* - `refuse`: no backend yet (`owner` is the task that builds it); an error diagnostic when given.
|
|
410
|
+
* @public
|
|
411
|
+
*/
|
|
412
|
+
type JestCliSupport = "request" | "config" | "accepted" | "warn" | "refuse";
|
|
413
|
+
/**
|
|
414
|
+
* One option of Jest's command line.
|
|
415
|
+
* @public
|
|
416
|
+
*/
|
|
417
|
+
interface JestCliOption {
|
|
418
|
+
/** yargs' type for the option; absent for the two choice-only options. */
|
|
419
|
+
readonly type?: "boolean" | "string" | "number" | "array";
|
|
420
|
+
/** The single-letter or short alias (`-b`, `-w`, `--env`). */
|
|
421
|
+
readonly alias?: string;
|
|
422
|
+
/** yargs `requiresArg`: the flag needs a value after it. */
|
|
423
|
+
readonly requiresArg?: true;
|
|
424
|
+
/** yargs `string`: an array option whose elements stay strings (no number coercion). */
|
|
425
|
+
readonly string?: true;
|
|
426
|
+
/** yargs `choices`: the only values the option accepts. */
|
|
427
|
+
readonly choices?: readonly string[];
|
|
428
|
+
readonly description: string;
|
|
429
|
+
readonly support: JestCliSupport;
|
|
430
|
+
/** For `warn` and `refuse`: the task, track or decision that owns the missing piece. */
|
|
431
|
+
readonly owner?: string;
|
|
432
|
+
}
|
|
433
|
+
/**
|
|
434
|
+
* Jest 30.5.2's CLI options: `jest-cli` `src/args.ts`'s `options` object (`build/index.js` L70
|
|
435
|
+
* onward), the keys in its order, each with Provino's classification.
|
|
436
|
+
* @public
|
|
437
|
+
*/
|
|
438
|
+
export declare const JEST_CLI_OPTIONS: Readonly<Record<string, JestCliOption>>;
|
|
439
|
+
/**
|
|
440
|
+
* Stable codes for errors reading a Jest config, so callers and tests assert on the code. The
|
|
441
|
+
* message is Jest 30.5's own text wherever Jest has one (uncoloured), so a user sees what Jest
|
|
442
|
+
* would print.
|
|
443
|
+
*
|
|
444
|
+
* - `JEST_CONFIG_NOT_FOUND`: no config and no `package.json` from the directory up to the root.
|
|
445
|
+
* - `JEST_CONFIG_NO_ROOT`: an explicit path that doesn't exist.
|
|
446
|
+
* - `JEST_CONFIG_MULTIPLE`: more than one config in one directory ("Multiple configurations found").
|
|
447
|
+
* - `JEST_CONFIG_LOAD_FAILED`: the file couldn't be read or run, or its function threw (`cause`).
|
|
448
|
+
* - `JEST_CONFIG_RESOLVER_LOAD_FAILED`: the custom `resolver` module threw as it loaded. Jest lets
|
|
449
|
+
* that error out as it is and jest-cli prints its stack, so the `cause` is what to print.
|
|
450
|
+
* - `JEST_CONFIG_TS_LOADER`: a TypeScript config Node can't strip, and no loader to fall back to.
|
|
451
|
+
* - `JEST_CONFIG_INVALID`: a key has the wrong type or value (Jest's `ValidationError`).
|
|
452
|
+
* - `JEST_CONFIG_PRESET`: the preset can't be found or loaded.
|
|
453
|
+
* - `JEST_CONFIG_MODULE_NOT_FOUND`: a module a key names can't be resolved.
|
|
454
|
+
* - `JEST_CONFIG_DUPLICATE_PROJECT`: two `projects` resolve to the same config file.
|
|
455
|
+
* @public
|
|
456
|
+
*/
|
|
457
|
+
type JestConfigErrorCode = "JEST_CONFIG_NOT_FOUND" | "JEST_CONFIG_NO_ROOT" | "JEST_CONFIG_MULTIPLE" | "JEST_CONFIG_LOAD_FAILED" | "JEST_CONFIG_RESOLVER_LOAD_FAILED" | "JEST_CONFIG_TS_LOADER" | "JEST_CONFIG_INVALID" | "JEST_CONFIG_PRESET" | "JEST_CONFIG_MODULE_NOT_FOUND" | "JEST_CONFIG_DUPLICATE_PROJECT";
|
|
458
|
+
/**
|
|
459
|
+
* An error reading a Jest config, with a stable code. `cause` holds the underlying error where
|
|
460
|
+
* there is one.
|
|
461
|
+
* @public
|
|
462
|
+
*/
|
|
463
|
+
export declare class JestConfigError extends Error {
|
|
464
|
+
override readonly name = "JestConfigError";
|
|
465
|
+
readonly code: JestConfigErrorCode;
|
|
466
|
+
constructor(code: JestConfigErrorCode, message: string, options?: {
|
|
467
|
+
readonly cause?: unknown;
|
|
468
|
+
});
|
|
469
|
+
}
|
|
470
|
+
/**
|
|
471
|
+
* Stable codes for errors parsing a Jest command line (T11.7). The message is Jest's own text where
|
|
472
|
+
* Jest has one (uncoloured). Real Jest prints these and exits with code 1; the caller maps a
|
|
473
|
+
* `JestCliError` to Provino's usage exit code.
|
|
474
|
+
*
|
|
475
|
+
* - `JEST_CLI_INVALID`: yargs or `jest-cli`'s `check` refused the arguments (a missing value, a
|
|
476
|
+
* value outside the choices, flags that exclude each other), or a value Provino can't use.
|
|
477
|
+
* - `JEST_CLI_UNRECOGNIZED`: jest-validate's "Unrecognized CLI Parameter" (with a "did you mean").
|
|
478
|
+
* - `JEST_CLI_DEPRECATED`: a removed option (`--testPathPattern`, `--timers`, …).
|
|
479
|
+
* - `JEST_CLI_UNSUPPORTED`: `--help`, `-h`, `help` or `--version`, which Provino leaves to the
|
|
480
|
+
* real `jest`.
|
|
481
|
+
* - `JEST_CLI_UNSUPPORTED_FORM`: a yargs behaviour the parser doesn't rebuild, refused by name
|
|
482
|
+
* rather than parsed differently.
|
|
483
|
+
* @public
|
|
484
|
+
*/
|
|
485
|
+
type JestCliErrorCode = "JEST_CLI_INVALID" | "JEST_CLI_UNRECOGNIZED" | "JEST_CLI_DEPRECATED" | "JEST_CLI_UNSUPPORTED" | "JEST_CLI_UNSUPPORTED_FORM";
|
|
486
|
+
/**
|
|
487
|
+
* An error parsing a Jest command line, with a stable code.
|
|
488
|
+
* @public
|
|
489
|
+
*/
|
|
490
|
+
export declare class JestCliError extends Error {
|
|
491
|
+
override readonly name = "JestCliError";
|
|
492
|
+
readonly code: JestCliErrorCode;
|
|
493
|
+
constructor(code: JestCliErrorCode, message: string);
|
|
494
|
+
}
|
|
495
|
+
/**
|
|
496
|
+
* Parses Jest's command line (the arguments after `jest`), exactly as `jest-cli` 30.5.2's
|
|
497
|
+
* `buildArgv` does, without `$0`. Throws a `JestCliError` where Jest prints an error and exits.
|
|
498
|
+
* @public
|
|
499
|
+
*/
|
|
500
|
+
export declare function parseJestArgv(args: readonly string[]): JestArgv;
|
|
501
|
+
/**
|
|
502
|
+
* `parseJestArgv`, plus Provino's diagnostics: a `warning` for each flag it reads but doesn't apply
|
|
503
|
+
* yet, and an `error` for each flag it has no backend for (named with the task that builds it).
|
|
504
|
+
* The diagnostics come in the table's order.
|
|
505
|
+
* @public
|
|
506
|
+
*/
|
|
507
|
+
export declare function parseJestCli(args: readonly string[]): {
|
|
508
|
+
readonly argv: JestArgv;
|
|
509
|
+
readonly diagnostics: Diagnostic[];
|
|
510
|
+
};
|
|
511
|
+
/**
|
|
512
|
+
* The `RunRequest` a parsed Jest command line asks for. Positionals and `--testPathPatterns` are
|
|
513
|
+
* regex file filters (positionals are exact paths with `--runTestsByPath`, and no filter under
|
|
514
|
+
* `--findRelatedTests`, whose source paths they are). When several of
|
|
515
|
+
* `--showConfig`, `--clearCache` and `--listTests` are given, the mode is the one Jest acts on
|
|
516
|
+
* first (`jest-core` `cli/index.ts` L62 and L67, then `runJest.ts` L310). Throws a `JestCliError`
|
|
517
|
+
* for a `--maxWorkers` that is neither a count nor a percentage.
|
|
518
|
+
* @public
|
|
519
|
+
*/
|
|
520
|
+
export declare function jestArgvToRunRequest(argv: JestArgv): RunRequest;
|
|
521
|
+
/**
|
|
522
|
+
* The Jest command line: `parse` is `parseJestCli`, `toRunRequest` is `jestArgvToRunRequest`.
|
|
523
|
+
* @public
|
|
524
|
+
*/
|
|
525
|
+
export declare const jestCli: CliDialect<JestArgv>;
|
|
526
|
+
/**
|
|
527
|
+
* The flags the Jest command line accepts, in `jest-cli`'s table order.
|
|
528
|
+
* @public
|
|
529
|
+
*/
|
|
530
|
+
export declare const jestFlags: readonly FlagSpec[];
|
|
531
|
+
/**
|
|
532
|
+
* Which files of `project` count toward coverage, as `shouldInstrument` decides with Jest's
|
|
533
|
+
* options: `forceCoverageMatch`, the test files (`testMatch`, `testRegex`, unless
|
|
534
|
+
* `testPathIgnorePatterns` matches), `collectCoverageFrom` relative to the run's `rootDir`,
|
|
535
|
+
* `coveragePathIgnorePatterns`, and the setup and global hook files. With `babelInstruments` (the
|
|
536
|
+
* project's transform is Jest's default babel-jest, which instruments its own output), the files
|
|
537
|
+
* outside the process's working directory are left out too: babel-jest gives
|
|
538
|
+
* `babel-plugin-istanbul` `cwd: config.cwd` (babel-jest 30.5.2 `src/index.ts` L69-L70), where
|
|
539
|
+
* the ScriptTransformer path gives it `rootDir` (`ScriptTransformer.ts` L389). Recorded:
|
|
540
|
+
* `coverage/babel-cwd-below-root`.
|
|
541
|
+
* @public
|
|
542
|
+
*/
|
|
543
|
+
export declare function jestCoverageFilter(project: JestProjectConfig, globalConfig: JestGlobalConfig, options?: {
|
|
544
|
+
readonly babelInstruments?: boolean;
|
|
545
|
+
}): SerializedCoverageConfig;
|
|
546
|
+
/**
|
|
547
|
+
* What `jestCoverageOptions` reads besides the config.
|
|
548
|
+
* @public
|
|
549
|
+
*/
|
|
550
|
+
interface JestCoverageEnvironment {
|
|
551
|
+
/** The variables `getMaxCols` reads (`COLUMNS`, `CI`, `GITHUB_ACTIONS`, `JEST_WORKER_ID`). */
|
|
552
|
+
readonly env: Readonly<Record<string, string | undefined>>;
|
|
553
|
+
/** `process.stdout.columns`: the terminal's width, `undefined` when stdout is no terminal. */
|
|
554
|
+
readonly stdoutColumns: number | undefined;
|
|
555
|
+
}
|
|
556
|
+
/**
|
|
557
|
+
* What the coordinator reports with, from Jest's global config: the provider (`babel` is
|
|
558
|
+
* Istanbul), `coverageReporters` (`[]` becomes `['text-summary']` unless `useStderr`), each with
|
|
559
|
+
* `maxCols` under its own options, the directory, `getWatermarks` (the `global` thresholds raise
|
|
560
|
+
* the high marks) and the threshold groups in config order.
|
|
561
|
+
* @public
|
|
562
|
+
*/
|
|
563
|
+
export declare function jestCoverageOptions(globalConfig: JestGlobalConfig, environment: JestCoverageEnvironment): RunCoverageOptions;
|
|
564
|
+
/**
|
|
565
|
+
* The texts Jest's CoverageReporter prints around the reports, uncoloured (the caller colours
|
|
566
|
+
* them: `RUNNING_TEST_COLOR` is bold dim, the failures `chalk.red`).
|
|
567
|
+
* @public
|
|
568
|
+
*/
|
|
569
|
+
export declare const jestCoverageTexts: {
|
|
570
|
+
/** While the files no test loaded are covered, on a terminal (L159). */
|
|
571
|
+
readonly untestedNotice: string;
|
|
572
|
+
/** A file no test loaded whose coverage failed (L207-L213). */
|
|
573
|
+
untestedFailure(path: string, message: string, stack: string | undefined): string;
|
|
574
|
+
/** The reports failed (L118-L124): the template's own indentation is kept. */
|
|
575
|
+
reportFailure(text: string, stack: string | undefined): string;
|
|
576
|
+
};
|
|
577
|
+
/**
|
|
578
|
+
* The text `--debug` (and `--showConfig`) prints: `{ configs, globalConfig, version }` with two
|
|
579
|
+
* spaces of indent and a newline. The global config's `testPathPatterns` is the list of patterns
|
|
580
|
+
* (as Jest's `.patterns`), which is what the reader already keeps.
|
|
581
|
+
* @public
|
|
582
|
+
*/
|
|
583
|
+
export declare function jestDebugText(globalConfig: JestGlobalConfig, configs: readonly JestProjectConfig[], version: string): string;
|
|
584
|
+
/**
|
|
585
|
+
* A project's test paths in, the ones that run out.
|
|
586
|
+
* @public
|
|
587
|
+
*/
|
|
588
|
+
type JestFilter = (testPaths: readonly string[]) => Promise<readonly string[]>;
|
|
589
|
+
/**
|
|
590
|
+
* The module `--filter` (or the config's `filter`) names, loaded as `runCLI` does with a plain
|
|
591
|
+
* `require` (no transform), or `undefined` with no filter or with `--skipFilter`. A `setup` export
|
|
592
|
+
* starts at once; an error it throws is raised when the first project is filtered, not before.
|
|
593
|
+
* The filter is called once per project with that project's test paths (absolute); anything it
|
|
594
|
+
* returns without a `filtered` array is a `TypeError` (`SearchSource.getTestPaths`).
|
|
595
|
+
* @public
|
|
596
|
+
*/
|
|
597
|
+
export declare function loadJestFilter(globalConfig: {
|
|
598
|
+
readonly filter: JestGlobalConfig["filter"];
|
|
599
|
+
readonly skipFilter: boolean;
|
|
600
|
+
}): JestFilter | undefined;
|
|
601
|
+
/**
|
|
602
|
+
* `jest-config` `constants.ts` L21-L29: the extensions tried after `jest.config`, in order.
|
|
603
|
+
* @public
|
|
604
|
+
*/
|
|
605
|
+
export declare const JEST_CONFIG_EXT_ORDER: readonly string[];
|
|
606
|
+
/**
|
|
607
|
+
* The config file names a directory is searched for, in order (`package.json` last).
|
|
608
|
+
* @public
|
|
609
|
+
*/
|
|
610
|
+
export declare const JEST_CONFIG_CANDIDATES: readonly string[];
|
|
611
|
+
/**
|
|
612
|
+
* Whether `--config` was given JSON rather than a path (`jest-config` `utils.ts` L114-L118).
|
|
613
|
+
* @public
|
|
614
|
+
*/
|
|
615
|
+
export declare function isJSONString(text: string | undefined): text is string;
|
|
616
|
+
/**
|
|
617
|
+
* `package.json`'s `key`, or `undefined` for a file that is missing, not JSON or lacks it.
|
|
618
|
+
* @public
|
|
619
|
+
*/
|
|
620
|
+
export declare function packageJsonKey(path: string, key: string): unknown;
|
|
621
|
+
/**
|
|
622
|
+
* Jest's `resolveConfigPath(pathToResolve, cwd)`: the config file for a path (a file is itself; a
|
|
623
|
+
* directory is searched, then its parents). Throws `JestConfigError` with Jest's text:
|
|
624
|
+
* `JEST_CONFIG_NO_ROOT` for a path that doesn't exist, `JEST_CONFIG_MULTIPLE`, `JEST_CONFIG_INVALID`
|
|
625
|
+
* for a `package.json` string key that isn't a file, `JEST_CONFIG_NOT_FOUND` at the root.
|
|
626
|
+
* @public
|
|
627
|
+
*/
|
|
628
|
+
export declare function resolveJestConfigPath(pathToResolve: string, cwd: string, options?: {
|
|
629
|
+
readonly skipMultipleConfigError?: boolean;
|
|
630
|
+
}): string;
|
|
631
|
+
/**
|
|
632
|
+
* Finds the Jest config for `cwd`, as `jest` run there would (`readInitialOptions`, without
|
|
633
|
+
* reading the file). `explicit` is `--config`: JSON text (`{…}`) is an `inline` source, anything
|
|
634
|
+
* else a path resolved like the search. Throws `JestConfigError` (see `resolveJestConfigPath`).
|
|
635
|
+
* @public
|
|
636
|
+
*/
|
|
637
|
+
export declare function findJestConfig(cwd: string, explicit?: string): ConfigSource;
|
|
638
|
+
/**
|
|
639
|
+
* The hooks the run itself names, beside its projects' own: the root config's `globalSetup` and
|
|
640
|
+
* `globalTeardown`, which a config with `projects` keeps in its global config (`runGlobalHook` adds
|
|
641
|
+
* them to the projects' own). Every path is absolute. `undefined` when the run names neither.
|
|
642
|
+
* @public
|
|
643
|
+
*/
|
|
644
|
+
export declare function jestRunGlobalHooks(globalConfig: JestGlobalConfig): {
|
|
645
|
+
readonly setup: readonly string[];
|
|
646
|
+
readonly teardown: readonly string[];
|
|
647
|
+
} | undefined;
|
|
648
|
+
/**
|
|
649
|
+
* Reads one config file and sets its `rootDir`: Jest's `readConfigFileAndSetRootDir(configPath)`.
|
|
650
|
+
* Throws `JestConfigError` (`JEST_CONFIG_LOAD_FAILED`, `JEST_CONFIG_TS_LOADER`, `JEST_CONFIG_INVALID`).
|
|
651
|
+
* @public
|
|
652
|
+
*/
|
|
653
|
+
export declare function readJestConfigFile(configPath: string): Promise<JestInitialOptions>;
|
|
654
|
+
/**
|
|
655
|
+
* Reads the config a source names, as Jest's `readInitialOptions` does: a file is read and its
|
|
656
|
+
* `rootDir` set; inline JSON (`--config '{…}'`) gets `rootDir` from the source's directory when it
|
|
657
|
+
* has none. Returns the options and the config path (`null` for inline).
|
|
658
|
+
* @public
|
|
659
|
+
*/
|
|
660
|
+
export declare function loadJestConfig(source: ConfigSource): Promise<{
|
|
661
|
+
readonly options: JestInitialOptions;
|
|
662
|
+
readonly configPath: string | null;
|
|
663
|
+
}>;
|
|
664
|
+
/**
|
|
665
|
+
* An inline project object (`projects: [{ … }]`) as `readInitialOptions` prepares it (L337-L344):
|
|
666
|
+
* its `rootDir` is the parent config's directory, or its own with `<rootDir>` replaced by that.
|
|
667
|
+
* @public
|
|
668
|
+
*/
|
|
669
|
+
export declare function inlineProjectOptions(project: Readonly<Record<string, unknown>>, parentConfigDirname: string): JestInitialOptions;
|
|
670
|
+
/**
|
|
671
|
+
* `<rootDir>` at the start of a path, replaced by `rootDir` (`utils.ts` L60-L71). A path without it
|
|
672
|
+
* is returned as it is.
|
|
673
|
+
* @public
|
|
674
|
+
*/
|
|
675
|
+
export declare function replaceRootDirInPath(rootDir: string, filePath: string): string;
|
|
676
|
+
type Options = Record<string, unknown>;
|
|
677
|
+
/**
|
|
678
|
+
* Loads `optionsPreset` for a config and merges it in, as Jest's `setupPreset` does. `options`
|
|
679
|
+
* has its `rootDir` and `setupFiles` already (`normalizeMissingOptions`). Throws `JestConfigError`
|
|
680
|
+
* (`JEST_CONFIG_PRESET`) with Jest's text when the preset can't be found or loaded.
|
|
681
|
+
* @public
|
|
682
|
+
*/
|
|
683
|
+
export declare function setupPreset(options: Readonly<Options> & {
|
|
684
|
+
readonly rootDir: string;
|
|
685
|
+
}, optionsPreset: string, resolution: JestResolution): Promise<Options>;
|
|
686
|
+
/**
|
|
687
|
+
* The colours the text uses; `@provino/reporters`' `Style` has them all.
|
|
688
|
+
* @public
|
|
689
|
+
*/
|
|
690
|
+
interface CollectedTextStyle {
|
|
691
|
+
bold(text: string): string;
|
|
692
|
+
dim(text: string): string;
|
|
693
|
+
red(text: string): string;
|
|
694
|
+
green(text: string): string;
|
|
695
|
+
yellow(text: string): string;
|
|
696
|
+
magenta(text: string): string;
|
|
697
|
+
}
|
|
698
|
+
/**
|
|
699
|
+
* The text of a collect-only run: each file's tree (a file that failed to load, with its error),
|
|
700
|
+
* then the summary.
|
|
701
|
+
* @public
|
|
702
|
+
*/
|
|
703
|
+
export declare function jestCollectedText(results: AggregatedResult, style: CollectedTextStyle): string;
|
|
704
|
+
/**
|
|
705
|
+
* The text under a console entry of kind `level` whose call site is `origin`.
|
|
706
|
+
* @public
|
|
707
|
+
*/
|
|
708
|
+
export declare function jestConsoleTrace(origin: string, level: string | null, config: StackTraceConfig, globalConfig: {
|
|
709
|
+
readonly noStackTrace?: boolean;
|
|
710
|
+
}): string;
|
|
711
|
+
/**
|
|
712
|
+
* What `onRunStart` is given as its second argument (`ReporterOnStartOptions`).
|
|
713
|
+
* @public
|
|
714
|
+
*/
|
|
715
|
+
interface JestReporterOnStartOptions {
|
|
716
|
+
estimatedTime: number;
|
|
717
|
+
showStatus: boolean;
|
|
718
|
+
}
|
|
719
|
+
/**
|
|
720
|
+
* What a reporter class is constructed with as its third argument (`ReporterContext`,
|
|
721
|
+
* `@jest/reporters` `types.ts`).
|
|
722
|
+
* @public
|
|
723
|
+
*/
|
|
724
|
+
interface JestReporterContext {
|
|
725
|
+
firstRun: boolean;
|
|
726
|
+
previousSuccess: boolean;
|
|
727
|
+
changedFiles?: Set<string>;
|
|
728
|
+
sourcesRelatedToTestsInChangedFiles?: Set<string>;
|
|
729
|
+
/** Watch mode's `startRun` (`ReporterContext.startRun`), which a reporter may call. */
|
|
730
|
+
startRun?: (globalConfig: JestGlobalConfig) => unknown;
|
|
731
|
+
}
|
|
732
|
+
/**
|
|
733
|
+
* A Jest reporter (`Reporter`, `@jest/reporters`): every hook is optional.
|
|
734
|
+
* @public
|
|
735
|
+
*/
|
|
736
|
+
interface JestReporterInstance {
|
|
737
|
+
readonly onTestResult?: (test: Test, testResult: TestResult, aggregated: AggregatedResult) => Promise<void> | void;
|
|
738
|
+
readonly onTestFileResult?: (test: Test, testResult: TestResult, aggregated: AggregatedResult) => Promise<void> | void;
|
|
739
|
+
readonly onTestCaseStart?: (test: Test, info: TestCaseStartInfo) => Promise<void> | void;
|
|
740
|
+
readonly onTestCaseResult?: (test: Test, result: AssertionResult) => Promise<void> | void;
|
|
741
|
+
readonly onRunStart?: (aggregated: AggregatedResult, options: JestReporterOnStartOptions) => Promise<void> | void;
|
|
742
|
+
readonly onTestStart?: (test: Test) => Promise<void> | void;
|
|
743
|
+
readonly onTestFileStart?: (test: Test) => Promise<void> | void;
|
|
744
|
+
readonly onRunComplete?: (contexts: Set<TestContext>, aggregated: AggregatedResult) => Promise<void> | void;
|
|
745
|
+
readonly getLastError?: () => unknown;
|
|
746
|
+
}
|
|
747
|
+
/**
|
|
748
|
+
* A Jest reporter class, as a `reporters` entry's module exports it (`ReporterConstructor`).
|
|
749
|
+
* @public
|
|
750
|
+
*/
|
|
751
|
+
type JestReporterClass = new (globalConfig: never, options: Readonly<Record<string, unknown>>, context: JestReporterContext) => JestReporterInstance;
|
|
752
|
+
/**
|
|
753
|
+
* One custom reporter of the run: where it came from, its options, and its class.
|
|
754
|
+
* @public
|
|
755
|
+
*/
|
|
756
|
+
interface JestLoadedReporter {
|
|
757
|
+
readonly path: string;
|
|
758
|
+
readonly options: Readonly<Record<string, unknown>>;
|
|
759
|
+
readonly Class: JestReporterClass;
|
|
760
|
+
}
|
|
761
|
+
/**
|
|
762
|
+
* What `createJestReporterHost` needs.
|
|
763
|
+
* @public
|
|
764
|
+
*/
|
|
765
|
+
interface JestReporterHostOptions<Config extends ProjectConfigLike> {
|
|
766
|
+
/** The collector that is registered before the host's reporters. */
|
|
767
|
+
readonly results: JestResults<Config>;
|
|
768
|
+
/** The global config each class is constructed with. */
|
|
769
|
+
readonly globalConfig: unknown;
|
|
770
|
+
readonly entries: readonly JestLoadedReporter[];
|
|
771
|
+
readonly context?: JestReporterContext;
|
|
772
|
+
/**
|
|
773
|
+
* `showStatus` of `onRunStart` (Jest: not in band). Default: not `RunInfo.inBand`, the run's own
|
|
774
|
+
* decision, read at `run:start`.
|
|
775
|
+
*/
|
|
776
|
+
readonly showStatus?: boolean;
|
|
777
|
+
/**
|
|
778
|
+
* Hear one file at a time, as Jest does in band: a file's start and its events wait until the
|
|
779
|
+
* file before it has had its result. Default: `showStatus` is false.
|
|
780
|
+
*/
|
|
781
|
+
readonly serial?: boolean;
|
|
782
|
+
}
|
|
783
|
+
/**
|
|
784
|
+
* One neutral reporter per entry, in order, then one that frees each file's console buffer after
|
|
785
|
+
* every reporter has seen the file (`ReporterDispatcher.onTestFileResult`'s
|
|
786
|
+
* `testResult.console = undefined`). Register the collector first and the host's reporters after.
|
|
787
|
+
* A class that fails to construct fails its `run:start`, with Jest's wording.
|
|
788
|
+
* @public
|
|
789
|
+
*/
|
|
790
|
+
export declare function createJestReporterHost<Config extends ProjectConfigLike>(options: JestReporterHostOptions<Config>): Reporter[];
|
|
791
|
+
/**
|
|
792
|
+
* `jest-util`'s `specialChars.ICONS` (`specialChars.ts` L8-L16), as the result tree prints them:
|
|
793
|
+
* Windows has `\u00D7` and `\u221A` for a failure and a pass.
|
|
794
|
+
* @public
|
|
795
|
+
*/
|
|
796
|
+
export declare function jestResultIcons(platform?: string): {
|
|
797
|
+
readonly failed: string;
|
|
798
|
+
readonly pending: string;
|
|
799
|
+
readonly success: string;
|
|
800
|
+
readonly todo: string;
|
|
801
|
+
};
|
|
802
|
+
/**
|
|
803
|
+
* What `createJestGitHubActionsReporter` takes.
|
|
804
|
+
* @public
|
|
805
|
+
*/
|
|
806
|
+
interface JestGitHubActionsOptions {
|
|
807
|
+
/**
|
|
808
|
+
* The run's colours (Provino's own colour decision: `--colors`, `--no-color`, the terminal, the
|
|
809
|
+
* environment). Default: none, as chalk with no colour support.
|
|
810
|
+
*/
|
|
811
|
+
readonly style?: TextStyle;
|
|
812
|
+
/** `process.platform` for the result marks (`specialChars.ICONS`). Default: this process's. */
|
|
813
|
+
readonly platform?: string;
|
|
814
|
+
}
|
|
815
|
+
/**
|
|
816
|
+
* The `github-actions` reporter of Jest 30.5.2 (`silent` defaults to `true`, as there), coloured
|
|
817
|
+
* with `options.style`.
|
|
818
|
+
* @public
|
|
819
|
+
*/
|
|
820
|
+
export declare function createJestGitHubActionsReporter(options?: JestGitHubActionsOptions): JestReporterClass;
|
|
821
|
+
/**
|
|
822
|
+
* One reporter of the run.
|
|
823
|
+
* @public
|
|
824
|
+
*/
|
|
825
|
+
type JestReporterStep = {
|
|
826
|
+
readonly kind: "builtin";
|
|
827
|
+
readonly name: "default" | "verbose" | "agent" | "github-actions";
|
|
828
|
+
readonly options: Readonly<Record<string, unknown>>;
|
|
829
|
+
} | {
|
|
830
|
+
readonly kind: "custom";
|
|
831
|
+
/** The module path the config reader resolved. */
|
|
832
|
+
readonly path: string;
|
|
833
|
+
readonly options: Readonly<Record<string, unknown>>;
|
|
834
|
+
} | {
|
|
835
|
+
/** A reporter the host builds itself, named by one of `hostReporters` (D141). */
|
|
836
|
+
readonly kind: "host";
|
|
837
|
+
readonly name: string;
|
|
838
|
+
readonly options: Readonly<Record<string, unknown>>;
|
|
839
|
+
};
|
|
840
|
+
/**
|
|
841
|
+
* The reporters of a run, in the order they are added, and the options of the summary reporter
|
|
842
|
+
* that comes last (`undefined`: none, because no `default`, `agent` or `summary` was named).
|
|
843
|
+
* @public
|
|
844
|
+
*/
|
|
845
|
+
interface JestReporterPlan {
|
|
846
|
+
readonly steps: readonly JestReporterStep[];
|
|
847
|
+
readonly summary: {
|
|
848
|
+
readonly options: Readonly<Record<string, unknown>>;
|
|
849
|
+
} | undefined;
|
|
850
|
+
}
|
|
851
|
+
/**
|
|
852
|
+
* What the plan reads of the environment: Jest's `detectAgent()` and its `GITHUB_ACTIONS`.
|
|
853
|
+
* @public
|
|
854
|
+
*/
|
|
855
|
+
interface JestReporterEnvironment {
|
|
856
|
+
readonly agent: boolean;
|
|
857
|
+
readonly githubActions: boolean;
|
|
858
|
+
}
|
|
859
|
+
/**
|
|
860
|
+
* What the plan is told by its host.
|
|
861
|
+
* @public
|
|
862
|
+
*/
|
|
863
|
+
interface JestReporterPlanOptions {
|
|
864
|
+
/**
|
|
865
|
+
* The bare names the config reader kept for the host (`NormalizeOptions.hostReporters`): each
|
|
866
|
+
* becomes a `host` step, not a custom module. They print no summary of their own, so a plan of
|
|
867
|
+
* host steps alone has none. Default: none.
|
|
868
|
+
*/
|
|
869
|
+
readonly hostReporters?: readonly string[];
|
|
870
|
+
}
|
|
871
|
+
/**
|
|
872
|
+
* The plan for a run. `globalConfig.reporters` is what the config reader produced (`undefined` when
|
|
873
|
+
* the config and the command line name none). With none, Jest runs `agent` under an agent and
|
|
874
|
+
* `default` otherwise; Provino also adds `github-actions` on GitHub Actions (D88, DV59), where Jest
|
|
875
|
+
* adds it only when it is named. `default` is the verbose reporter when the global config or any
|
|
876
|
+
* project is verbose. A name in `options.hostReporters` is a `host` step.
|
|
877
|
+
* @public
|
|
878
|
+
*/
|
|
879
|
+
export declare function jestReporterPlan(globalConfig: {
|
|
880
|
+
readonly reporters: readonly (readonly [string, Readonly<Record<string, unknown>>])[] | undefined;
|
|
881
|
+
readonly verbose?: boolean | undefined;
|
|
882
|
+
}, projectConfigs: readonly {
|
|
883
|
+
readonly verbose?: boolean | undefined;
|
|
884
|
+
}[], environment: JestReporterEnvironment, planOptions?: JestReporterPlanOptions): JestReporterPlan;
|
|
885
|
+
/**
|
|
886
|
+
* The custom reporters of `plan` as loaded entries, in order, and Jest's `github-actions` reporter
|
|
887
|
+
* where the plan has it (its class is `jestGitHubActionsReporter`). A module that can't be loaded throws
|
|
888
|
+
* Jest's wrapped message: `An error occurred while adding the reporter at path "<path>".` and the
|
|
889
|
+
* error's own text.
|
|
890
|
+
* @public
|
|
891
|
+
*/
|
|
892
|
+
export declare function loadJestReporters(plan: JestReporterPlan, options?: {
|
|
893
|
+
readonly style?: TextStyle;
|
|
894
|
+
}): Promise<JestLoadedReporter[]>;
|
|
895
|
+
/**
|
|
896
|
+
* The part of `node-notifier` the reporter uses.
|
|
897
|
+
* @public
|
|
898
|
+
*/
|
|
899
|
+
interface JestNotifier {
|
|
900
|
+
notify(options: Readonly<Record<string, unknown>>): void;
|
|
901
|
+
}
|
|
902
|
+
/**
|
|
903
|
+
* Raised when `node-notifier` can't be found: Jest's text (`NotifyReporter.loadNotifier`), thrown
|
|
904
|
+
* where Jest constructs the reporter, so before any file runs. The run ends with its stack.
|
|
905
|
+
* @public
|
|
906
|
+
*/
|
|
907
|
+
export declare class JestNotifierMissingError extends Error {
|
|
908
|
+
constructor(options?: ErrorOptions);
|
|
909
|
+
}
|
|
910
|
+
/**
|
|
911
|
+
* `node-notifier` and what the notification names beside it.
|
|
912
|
+
* @public
|
|
913
|
+
*/
|
|
914
|
+
interface JestNotifierLoad {
|
|
915
|
+
readonly notifier: JestNotifier;
|
|
916
|
+
/** The `jest_logo.png` of the `@jest/reporters` install, Jest's icon; absent when none is found. */
|
|
917
|
+
readonly icon?: string;
|
|
918
|
+
}
|
|
919
|
+
/**
|
|
920
|
+
* Loads `node-notifier` from the project, then from where Jest's `@jest/reporters` is installed
|
|
921
|
+
* (Jest's `require` runs from there), and finds the icon in that install: one search for both.
|
|
922
|
+
* `JestNotifierMissingError` when neither has the module; any other error it throws on load is the
|
|
923
|
+
* caller's.
|
|
924
|
+
* @public
|
|
925
|
+
*/
|
|
926
|
+
export declare function loadJestNotifier(rootDir: string): JestNotifierLoad;
|
|
927
|
+
/**
|
|
928
|
+
* What `createNotifyReporter` reads of the global config.
|
|
929
|
+
* @public
|
|
930
|
+
*/
|
|
931
|
+
interface JestNotifyConfig {
|
|
932
|
+
readonly rootDir: string;
|
|
933
|
+
readonly notifyMode: string;
|
|
934
|
+
}
|
|
935
|
+
/**
|
|
936
|
+
* Jest's `NotifyReporter` as a reporter of the run. `previousSuccess` and `firstRun` are the
|
|
937
|
+
* context `runJest` gives a run that is not watching (`true` and `true`), which no `notifyMode`
|
|
938
|
+
* tells apart from a first run; watch mode is not built.
|
|
939
|
+
* @public
|
|
940
|
+
*/
|
|
941
|
+
export declare function createNotifyReporter(options: {
|
|
942
|
+
readonly globalConfig: JestNotifyConfig;
|
|
943
|
+
/** What `loadJestNotifier` found. */
|
|
944
|
+
readonly loaded: JestNotifierLoad;
|
|
945
|
+
/** The run's aggregate, complete once `run:end` has been heard. */
|
|
946
|
+
readonly aggregated: () => AggregatedResult;
|
|
947
|
+
}): Reporter;
|
|
948
|
+
/**
|
|
949
|
+
* What `processJestResults` needs.
|
|
950
|
+
* @public
|
|
951
|
+
*/
|
|
952
|
+
interface ProcessJestResultsOptions {
|
|
953
|
+
readonly aggregated: AggregatedResult;
|
|
954
|
+
readonly globalConfig: {
|
|
955
|
+
readonly json: boolean;
|
|
956
|
+
readonly outputFile: string | undefined;
|
|
957
|
+
readonly testResultsProcessor: string | undefined;
|
|
958
|
+
readonly testFailureExitCode: number;
|
|
959
|
+
};
|
|
960
|
+
/** The working directory the output file is resolved against. */
|
|
961
|
+
readonly cwd: string;
|
|
962
|
+
/** Where `--json` without an output file goes. */
|
|
963
|
+
readonly stdout: {
|
|
964
|
+
write(text: string): unknown;
|
|
965
|
+
};
|
|
966
|
+
/** Jest's output stream: stderr under `--json` or `--useStderr`, else stdout. */
|
|
967
|
+
readonly outputStream: {
|
|
968
|
+
write(text: string): unknown;
|
|
969
|
+
};
|
|
970
|
+
/**
|
|
971
|
+
* The run's coverage as a `CoverageMap`, when its reports were written: set on the results
|
|
972
|
+
* before the processor sees them, as the CoverageReporter sets it in `onRunComplete`.
|
|
973
|
+
*/
|
|
974
|
+
readonly coverageMap?: unknown;
|
|
975
|
+
}
|
|
976
|
+
/**
|
|
977
|
+
* Runs the processor, writes the JSON, and returns whether the run succeeded (the processor's
|
|
978
|
+
* results decide, as in Jest).
|
|
979
|
+
* @public
|
|
980
|
+
*/
|
|
981
|
+
export declare function processJestResults(options: ProcessJestResultsOptions): Promise<boolean>;
|
|
982
|
+
/**
|
|
983
|
+
* What the Snapshot Summary tells the user to run: ``press `u` `` in watch mode, the package
|
|
984
|
+
* script that started the run (`npm test -- -u`, ``yarn test -u``) when it runs Jest, else
|
|
985
|
+
* ``re-run jest with `-u` ``. `env` is the run's environment: this never reads `process.env`.
|
|
986
|
+
* @public
|
|
987
|
+
*/
|
|
988
|
+
export declare function jestUpdateCommand(env: Readonly<Record<string, string | undefined>>, watch: boolean): string;
|
|
989
|
+
/**
|
|
990
|
+
* Jest's Snapshot Summary lines (`getSnapshotSummary`), or none when the run wrote, updated,
|
|
991
|
+
* failed or found obsolete no snapshot (`_printSnapshotSummary`'s test). The caller adds the blank
|
|
992
|
+
* line after them.
|
|
993
|
+
* @public
|
|
994
|
+
*/
|
|
995
|
+
export declare function jestSnapshotSummary(snapshots: SnapshotSummary, globalConfig: Pick<JestGlobalConfig, "rootDir">, updateCommand: string, style: TextStyle): readonly string[];
|
|
996
|
+
/**
|
|
997
|
+
* The line after the totals (`_getTestSummary`): `Ran all test suites` and what narrowed the run
|
|
998
|
+
* (paths, changed files, a file pattern, a test name, the project count), or ``Test run was
|
|
999
|
+
* interrupted.``. `interrupted` is the aggregate's `wasInterrupted`: Jest sets it from
|
|
1000
|
+
* `watcher.isInterrupted()`, which only watch mode ever raises, so outside `watch` the line is
|
|
1001
|
+
* never printed, and a run that a signal cut has no closing line at all (Jest's process ends).
|
|
1002
|
+
* Nothing under `--silent`.
|
|
1003
|
+
* @public
|
|
1004
|
+
*/
|
|
1005
|
+
export declare function jestRunSummaryLine(globalConfig: Pick<JestGlobalConfig, "findRelatedTests" | "nonFlagArgs" | "onlyChanged" | "runTestsByPath" | "silent" | "testNamePattern" | "testPathPatterns">, run: {
|
|
1006
|
+
readonly interrupted: boolean;
|
|
1007
|
+
readonly contextCount: number;
|
|
1008
|
+
/** `--watch` or `--watchAll`. */
|
|
1009
|
+
readonly watch?: boolean;
|
|
1010
|
+
}, style: TextStyle): string | undefined;
|
|
1011
|
+
/**
|
|
1012
|
+
* The lines under a file's header about its snapshots (`getSnapshotStatus`): written, updated,
|
|
1013
|
+
* failed, obsolete (removed after `-u`) with each obsolete key, and a deleted `.snap`.
|
|
1014
|
+
* @public
|
|
1015
|
+
*/
|
|
1016
|
+
export declare function jestSnapshotStatus(snapshot: TestResult["snapshot"], afterUpdate: boolean, style: TextStyle): readonly string[];
|
|
1017
|
+
/**
|
|
1018
|
+
* The neutral environment name for a resolved Jest `testEnvironment`: `node`, `jsdom` or
|
|
1019
|
+
* `happy-dom` for the packages that provide them, else the path itself.
|
|
1020
|
+
* @public
|
|
1021
|
+
*/
|
|
1022
|
+
export declare function neutralEnvironmentName(testEnvironment: string): string;
|
|
1023
|
+
/** What `jestProjectToNeutral` needs besides the normalized config. */
|
|
1024
|
+
interface ToNeutralOptions {
|
|
1025
|
+
/** Whether the config named a `cacheDirectory`, so it is the user's (D70). Default: no. */
|
|
1026
|
+
readonly cacheDirectorySet?: boolean;
|
|
1027
|
+
/** The variables Jest reads (`NODE_PATH`). Default: `process.env`. */
|
|
1028
|
+
readonly env?: NodeJS.ProcessEnv;
|
|
1029
|
+
/** Where Jest's own packages resolve from. Default: the project's own Jest. */
|
|
1030
|
+
readonly requireResolve?: JestRequireResolve;
|
|
1031
|
+
}
|
|
1032
|
+
/**
|
|
1033
|
+
* One normalized project as a `NeutralProject`, with a warning for each key it reads but doesn't
|
|
1034
|
+
* apply yet. `globalConfig` is the run's (`passWithNoTests`, `maxConcurrency`, the global-only keys).
|
|
1035
|
+
* @public
|
|
1036
|
+
*/
|
|
1037
|
+
export declare function jestProjectToNeutral(project: JestProjectConfig, globalConfig: JestGlobalConfig, options?: ToNeutralOptions): {
|
|
1038
|
+
readonly project: NeutralProject;
|
|
1039
|
+
readonly diagnostics: readonly Diagnostic[];
|
|
1040
|
+
};
|
|
1041
|
+
/**
|
|
1042
|
+
* What validation found: warnings, and whether a deprecated key was among them.
|
|
1043
|
+
* @public
|
|
1044
|
+
*/
|
|
1045
|
+
interface ValidationOutcome {
|
|
1046
|
+
readonly diagnostics: readonly Diagnostic[];
|
|
1047
|
+
readonly hasDeprecationWarnings: boolean;
|
|
1048
|
+
}
|
|
1049
|
+
/**
|
|
1050
|
+
* Validates a config's keys as Jest 30.5 does before normalizing it. `isProject` is a config read
|
|
1051
|
+
* only as one of `projects` (Jest's `isProjectOptions`): its table is the project one, and a
|
|
1052
|
+
* global-only key gets the "move it to the root configuration" warning. Throws `JestConfigError`
|
|
1053
|
+
* (`JEST_CONFIG_INVALID`, Jest's text) for a known key of the wrong type.
|
|
1054
|
+
* @public
|
|
1055
|
+
*/
|
|
1056
|
+
export declare function validateJestConfig(options: Readonly<Record<string, unknown>>, isProject: boolean): ValidationOutcome;
|
|
1057
|
+
/**
|
|
1058
|
+
* The keys watch mode reads, as the bytes a terminal in raw mode sends (`constants.ts` L10-L21).
|
|
1059
|
+
* Backspace is `0x08` on Windows and `0x7f` elsewhere.
|
|
1060
|
+
* @beta
|
|
1061
|
+
*/
|
|
1062
|
+
interface JestWatchKeys {
|
|
1063
|
+
readonly ARROW_DOWN: string;
|
|
1064
|
+
readonly ARROW_LEFT: string;
|
|
1065
|
+
readonly ARROW_RIGHT: string;
|
|
1066
|
+
readonly ARROW_UP: string;
|
|
1067
|
+
readonly BACKSPACE: string;
|
|
1068
|
+
readonly CONTROL_C: string;
|
|
1069
|
+
readonly CONTROL_D: string;
|
|
1070
|
+
readonly CONTROL_U: string;
|
|
1071
|
+
readonly ENTER: string;
|
|
1072
|
+
readonly ESCAPE: string;
|
|
1073
|
+
}
|
|
1074
|
+
/**
|
|
1075
|
+
* The keys on `platform` (`process.platform` is what Jest reads).
|
|
1076
|
+
* @beta
|
|
1077
|
+
*/
|
|
1078
|
+
export declare function jestWatchKeys(platform: NodeJS.Platform): JestWatchKeys;
|
|
1079
|
+
/**
|
|
1080
|
+
* Where the prompt's scrolled list starts (`ScrollOptions`).
|
|
1081
|
+
* @beta
|
|
1082
|
+
*/
|
|
1083
|
+
interface JestScrollOptions {
|
|
1084
|
+
readonly offset: number;
|
|
1085
|
+
readonly max: number;
|
|
1086
|
+
}
|
|
1087
|
+
/**
|
|
1088
|
+
* A terminal whose resizes redraw the prompt (Jest listens on `process.stdout`).
|
|
1089
|
+
* @beta
|
|
1090
|
+
*/
|
|
1091
|
+
interface JestResizeSource {
|
|
1092
|
+
on(event: "resize", listener: () => void): unknown;
|
|
1093
|
+
removeListener(event: "resize", listener: () => void): unknown;
|
|
1094
|
+
}
|
|
1095
|
+
/**
|
|
1096
|
+
* The prompt: `enter` starts it, `put` takes each key, Enter ends it with the value, Esc cancels.
|
|
1097
|
+
* @beta
|
|
1098
|
+
*/
|
|
1099
|
+
export declare class JestPrompt {
|
|
1100
|
+
#private;
|
|
1101
|
+
constructor(keys: JestWatchKeys, resizes?: JestResizeSource);
|
|
1102
|
+
/** `Prompt.ts` L37-L58. */
|
|
1103
|
+
enter(onChange: (pattern: string, options: JestScrollOptions) => void, onSuccess: (pattern: string) => void, onCancel: () => void): void;
|
|
1104
|
+
setPromptLength(length: number): void;
|
|
1105
|
+
setPromptSelection(selected: string): void;
|
|
1106
|
+
/** `Prompt.ts` L68-L105. */
|
|
1107
|
+
put(key: string): void;
|
|
1108
|
+
/** `Prompt.ts` L107-L111. */
|
|
1109
|
+
abort(): void;
|
|
1110
|
+
isEntering(): boolean;
|
|
1111
|
+
}
|
|
1112
|
+
/**
|
|
1113
|
+
* jest-util `specialChars.CLEAR` (`specialChars.ts` L11-L13): erase the screen and the scrollback,
|
|
1114
|
+
* cursor home; on Windows erase the screen and home.
|
|
1115
|
+
* @beta
|
|
1116
|
+
*/
|
|
1117
|
+
export declare function jestClearScreen(platform: NodeJS.Platform): string;
|
|
1118
|
+
/**
|
|
1119
|
+
* The escapes of `ansi-escapes` 4.3.2 the watch mode uses (`index.js` L46-L77). The cursor's save and
|
|
1120
|
+
* restore are `ESC 7` and `ESC 8` under Apple's Terminal (`TERM_PROGRAM === 'Apple_Terminal'`),
|
|
1121
|
+
* else `CSI s` and `CSI u`.
|
|
1122
|
+
* @beta
|
|
1123
|
+
*/
|
|
1124
|
+
interface JestTerminalEscapes {
|
|
1125
|
+
readonly cursorHide: string;
|
|
1126
|
+
readonly cursorShow: string;
|
|
1127
|
+
readonly cursorLeft: string;
|
|
1128
|
+
readonly eraseLine: string;
|
|
1129
|
+
readonly eraseDown: string;
|
|
1130
|
+
readonly cursorSavePosition: string;
|
|
1131
|
+
readonly cursorRestorePosition: string;
|
|
1132
|
+
cursorUp(count?: number): string;
|
|
1133
|
+
cursorDown(count?: number): string;
|
|
1134
|
+
cursorTo(x: number, y: number): string;
|
|
1135
|
+
}
|
|
1136
|
+
/**
|
|
1137
|
+
* The escapes for a terminal (`appleTerminal`: `TERM_PROGRAM` is `Apple_Terminal`).
|
|
1138
|
+
* @beta
|
|
1139
|
+
*/
|
|
1140
|
+
export declare function jestTerminalEscapes(appleTerminal: boolean): JestTerminalEscapes;
|
|
1141
|
+
/**
|
|
1142
|
+
* jest-util `clearLine` (`clearLine.ts` L10-L14): what a reporter writes to a terminal before its
|
|
1143
|
+
* first line, and what `CustomConsole` writes before each entry, so the pre-run message goes.
|
|
1144
|
+
* @beta
|
|
1145
|
+
*/
|
|
1146
|
+
export declare const JEST_CLEAR_LINE: string;
|
|
1147
|
+
/**
|
|
1148
|
+
* jest-util `preRunMessage.print` (`preRunMessage.ts` L13-L17): written before each run on an
|
|
1149
|
+
* interactive terminal, bold and dim.
|
|
1150
|
+
* @beta
|
|
1151
|
+
*/
|
|
1152
|
+
export declare const JEST_PRE_RUN_MESSAGE: string;
|
|
1153
|
+
/**
|
|
1154
|
+
* `string-length` 4 as jest-watcher uses it (`patternModeHelpers.ts` L30): the length of the text
|
|
1155
|
+
* with its escapes taken out, in code points.
|
|
1156
|
+
* @beta
|
|
1157
|
+
*/
|
|
1158
|
+
export declare function jestStringLength(text: string): number;
|
|
1159
|
+
/**
|
|
1160
|
+
* A stream the watch mode writes to (Jest's `outputStream`).
|
|
1161
|
+
* @beta
|
|
1162
|
+
*/
|
|
1163
|
+
interface JestWatchOutput {
|
|
1164
|
+
write(text: string): unknown;
|
|
1165
|
+
}
|
|
1166
|
+
/**
|
|
1167
|
+
* The terminal the watch mode draws on: where it writes, how it colours (the host's choice, as
|
|
1168
|
+
* chalk's is Jest's), the escapes, the screen clear and the keys of this platform.
|
|
1169
|
+
* @beta
|
|
1170
|
+
*/
|
|
1171
|
+
interface JestWatchTerminal {
|
|
1172
|
+
readonly out: JestWatchOutput;
|
|
1173
|
+
readonly style: TextStyle;
|
|
1174
|
+
readonly escapes: JestTerminalEscapes;
|
|
1175
|
+
readonly clear: string;
|
|
1176
|
+
readonly keys: JestWatchKeys;
|
|
1177
|
+
/** Resizes redraw an open prompt (Jest listens on `process.stdout`). */
|
|
1178
|
+
readonly resizes?: JestResizeSource;
|
|
1179
|
+
}
|
|
1180
|
+
/**
|
|
1181
|
+
* The part of Jest's `AggregatedResult` the watch mode reads: the failed-tests cache, the
|
|
1182
|
+
* interactive plugins' usage rows and the run's own `onTestRunComplete` listeners.
|
|
1183
|
+
* @beta
|
|
1184
|
+
*/
|
|
1185
|
+
interface JestWatchResults {
|
|
1186
|
+
readonly numFailedTests: number;
|
|
1187
|
+
readonly snapshot: {
|
|
1188
|
+
readonly failure: boolean;
|
|
1189
|
+
readonly unmatched: number;
|
|
1190
|
+
};
|
|
1191
|
+
readonly testResults: readonly {
|
|
1192
|
+
readonly testFilePath: string;
|
|
1193
|
+
readonly numFailingTests: number;
|
|
1194
|
+
readonly testExecError?: unknown;
|
|
1195
|
+
readonly snapshot?: {
|
|
1196
|
+
readonly unmatched: number;
|
|
1197
|
+
};
|
|
1198
|
+
readonly testResults: readonly {
|
|
1199
|
+
readonly fullName: string;
|
|
1200
|
+
readonly status: string;
|
|
1201
|
+
}[];
|
|
1202
|
+
}[];
|
|
1203
|
+
}
|
|
1204
|
+
/**
|
|
1205
|
+
* What `onFileChange` listeners get: each project's test paths (`watch.ts` L231-L245).
|
|
1206
|
+
* @beta
|
|
1207
|
+
*/
|
|
1208
|
+
interface JestFileChange {
|
|
1209
|
+
readonly projects: readonly {
|
|
1210
|
+
readonly config: unknown;
|
|
1211
|
+
readonly testPaths: readonly string[];
|
|
1212
|
+
}[];
|
|
1213
|
+
}
|
|
1214
|
+
/**
|
|
1215
|
+
* What `shouldRunTestSuite` listeners get (`runJest.ts` L149-L157).
|
|
1216
|
+
* @beta
|
|
1217
|
+
*/
|
|
1218
|
+
interface JestTestSuiteInfo {
|
|
1219
|
+
readonly config: unknown;
|
|
1220
|
+
readonly duration: number | undefined;
|
|
1221
|
+
readonly testPath: string;
|
|
1222
|
+
}
|
|
1223
|
+
/**
|
|
1224
|
+
* What a plugin's `apply` gets (`JestHookSubscriber`).
|
|
1225
|
+
* @beta
|
|
1226
|
+
*/
|
|
1227
|
+
interface JestHookSubscriber {
|
|
1228
|
+
onFileChange(listener: (change: JestFileChange) => void): void;
|
|
1229
|
+
onTestRunComplete(listener: (results: JestWatchResults) => void): void;
|
|
1230
|
+
shouldRunTestSuite(listener: (info: JestTestSuiteInfo) => boolean | Promise<boolean>): void;
|
|
1231
|
+
}
|
|
1232
|
+
/**
|
|
1233
|
+
* What the driver calls (`JestHookEmitter`).
|
|
1234
|
+
* @beta
|
|
1235
|
+
*/
|
|
1236
|
+
interface JestHookEmitter {
|
|
1237
|
+
onFileChange(change: JestFileChange): void;
|
|
1238
|
+
onTestRunComplete(results: JestWatchResults): void;
|
|
1239
|
+
shouldRunTestSuite(info: JestTestSuiteInfo): Promise<boolean>;
|
|
1240
|
+
}
|
|
1241
|
+
/**
|
|
1242
|
+
* One session's hooks (`new JestHooks()`).
|
|
1243
|
+
* @beta
|
|
1244
|
+
*/
|
|
1245
|
+
interface JestHooks {
|
|
1246
|
+
readonly subscriber: JestHookSubscriber;
|
|
1247
|
+
readonly emitter: JestHookEmitter;
|
|
1248
|
+
isUsed(hook: "onFileChange" | "onTestRunComplete" | "shouldRunTestSuite"): boolean;
|
|
1249
|
+
}
|
|
1250
|
+
/**
|
|
1251
|
+
* Makes the hooks of one watch session.
|
|
1252
|
+
* @beta
|
|
1253
|
+
*/
|
|
1254
|
+
export declare function createJestHooks(): JestHooks;
|
|
1255
|
+
/**
|
|
1256
|
+
* The failed tests of the last run, by file.
|
|
1257
|
+
* @beta
|
|
1258
|
+
*/
|
|
1259
|
+
export declare class JestFailedTestsCache {
|
|
1260
|
+
#private;
|
|
1261
|
+
/**
|
|
1262
|
+
* `filterTests` (L15-L22): before any run, every path; after one, the files that failed in it (a
|
|
1263
|
+
* file that failed to run counts, with no test named).
|
|
1264
|
+
*/
|
|
1265
|
+
filterPaths<T extends {
|
|
1266
|
+
readonly path: string;
|
|
1267
|
+
}>(tests: readonly T[]): readonly T[];
|
|
1268
|
+
/** `setTestResults` (L24-L50). */
|
|
1269
|
+
setTestResults(testResults: JestWatchResults["testResults"]): void;
|
|
1270
|
+
}
|
|
1271
|
+
/**
|
|
1272
|
+
* A test that failed, by its full name and its file (`AssertionLocation`).
|
|
1273
|
+
* @beta
|
|
1274
|
+
*/
|
|
1275
|
+
interface JestAssertionLocation {
|
|
1276
|
+
readonly fullName: string;
|
|
1277
|
+
readonly path: string;
|
|
1278
|
+
}
|
|
1279
|
+
/**
|
|
1280
|
+
* jest-util `specialChars.ARROW` (`specialChars.ts` L9).
|
|
1281
|
+
* @beta
|
|
1282
|
+
*/
|
|
1283
|
+
export declare const JEST_ARROW: string;
|
|
1284
|
+
/**
|
|
1285
|
+
* jest-util `pluralize` (`pluralize.ts` L8-L10).
|
|
1286
|
+
* @beta
|
|
1287
|
+
*/
|
|
1288
|
+
export declare function jestPluralize(word: string, count: number): string;
|
|
1289
|
+
/**
|
|
1290
|
+
* The interactive failed-tests mode (`FailedTestsInteractiveMode`). `run` calls `updateConfig`
|
|
1291
|
+
* with the test to run next, or with nothing when the mode ends.
|
|
1292
|
+
* @beta
|
|
1293
|
+
*/
|
|
1294
|
+
export declare class JestFailedTestsInteractiveMode {
|
|
1295
|
+
#private;
|
|
1296
|
+
constructor(terminal: JestWatchTerminal);
|
|
1297
|
+
isActive(): boolean;
|
|
1298
|
+
/** L37-L70 */
|
|
1299
|
+
put(key: string): void;
|
|
1300
|
+
/** L72-L83 */
|
|
1301
|
+
run(failedTestAssertions: readonly JestAssertionLocation[], updateConfig: (failure?: JestAssertionLocation) => void): void;
|
|
1302
|
+
/** L85-L97 */
|
|
1303
|
+
updateWithResults(results: JestWatchResults): void;
|
|
1304
|
+
}
|
|
1305
|
+
/**
|
|
1306
|
+
* What a key or a plugin may change (jest-watcher `AllowedConfigOptions`), plus the driver's own
|
|
1307
|
+
* `passWithNoTests`. `mode` is `--watch` or `--watchAll`.
|
|
1308
|
+
* @beta
|
|
1309
|
+
*/
|
|
1310
|
+
interface JestWatchConfigUpdate {
|
|
1311
|
+
readonly bail?: boolean | number;
|
|
1312
|
+
readonly changedSince?: string;
|
|
1313
|
+
readonly collectCoverage?: boolean;
|
|
1314
|
+
readonly collectCoverageFrom?: readonly string[];
|
|
1315
|
+
readonly coverageDirectory?: string;
|
|
1316
|
+
readonly coverageReporters?: readonly unknown[];
|
|
1317
|
+
readonly findRelatedTests?: boolean;
|
|
1318
|
+
readonly mode?: "watch" | "watchAll";
|
|
1319
|
+
readonly nonFlagArgs?: readonly string[];
|
|
1320
|
+
readonly notify?: boolean;
|
|
1321
|
+
readonly notifyMode?: string;
|
|
1322
|
+
readonly onlyFailures?: boolean;
|
|
1323
|
+
readonly passWithNoTests?: true;
|
|
1324
|
+
readonly reporters?: JestGlobalConfig["reporters"];
|
|
1325
|
+
readonly testNamePattern?: string;
|
|
1326
|
+
readonly testPathPatterns?: readonly string[];
|
|
1327
|
+
readonly updateSnapshot?: JestGlobalConfig["updateSnapshot"];
|
|
1328
|
+
readonly verbose?: boolean;
|
|
1329
|
+
}
|
|
1330
|
+
/**
|
|
1331
|
+
* `updateGlobalConfig(globalConfig, options)`: a copy with the options applied and `onlyChanged`
|
|
1332
|
+
* worked out again (on unless `--watchAll`, a name pattern or a path pattern).
|
|
1333
|
+
* @beta
|
|
1334
|
+
*/
|
|
1335
|
+
export declare function updateJestWatchConfig(globalConfig: JestGlobalConfig, options?: JestWatchConfigUpdate): JestGlobalConfig;
|
|
1336
|
+
/**
|
|
1337
|
+
* A usage row: the key and what it does (`UsageData`).
|
|
1338
|
+
* @beta
|
|
1339
|
+
*/
|
|
1340
|
+
interface JestUsageData {
|
|
1341
|
+
readonly key: string;
|
|
1342
|
+
readonly prompt: string;
|
|
1343
|
+
}
|
|
1344
|
+
/**
|
|
1345
|
+
* What a plugin's `run` gets to start a run with a new config (`UpdateConfigCallback`).
|
|
1346
|
+
* @beta
|
|
1347
|
+
*/
|
|
1348
|
+
type JestUpdateConfigAndRun = (update?: JestWatchConfigUpdate) => void;
|
|
1349
|
+
/**
|
|
1350
|
+
* A watch plugin. `isInternal` sorts Jest's own before any other; `FailedTestsInteractive` is not
|
|
1351
|
+
* marked, so its row comes after the internal ones.
|
|
1352
|
+
* @beta
|
|
1353
|
+
*/
|
|
1354
|
+
interface JestWatchPlugin {
|
|
1355
|
+
readonly isInternal?: true;
|
|
1356
|
+
apply?(hooks: JestHookSubscriber): void;
|
|
1357
|
+
getUsageInfo?(globalConfig: JestGlobalConfig): JestUsageData | null;
|
|
1358
|
+
onKey?(key: string): void;
|
|
1359
|
+
/** Resolves truthy when the driver should run again with the config as it is (Jest's `boolean`). */
|
|
1360
|
+
run?(globalConfig: JestGlobalConfig, updateConfigAndRun: JestUpdateConfigAndRun): Promise<unknown>;
|
|
1361
|
+
}
|
|
1362
|
+
/**
|
|
1363
|
+
* `filterInteractivePlugins` (L12-L29): the plugins with a usage row whose key no later plugin
|
|
1364
|
+
* takes.
|
|
1365
|
+
* @beta
|
|
1366
|
+
*/
|
|
1367
|
+
export declare function filterInteractivePlugins(plugins: readonly JestWatchPlugin[], globalConfig: JestGlobalConfig): JestWatchPlugin[];
|
|
1368
|
+
/**
|
|
1369
|
+
* `getSortedUsageRows` (L31-L56): internal plugins first in their own order, the others after them
|
|
1370
|
+
* by key.
|
|
1371
|
+
* @beta
|
|
1372
|
+
*/
|
|
1373
|
+
export declare function getSortedUsageRows(plugins: readonly JestWatchPlugin[], globalConfig: JestGlobalConfig): JestUsageData[];
|
|
1374
|
+
/**
|
|
1375
|
+
* The key a plugin owns (`watch.ts` L525-L534).
|
|
1376
|
+
* @beta
|
|
1377
|
+
*/
|
|
1378
|
+
export declare function pluginKey(plugin: JestWatchPlugin, globalConfig: JestGlobalConfig): string | null;
|
|
1379
|
+
/**
|
|
1380
|
+
* `FailedTestsInteractivePlugin`: `i`, `run failing tests interactively`, after a run with a
|
|
1381
|
+
* failed test and no unmatched snapshot. Not internal (Jest doesn't mark it), so its row sorts
|
|
1382
|
+
* after Jest's own.
|
|
1383
|
+
* @beta
|
|
1384
|
+
*/
|
|
1385
|
+
export declare function jestFailedTestsInteractivePlugin(terminal: JestWatchTerminal): JestWatchPlugin;
|
|
1386
|
+
/**
|
|
1387
|
+
* `UpdateSnapshotsPlugin`: `u`, `update failing snapshots`, after a run with a snapshot failure.
|
|
1388
|
+
* The run it starts has `updateSnapshot: 'all'`, which the driver resets after it.
|
|
1389
|
+
* @beta
|
|
1390
|
+
*/
|
|
1391
|
+
export declare function jestUpdateSnapshotsPlugin(): JestWatchPlugin;
|
|
1392
|
+
/**
|
|
1393
|
+
* `UpdateSnapshotInteractivePlugin`: `i`, `update failing snapshots interactively`, after a run
|
|
1394
|
+
* with a failed test in a file whose snapshots didn't match.
|
|
1395
|
+
* @beta
|
|
1396
|
+
*/
|
|
1397
|
+
export declare function jestUpdateSnapshotsInteractivePlugin(terminal: JestWatchTerminal): JestWatchPlugin;
|
|
1398
|
+
/**
|
|
1399
|
+
* `TestPathPatternPlugin`: `p`, `filter by a filename regex pattern`.
|
|
1400
|
+
* @beta
|
|
1401
|
+
*/
|
|
1402
|
+
export declare function jestTestPathPatternPlugin(terminal: JestWatchTerminal): JestWatchPlugin;
|
|
1403
|
+
/**
|
|
1404
|
+
* `TestNamePatternPlugin`: `t`, `filter by a test name regex pattern`.
|
|
1405
|
+
* @beta
|
|
1406
|
+
*/
|
|
1407
|
+
export declare function jestTestNamePatternPlugin(terminal: JestWatchTerminal): JestWatchPlugin;
|
|
1408
|
+
/**
|
|
1409
|
+
* `printPatternCaret` (`patternModeHelpers.ts` L12-L21): erase below, the ` pattern › ` line, save
|
|
1410
|
+
* the cursor.
|
|
1411
|
+
* @beta
|
|
1412
|
+
*/
|
|
1413
|
+
export declare function printPatternCaret(pattern: string, terminal: JestWatchTerminal): void;
|
|
1414
|
+
/**
|
|
1415
|
+
* `printRestoredPatternCaret` (`patternModeHelpers.ts` L23-L34): the cursor to the end of the
|
|
1416
|
+
* pattern on the prompt's row, then restored.
|
|
1417
|
+
* @beta
|
|
1418
|
+
*/
|
|
1419
|
+
export declare function printRestoredPatternCaret(pattern: string, currentUsageRows: number, terminal: JestWatchTerminal): void;
|
|
1420
|
+
/**
|
|
1421
|
+
* The filename (`entity` `filenames`) or test-name (`tests`) prompt: `run` draws the screen and
|
|
1422
|
+
* hands the keys to `prompt`, each change erases the line and draws the caret again.
|
|
1423
|
+
* @beta
|
|
1424
|
+
*/
|
|
1425
|
+
export declare class JestPatternPrompt {
|
|
1426
|
+
#private;
|
|
1427
|
+
constructor(terminal: JestWatchTerminal, prompt: JestPrompt, entity: "filenames" | "tests");
|
|
1428
|
+
/** `PatternPrompt.ts` L36-L55. */
|
|
1429
|
+
run(onSuccess: (value: string) => void, onCancel: () => void, options?: {
|
|
1430
|
+
readonly header: string;
|
|
1431
|
+
}): void;
|
|
1432
|
+
}
|
|
1433
|
+
/**
|
|
1434
|
+
* The terminal's input as watch mode reads it: raw mode when it is a terminal, `utf8` chunks.
|
|
1435
|
+
* @beta
|
|
1436
|
+
*/
|
|
1437
|
+
interface JestWatchStdin {
|
|
1438
|
+
readonly setRawMode?: (mode: boolean) => unknown;
|
|
1439
|
+
resume(): unknown;
|
|
1440
|
+
pause(): unknown;
|
|
1441
|
+
setEncoding(encoding: "utf8"): unknown;
|
|
1442
|
+
on(event: "data", listener: (chunk: string) => void): unknown;
|
|
1443
|
+
off(event: "data", listener: (chunk: string) => void): unknown;
|
|
1444
|
+
}
|
|
1445
|
+
/**
|
|
1446
|
+
* `QuitPlugin`: `q`, `quit watch mode`.
|
|
1447
|
+
* @beta
|
|
1448
|
+
*/
|
|
1449
|
+
export declare function jestQuitPlugin(terminal: JestWatchTerminal, stdin: JestWatchStdin, exit: (code: number) => void): JestWatchPlugin;
|
|
1450
|
+
/**
|
|
1451
|
+
* Why watch mode could not start with its plugins.
|
|
1452
|
+
*
|
|
1453
|
+
* - `JEST_WATCH_PLUGIN_LOAD`: a plugin's module failed to load, or its class to construct.
|
|
1454
|
+
* - `JEST_WATCH_PLUGIN_CONFLICT`: a plugin took a key Jest reserves, or one another plugin took.
|
|
1455
|
+
* - `JEST_WATCH_PLUGIN_HOOK`: a plugin's `onFileChange` listener threw (Jest's call is synchronous,
|
|
1456
|
+
* so the throw ends the session: jest-cli prints its stack in red, exit 1).
|
|
1457
|
+
* @beta
|
|
1458
|
+
*/
|
|
1459
|
+
type JestWatchPluginErrorCode = "JEST_WATCH_PLUGIN_LOAD" | "JEST_WATCH_PLUGIN_CONFLICT" | "JEST_WATCH_PLUGIN_HOOK";
|
|
1460
|
+
/**
|
|
1461
|
+
* A watch plugin that could not be loaded or that conflicts. `message` is what jest-cli prints
|
|
1462
|
+
* for it (`run.ts` L30-L38: the error's `stack` in red, or the error itself where it has none),
|
|
1463
|
+
* and Jest exits 1.
|
|
1464
|
+
* @beta
|
|
1465
|
+
*/
|
|
1466
|
+
export declare class JestWatchPluginError extends Error {
|
|
1467
|
+
override readonly name = "JestWatchPluginError";
|
|
1468
|
+
readonly code: JestWatchPluginErrorCode;
|
|
1469
|
+
constructor(code: JestWatchPluginErrorCode, message: string, options?: {
|
|
1470
|
+
cause?: unknown;
|
|
1471
|
+
});
|
|
1472
|
+
}
|
|
1473
|
+
/**
|
|
1474
|
+
* What a key is reserved for (`ReservedInfo`): `forbiddenOverwriteMessage` set, no plugin may take
|
|
1475
|
+
* the key; unset, the first plugin to claim it replaces Jest's own.
|
|
1476
|
+
* @beta
|
|
1477
|
+
*/
|
|
1478
|
+
interface JestReservedKey {
|
|
1479
|
+
readonly key?: string;
|
|
1480
|
+
readonly forbiddenOverwriteMessage?: string;
|
|
1481
|
+
}
|
|
1482
|
+
interface ReservedInfo {
|
|
1483
|
+
readonly forbiddenOverwriteMessage?: string | undefined;
|
|
1484
|
+
readonly overwritable: boolean;
|
|
1485
|
+
readonly plugin: JestWatchPlugin;
|
|
1486
|
+
}
|
|
1487
|
+
/**
|
|
1488
|
+
* The keys taken so far (`WatchPluginKeysMap`).
|
|
1489
|
+
* @beta
|
|
1490
|
+
*/
|
|
1491
|
+
type JestWatchPluginKeys = Map<string, ReservedInfo>;
|
|
1492
|
+
/**
|
|
1493
|
+
* `getPluginIdentifier` (L517-L523): the plugin class's `displayName`, else its `name`.
|
|
1494
|
+
* @beta
|
|
1495
|
+
*/
|
|
1496
|
+
export declare function getJestPluginIdentifier(plugin: JestWatchPlugin): string;
|
|
1497
|
+
/**
|
|
1498
|
+
* `getPluginKey` (L525-L534): the key of the plugin's usage row for this config, or `null`.
|
|
1499
|
+
* @beta
|
|
1500
|
+
*/
|
|
1501
|
+
export declare function getJestPluginKey(plugin: JestWatchPlugin, globalConfig: JestGlobalConfig): string | null;
|
|
1502
|
+
/**
|
|
1503
|
+
* The keys Jest's own plugins hold before any third-party one loads (L169-L188): a reserved key
|
|
1504
|
+
* from `reserved`, else the plugin's current key; a plugin with neither holds none.
|
|
1505
|
+
* @beta
|
|
1506
|
+
*/
|
|
1507
|
+
export declare function jestWatchPluginKeys(plugins: readonly JestWatchPlugin[], reserved: ReadonlyMap<JestWatchPlugin, JestReservedKey>, globalConfig: JestGlobalConfig): JestWatchPluginKeys;
|
|
1508
|
+
/**
|
|
1509
|
+
* `checkForConflicts` (L474-L515): a plugin with a key takes it when no one holds it or Jest's own
|
|
1510
|
+
* plugin may give it up; otherwise Jest's `ValidationError`, as jest-validate words it
|
|
1511
|
+
* (`utils.ts` L29-L41: `<name>:\n\n<message>\n`, red, the name bold).
|
|
1512
|
+
* @beta
|
|
1513
|
+
*/
|
|
1514
|
+
export declare function checkJestWatchPluginConflicts(keys: JestWatchPluginKeys, plugin: JestWatchPlugin, globalConfig: JestGlobalConfig, style: TextStyle): void;
|
|
1515
|
+
/**
|
|
1516
|
+
* What a third-party plugin is built with and how a failure is worded.
|
|
1517
|
+
* @beta
|
|
1518
|
+
*/
|
|
1519
|
+
interface JestWatchPluginLoadOptions {
|
|
1520
|
+
readonly stdin: JestWatchStdin;
|
|
1521
|
+
/** Jest's `outputStream`. */
|
|
1522
|
+
readonly stdout: JestWatchOutput;
|
|
1523
|
+
readonly style: TextStyle;
|
|
1524
|
+
/** What the plugin's path is printed relative to (`process.cwd()`). */
|
|
1525
|
+
readonly cwd: string;
|
|
1526
|
+
/** `formatExecError(error, contexts[0].config, { noStackTrace: false })`. */
|
|
1527
|
+
readonly formatError: (error: unknown) => string;
|
|
1528
|
+
}
|
|
1529
|
+
/**
|
|
1530
|
+
* Loads one entry of `watchPlugins` (L199-L220): the module (jest-util's `requireOrImportModule`),
|
|
1531
|
+
* its default export constructed with `{ config, stdin, stdout }`. Any failure is Jest's
|
|
1532
|
+
* `Failed to initialize watch plugin` text.
|
|
1533
|
+
* @beta
|
|
1534
|
+
*/
|
|
1535
|
+
export declare function loadJestWatchPlugin(entry: {
|
|
1536
|
+
readonly path: string;
|
|
1537
|
+
readonly config: unknown;
|
|
1538
|
+
}, options: JestWatchPluginLoadOptions): Promise<JestWatchPlugin>;
|
|
1539
|
+
/**
|
|
1540
|
+
* The interactive snapshot mode (`SnapshotInteractiveMode`). `run` calls `onConfigChange` with the
|
|
1541
|
+
* test to run next and whether its snapshots are updated, or with `null` when the mode ends.
|
|
1542
|
+
* @beta
|
|
1543
|
+
*/
|
|
1544
|
+
export declare class JestSnapshotInteractiveMode {
|
|
1545
|
+
#private;
|
|
1546
|
+
constructor(terminal: JestWatchTerminal);
|
|
1547
|
+
isActive(): boolean;
|
|
1548
|
+
getSkippedNum(): number;
|
|
1549
|
+
/** L160-L195 */
|
|
1550
|
+
put(key: string): void;
|
|
1551
|
+
/** L197-L201 */
|
|
1552
|
+
abort(): void;
|
|
1553
|
+
/** L203-L207 */
|
|
1554
|
+
restart(): void;
|
|
1555
|
+
/** L209-L224 */
|
|
1556
|
+
updateWithResults(results: JestWatchResults): void;
|
|
1557
|
+
/** L231-L247 */
|
|
1558
|
+
run(failedSnapshotTestAssertions: readonly JestAssertionLocation[], onConfigChange: (assertion: JestAssertionLocation | null, shouldUpdateSnapshot: boolean) => unknown): void;
|
|
1559
|
+
}
|
|
1560
|
+
/**
|
|
1561
|
+
* `runJest.ts` L253-L266: `--watch` (selecting by the changed files) where no root is in a git, hg
|
|
1562
|
+
* or sl repository. Jest writes it to stderr and exits 1.
|
|
1563
|
+
* @beta
|
|
1564
|
+
*/
|
|
1565
|
+
export declare function jestWatchNoScmText(style: TextStyle): string;
|
|
1566
|
+
/**
|
|
1567
|
+
* `getNoTestFoundPassWithNoTests.ts` L10-L12: a watch run (always `passWithNoTests`) with no test
|
|
1568
|
+
* and no `-o` or `--onlyFailures` to explain why.
|
|
1569
|
+
* @beta
|
|
1570
|
+
*/
|
|
1571
|
+
export declare const JEST_NO_TESTS_PASS_TEXT: string;
|
|
1572
|
+
/**
|
|
1573
|
+
* jest-core `lib/isValidPath.ts` L11-L19: a change that starts a run is never under the coverage
|
|
1574
|
+
* directory and never a snapshot file (jest-snapshot's `isSnapshotPath`: the `.snap` extension).
|
|
1575
|
+
* @beta
|
|
1576
|
+
*/
|
|
1577
|
+
export declare function jestWatchPathIsValid(globalConfig: Pick<JestGlobalConfig, "coverageDirectory">, path: string): boolean;
|
|
1578
|
+
/**
|
|
1579
|
+
* `watch.ts` L336-L346: a run that threw, as watch mode prints it before it goes on
|
|
1580
|
+
* (`formatExecError(error, contexts[0].config, { noStackTrace: false })`).
|
|
1581
|
+
* @beta
|
|
1582
|
+
*/
|
|
1583
|
+
export declare function jestWatchRunErrorText(error: unknown, projectConfig: {
|
|
1584
|
+
readonly rootDir: string;
|
|
1585
|
+
readonly testMatch: readonly string[];
|
|
1586
|
+
}): string;
|
|
1587
|
+
/**
|
|
1588
|
+
* `activeFilters(globalConfig)`: `\nActive Filters: filename <patterns>, test name /<pattern>/`,
|
|
1589
|
+
* or `''` with no filter. The path patterns print as `TestPathPatterns.toPretty()` does, joined by `|`.
|
|
1590
|
+
* @beta
|
|
1591
|
+
*/
|
|
1592
|
+
export declare function jestActiveFilters(globalConfig: JestGlobalConfig, style: TextStyle): string;
|
|
1593
|
+
/**
|
|
1594
|
+
* `usage(globalConfig, watchPlugins)` (`watch.ts` L536-L584). `noSCM` is never set in Jest 30.5.2's
|
|
1595
|
+
* own runs (`updateGlobalConfig` is never passed it), so the `o` row depends on the mode and the
|
|
1596
|
+
* filters only.
|
|
1597
|
+
* @beta
|
|
1598
|
+
*/
|
|
1599
|
+
export declare function jestWatchUsage(globalConfig: JestGlobalConfig, plugins: readonly JestWatchPlugin[], style: TextStyle, delimiter?: string): string;
|
|
1600
|
+
/**
|
|
1601
|
+
* `showToggleUsagePrompt()` (`watch.ts` L586-L590).
|
|
1602
|
+
* @beta
|
|
1603
|
+
*/
|
|
1604
|
+
export declare function jestToggleUsagePrompt(style: TextStyle): string;
|
|
1605
|
+
/**
|
|
1606
|
+
* What a run gives back: its results (`onComplete`'s `AggregatedResult`), or `exit` when the run
|
|
1607
|
+
* ended watch mode itself (`--watch` with no repository, a failed changed-files lookup: the host has
|
|
1608
|
+
* written Jest's text).
|
|
1609
|
+
* @beta
|
|
1610
|
+
*/
|
|
1611
|
+
type JestWatchRunOutcome = {
|
|
1612
|
+
readonly kind: "complete";
|
|
1613
|
+
readonly results: JestWatchResults;
|
|
1614
|
+
} | {
|
|
1615
|
+
readonly kind: "exit";
|
|
1616
|
+
readonly code: number;
|
|
1617
|
+
};
|
|
1618
|
+
/**
|
|
1619
|
+
* What the host's run gets besides the config: the failed-tests cache `--onlyFailures` reads
|
|
1620
|
+
* (`runJest`'s `failedTestsCache`), the hooks (`jestHooks`), and the driver's `startRun`, which a
|
|
1621
|
+
* reporter may call (`reporterContext.startRun`).
|
|
1622
|
+
* @beta
|
|
1623
|
+
*/
|
|
1624
|
+
interface JestWatchRunContext {
|
|
1625
|
+
readonly failedTestsCache: JestFailedTestsCache;
|
|
1626
|
+
readonly hooks: JestHookEmitter;
|
|
1627
|
+
/** Whether any plugin listens to `shouldRunTestSuite`: when none does, the host skips the calls. */
|
|
1628
|
+
readonly usesShouldRunTestSuite: () => boolean;
|
|
1629
|
+
readonly startRun: (globalConfig: JestGlobalConfig) => void;
|
|
1630
|
+
}
|
|
1631
|
+
/**
|
|
1632
|
+
* What the driver runs on. `interactive` is jest-util's `isInteractive` (a terminal, not `dumb`,
|
|
1633
|
+
* not CI).
|
|
1634
|
+
* @beta
|
|
1635
|
+
*/
|
|
1636
|
+
interface JestWatchHost {
|
|
1637
|
+
readonly stdin: JestWatchStdin;
|
|
1638
|
+
/** Jest's `outputStream`: stdout, or stderr under `--useStderr`. */
|
|
1639
|
+
readonly stdout: JestWatchOutput;
|
|
1640
|
+
/** Where a run that threw is reported (`console.error`). */
|
|
1641
|
+
readonly stderr: JestWatchOutput;
|
|
1642
|
+
readonly interactive: boolean;
|
|
1643
|
+
readonly style: TextStyle;
|
|
1644
|
+
/** Default `process.platform`: Windows has its own screen clear and backspace. */
|
|
1645
|
+
readonly platform?: NodeJS.Platform;
|
|
1646
|
+
/** `TERM_PROGRAM` is `Apple_Terminal`: the cursor is saved with `ESC 7`. */
|
|
1647
|
+
readonly appleTerminal?: boolean;
|
|
1648
|
+
readonly resizes?: JestResizeSource;
|
|
1649
|
+
/** Runs the tests once with this config. */
|
|
1650
|
+
run(globalConfig: JestGlobalConfig, context: JestWatchRunContext): Promise<JestWatchRunOutcome>;
|
|
1651
|
+
/** Interrupts the run that is going (`testWatcher.setState({ interrupted: true })`). */
|
|
1652
|
+
interrupt(): void;
|
|
1653
|
+
/** Calls `listener` after each batch of relevant changes; returns the unsubscribe. */
|
|
1654
|
+
onFileChange(listener: () => void): () => void;
|
|
1655
|
+
/** The text of an error a run threw (`formatExecError(error, config, { noStackTrace: false })`). */
|
|
1656
|
+
formatError(error: unknown): string;
|
|
1657
|
+
/**
|
|
1658
|
+
* Every test file of each project, with its config, as a plugin's `onFileChange` hears them
|
|
1659
|
+
* (`emitFileChange`, L231-L245). Asked for only when a plugin listens; without it none is told.
|
|
1660
|
+
*/
|
|
1661
|
+
listTests?(): Promise<JestFileChange>;
|
|
1662
|
+
/** What a watch plugin's path is printed relative to when it fails to load. Default `process.cwd()`. */
|
|
1663
|
+
readonly cwd?: string;
|
|
1664
|
+
}
|
|
1665
|
+
/**
|
|
1666
|
+
* A running watch mode.
|
|
1667
|
+
* @beta
|
|
1668
|
+
*/
|
|
1669
|
+
interface JestWatch {
|
|
1670
|
+
/**
|
|
1671
|
+
* Resolves with the exit code once watch mode ends (`q`, Ctrl+C, Ctrl+D: 0). Rejects with a
|
|
1672
|
+
* `JestWatchPluginError` when a `watchPlugins` entry fails to load or conflicts, before any run.
|
|
1673
|
+
*/
|
|
1674
|
+
readonly done: Promise<number>;
|
|
1675
|
+
/** Stops reading keys and changes, leaves raw mode. Called whatever ended the session. */
|
|
1676
|
+
dispose(): void;
|
|
1677
|
+
}
|
|
1678
|
+
/**
|
|
1679
|
+
* Starts watch mode (`watch(initialGlobalConfig, ...)`): the first run starts now.
|
|
1680
|
+
*
|
|
1681
|
+
* One difference from Jest (D7): a change saved while a run is going starts one more run when it
|
|
1682
|
+
* ends, where Jest drops it (`startRun` L284-L287 returns while `isRunning`). A run that throws
|
|
1683
|
+
* also ends `isRunning`, where Jest's stays set and no run can start again.
|
|
1684
|
+
* @beta
|
|
1685
|
+
*/
|
|
1686
|
+
export declare function startJestWatch(initialGlobalConfig: JestGlobalConfig, host: JestWatchHost): JestWatch;
|
|
1687
|
+
/**
|
|
1688
|
+
* What the reader's `resolve` step returns: the run's global config and each project's config
|
|
1689
|
+
* (one, or one per entry of `projects`).
|
|
1690
|
+
* @public
|
|
1691
|
+
*/
|
|
1692
|
+
export interface JestResolvedConfig {
|
|
1693
|
+
readonly globalConfig: JestGlobalConfig;
|
|
1694
|
+
readonly configs: readonly JestProjectConfig[];
|
|
1695
|
+
/** Per config, whether it named a `cacheDirectory` (D70). Absent: none did. */
|
|
1696
|
+
readonly cacheDirectorySet?: readonly boolean[];
|
|
1697
|
+
}
|
|
1698
|
+
/**
|
|
1699
|
+
* The Jest config reader for a working directory and normalize options (`cwd` defaults to
|
|
1700
|
+
* `process.cwd()`).
|
|
1701
|
+
* @public
|
|
1702
|
+
*/
|
|
1703
|
+
export declare function createJestConfigReader(options?: NormalizeOptions): ConfigReader<JestLoadedConfig, JestResolvedConfig>;
|
|
1704
|
+
/**
|
|
1705
|
+
* The Jest config reader with the defaults: the process's working directory, no CLI values, and
|
|
1706
|
+
* Jest's own packages found through the project's Jest.
|
|
1707
|
+
* @public
|
|
1708
|
+
*/
|
|
1709
|
+
export declare const jestConfigReader: ConfigReader<JestLoadedConfig, JestResolvedConfig>;
|
|
1710
|
+
/**
|
|
1711
|
+
* The Jest 30.5 dialect with its config reader and command line: what the coordinator uses.
|
|
1712
|
+
* `jestDialect` (`.`) is the same value without them, for code that runs in a worker.
|
|
1713
|
+
* @public
|
|
1714
|
+
*/
|
|
1715
|
+
export declare const jestNodeDialect: Dialect<"jest">;
|
|
1716
|
+
export type { CollectedTextStyle, FindNodeModuleOptions, JestArgv, JestAssertionLocation, JestCliErrorCode, JestCliOption, JestCliSupport, JestConfigErrorCode, JestCoverageEnvironment, JestDisplayName, JestFileChange, JestFilter, JestGitHubActionsOptions, JestGlobalConfig, JestHookEmitter, JestHookSubscriber, JestHooks, JestInitialOptions, JestLoadedConfig, JestLoadedReporter, JestMapperEntry, JestNotifier, JestNotifierLoad, JestNotifyConfig, JestProjectConfig, JestReadConfig, JestReadConfigsOutcome, JestReadOutcome, JestReporterClass, JestReporterContext, JestReporterEntry, JestReporterEnvironment, JestReporterHostOptions, JestReporterInstance, JestReporterOnStartOptions, JestReporterPlan, JestReporterPlanOptions, JestReporterStep, JestRequireResolve, JestReservedKey, JestResizeSource, JestResolution, JestScrollOptions, JestTerminalEscapes, JestTestSuiteInfo, JestTransformEntry, JestUpdateConfigAndRun, JestUsageData, JestWatch, JestWatchConfigUpdate, JestWatchHost, JestWatchKeys, JestWatchOutput, JestWatchPlugin, JestWatchPluginErrorCode, JestWatchPluginKeys, JestWatchPluginLoadOptions, JestWatchResults, JestWatchRunContext, JestWatchRunOutcome, JestWatchStdin, JestWatchTerminal, NormalizeOptions, NormalizedJestOptions, ProcessJestResultsOptions, ReadJestConfigOptions, ValidationOutcome };
|