@provino/dialect-jest 0.0.0-stage → 0.1.0-rc.0

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.
@@ -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 };