@provino/core 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.
- package/LICENSE +21 -0
- package/README.md +8 -2
- package/dist/index.d.ts +397 -0
- package/dist/index.js +4369 -0
- package/package.json +41 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Pixel Perfect Software
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,9 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @provino/core
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The test runtime that runs inside a worker: the collector and executor for `describe`, `test` and hooks, the test context and the current-test lookup. It never imports the loader, and every difference between Jest and Vitest in it is a policy value that a dialect supplies.
|
|
4
|
+
|
|
5
|
+
This package is a building block of [Provino](https://github.com/pixel-perfect-software/provino), a test runner that is pre-alpha and not on npm yet. The `provino` package ships every `@provino/*` package inlined in one bundle, so you install `provino`, not this package.
|
|
6
|
+
|
|
7
|
+
**Versioning:** this package is `@beta` as a whole. There is no semver promise for it before 1.0, and its API can change in any release.
|
|
8
|
+
|
|
9
|
+
[MIT](https://github.com/pixel-perfect-software/provino/blob/main/LICENSE)
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,397 @@
|
|
|
1
|
+
import { CorePolicy, CurrentTest, DefaultRetry, DescribeRetry, DescribeRetryResult, EachRowArgs, EventSink, FileTask, Frame, ImportFile, JsonValue, LazyHost, LifecycleListener, SerializedError, SuiteTask, TaskId, TaskResult, TestContext, TestTask } from "@provino/types";
|
|
2
|
+
import { BehaviourLoader } from "@provino/policy";
|
|
3
|
+
/**
|
|
4
|
+
* Stable codes for `CoreError`.
|
|
5
|
+
* @public
|
|
6
|
+
*/
|
|
7
|
+
type CoreErrorCode = "CORE_NOT_IMPLEMENTED" | "CORE_ASYNC_DESCRIBE" | "CORE_DESCRIBE_RETURN_VALUE" | "CORE_MISSING_TEST_FN" | "CORE_INVALID_EACH_TABLE" | "CORE_TODO_WITH_FN" | "CORE_NESTED_REGISTRATION" | "CORE_LATE_REGISTRATION" | "CORE_EMPTY_DESCRIBE" | "CORE_ONLY_NOT_ALLOWED" | "CORE_TIMEOUT" | "CORE_NON_PROMISE_RETURN" | "CORE_EXPECTED_FAILURE" | "CORE_TEST_CALLBACK_CONTEXT" | "CORE_INVALID_ARGUMENT" | "CORE_BUSY";
|
|
8
|
+
/**
|
|
9
|
+
* An error raised by `@provino/core`, with a stable code.
|
|
10
|
+
* @public
|
|
11
|
+
*/
|
|
12
|
+
export declare class CoreError extends Error {
|
|
13
|
+
override readonly name: string;
|
|
14
|
+
readonly code: CoreErrorCode;
|
|
15
|
+
constructor(code: CoreErrorCode, message: string, options?: ErrorOptions);
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* An `aroundEach`/`aroundAll` hook returned without calling its inner function, or timed out in its
|
|
19
|
+
* setup phase (Vitest 5.0's meaning). An error the hook throws itself is reported as it is.
|
|
20
|
+
* @public
|
|
21
|
+
*/
|
|
22
|
+
export declare class AroundHookSetupError extends Error {
|
|
23
|
+
override readonly name: string;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* An `aroundEach`/`aroundAll` hook timed out after its inner function returned (Vitest 5.0's
|
|
27
|
+
* meaning). An error the hook throws itself is reported as it is.
|
|
28
|
+
* @public
|
|
29
|
+
*/
|
|
30
|
+
export declare class AroundHookTeardownError extends Error {
|
|
31
|
+
override readonly name: string;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* An `aroundEach`/`aroundAll` hook called its inner function more than once.
|
|
35
|
+
* @public
|
|
36
|
+
*/
|
|
37
|
+
export declare class AroundHookMultipleCallsError extends Error {
|
|
38
|
+
override readonly name: string;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Turns anything thrown into plain, clone-safe data: name, message, stack, `code`, the `cause`
|
|
42
|
+
* chain and an aggregate's errors (anything error-like with an `errors` array, so an
|
|
43
|
+
* `AggregateError` from another realm counts), and the `name` and `pass` of a failed assertion's
|
|
44
|
+
* `matcherResult`. A non-error value becomes an error whose message is
|
|
45
|
+
* its string form. Never throws: a field that can't be read (a throwing getter, a revoked proxy)
|
|
46
|
+
* is left out.
|
|
47
|
+
* @public
|
|
48
|
+
*/
|
|
49
|
+
export declare function serializeError(value: unknown): SerializedError;
|
|
50
|
+
/**
|
|
51
|
+
* Any function or class: the API function `captureStackTrace` cuts the user's frames at, and what
|
|
52
|
+
* a test or describe may be named after.
|
|
53
|
+
*/
|
|
54
|
+
type StackMarker = Function;
|
|
55
|
+
/**
|
|
56
|
+
* Decides whether a failed attempt is retried: a `RegExp` is tested against the last error's
|
|
57
|
+
* message, a function is called with the error (Vitest's `retry.condition`). Under the policy's
|
|
58
|
+
* `retry.functionCondition: 'ignore-warn'` (Vitest's dialect) a function is not called: Vitest
|
|
59
|
+
* 5.0.5 never calls it, so every failure retries.
|
|
60
|
+
* @public
|
|
61
|
+
*/
|
|
62
|
+
type RetryCondition = RegExp | ((error: SerializedError) => boolean);
|
|
63
|
+
/**
|
|
64
|
+
* The `retry` option: a count, or the count with what Vitest's `retry` object adds. `delay` is the
|
|
65
|
+
* milliseconds to wait before each retry; `condition` limits which failures retry.
|
|
66
|
+
* @public
|
|
67
|
+
*/
|
|
68
|
+
type RetryOption = number | {
|
|
69
|
+
readonly count?: number;
|
|
70
|
+
readonly delay?: number;
|
|
71
|
+
readonly condition?: RetryCondition;
|
|
72
|
+
};
|
|
73
|
+
/**
|
|
74
|
+
* The options tests and describes both take as their second argument (Vitest's options object).
|
|
75
|
+
* @public
|
|
76
|
+
*/
|
|
77
|
+
interface CommonOptions {
|
|
78
|
+
readonly timeout?: number;
|
|
79
|
+
readonly retry?: RetryOption;
|
|
80
|
+
readonly repeats?: number;
|
|
81
|
+
readonly concurrent?: boolean;
|
|
82
|
+
readonly skip?: boolean;
|
|
83
|
+
readonly only?: boolean;
|
|
84
|
+
readonly todo?: boolean;
|
|
85
|
+
readonly tags?: string | readonly string[];
|
|
86
|
+
readonly meta?: Readonly<Record<string, JsonValue>>;
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Options a test takes as its second argument.
|
|
90
|
+
* @public
|
|
91
|
+
*/
|
|
92
|
+
interface TestOptions extends CommonOptions {
|
|
93
|
+
readonly fails?: boolean;
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* Options a describe takes as its second argument; its tests and nested describes inherit them,
|
|
97
|
+
* `only`, `skip` and `todo` included.
|
|
98
|
+
* @public
|
|
99
|
+
*/
|
|
100
|
+
interface SuiteOptions extends CommonOptions {
|
|
101
|
+
readonly shuffle?: boolean;
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* A test body. Under `firstArg: 'context'` it receives the test context; the Jest dialect types
|
|
105
|
+
* its own `done` form.
|
|
106
|
+
* @public
|
|
107
|
+
*/
|
|
108
|
+
type TestFunction = (context: TestContext) => unknown;
|
|
109
|
+
/**
|
|
110
|
+
* `.each` over rows (array rows spread into arguments) or a tagged-template table.
|
|
111
|
+
* @public
|
|
112
|
+
*/
|
|
113
|
+
interface EachFunction<Register> {
|
|
114
|
+
(table: TemplateStringsArray, ...values: readonly unknown[]): Register extends "test" ? (name: string, fn: (row: Readonly<Record<string, unknown>>) => unknown, timeoutMs?: number) => void : (name: string, body: (row: Readonly<Record<string, unknown>>) => unknown, timeoutMs?: number) => void;
|
|
115
|
+
<const Row>(rows: readonly Row[]): Register extends "test" ? (name: string, fn: (...args: EachRowArgs<Row>) => unknown, timeoutMs?: number) => void : (name: string, body: (...args: EachRowArgs<Row>) => unknown, timeoutMs?: number) => void;
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* `.for` over rows: the row is passed unspread (and, for tests, the context second).
|
|
119
|
+
* @public
|
|
120
|
+
*/
|
|
121
|
+
type ForFunction<Register> = <const Row>(rows: readonly Row[]) => Register extends "test" ? (name: string, fn: (row: Row, context: TestContext) => unknown) => void : (name: string, body: (row: Row) => unknown) => void;
|
|
122
|
+
/**
|
|
123
|
+
* `test`/`it`: declares a test. Chain modifiers (`test.only.concurrent`), or pass options second.
|
|
124
|
+
* @public
|
|
125
|
+
*/
|
|
126
|
+
interface TestApi {
|
|
127
|
+
(name: string | StackMarker, fn?: TestFunction, timeoutMs?: number): void;
|
|
128
|
+
(name: string | StackMarker, options: TestOptions, fn?: TestFunction): void;
|
|
129
|
+
readonly only: TestApi;
|
|
130
|
+
readonly skip: TestApi;
|
|
131
|
+
readonly todo: TestApi;
|
|
132
|
+
readonly concurrent: TestApi;
|
|
133
|
+
/** Passes when the body fails (Vitest's name). */
|
|
134
|
+
readonly fails: TestApi;
|
|
135
|
+
/** Passes when the body fails (Jest's name). */
|
|
136
|
+
readonly failing: TestApi;
|
|
137
|
+
skipIf(condition: unknown): TestApi;
|
|
138
|
+
runIf(condition: unknown): TestApi;
|
|
139
|
+
readonly each: EachFunction<"test">;
|
|
140
|
+
readonly for: ForFunction<"test">;
|
|
141
|
+
}
|
|
142
|
+
/**
|
|
143
|
+
* A describe body. It may be async only where the policy awaits it (`asyncDescribe: 'await'`).
|
|
144
|
+
* @public
|
|
145
|
+
*/
|
|
146
|
+
type SuiteBody = () => unknown;
|
|
147
|
+
/**
|
|
148
|
+
* `describe`/`suite`: declares a block. Chain modifiers, or pass options second. A timeout third
|
|
149
|
+
* is `{ timeout }`: the block's tests inherit it.
|
|
150
|
+
* @public
|
|
151
|
+
*/
|
|
152
|
+
interface SuiteApi {
|
|
153
|
+
(name: string | StackMarker, body?: SuiteBody, timeoutMs?: number): void;
|
|
154
|
+
(name: string | StackMarker, options: SuiteOptions, body?: SuiteBody): void;
|
|
155
|
+
readonly only: SuiteApi;
|
|
156
|
+
readonly skip: SuiteApi;
|
|
157
|
+
readonly todo: SuiteApi;
|
|
158
|
+
readonly concurrent: SuiteApi;
|
|
159
|
+
skipIf(condition: unknown): SuiteApi;
|
|
160
|
+
runIf(condition: unknown): SuiteApi;
|
|
161
|
+
readonly each: EachFunction<"suite">;
|
|
162
|
+
readonly for: ForFunction<"suite">;
|
|
163
|
+
}
|
|
164
|
+
/**
|
|
165
|
+
* The task a suite hook receives: the suite (or file) it's declared on, or the test's innermost
|
|
166
|
+
* suite for each-hooks.
|
|
167
|
+
* @public
|
|
168
|
+
*/
|
|
169
|
+
type HookSuite = SuiteTask | FileTask;
|
|
170
|
+
/**
|
|
171
|
+
* The global functions a runtime provides. Dialects re-export them under their names.
|
|
172
|
+
* @public
|
|
173
|
+
*/
|
|
174
|
+
interface RuntimeApi {
|
|
175
|
+
readonly describe: SuiteApi;
|
|
176
|
+
readonly suite: SuiteApi;
|
|
177
|
+
readonly test: TestApi;
|
|
178
|
+
readonly it: TestApi;
|
|
179
|
+
beforeAll(fn: (suite: HookSuite) => unknown, timeoutMs?: number): void;
|
|
180
|
+
afterAll(fn: (suite: HookSuite) => unknown, timeoutMs?: number): void;
|
|
181
|
+
beforeEach(fn: (context: TestContext, suite: HookSuite) => unknown, timeoutMs?: number): void;
|
|
182
|
+
afterEach(fn: (context: TestContext, suite: HookSuite) => unknown, timeoutMs?: number): void;
|
|
183
|
+
/** Wraps each test's hooks and body; call `runTest` exactly once. `suite` is the test's innermost. */
|
|
184
|
+
aroundEach(fn: (runTest: () => Promise<void>, context: TestContext, suite: HookSuite) => unknown, timeoutMs?: number): void;
|
|
185
|
+
/** Wraps a suite's hooks and tests; call `runSuite` exactly once. */
|
|
186
|
+
aroundAll(fn: (runSuite: () => Promise<void>, suite: HookSuite) => unknown, timeoutMs?: number): void;
|
|
187
|
+
/** Runs after the current test (and its teardowns), last registered first. */
|
|
188
|
+
onTestFinished(fn: (context: TestContext) => unknown, timeoutMs?: number): void;
|
|
189
|
+
/** Runs after the current test when it failed. */
|
|
190
|
+
onTestFailed(fn: (context: TestContext) => unknown, timeoutMs?: number): void;
|
|
191
|
+
}
|
|
192
|
+
/**
|
|
193
|
+
* The current-test lookup, plus `running()`: the sync fast path.
|
|
194
|
+
* @public
|
|
195
|
+
*/
|
|
196
|
+
interface CurrentTestService extends CurrentTest {
|
|
197
|
+
/**
|
|
198
|
+
* The frame the executor is running right now, without an AsyncLocalStorage read. Only set
|
|
199
|
+
* while tests run one at a time (`maxConcurrency` 1 or no concurrent group); `undefined`
|
|
200
|
+
* otherwise. Code that needs the test that *started* some work must use `get()`.
|
|
201
|
+
*/
|
|
202
|
+
running(): Frame | undefined;
|
|
203
|
+
}
|
|
204
|
+
/**
|
|
205
|
+
* The worker's one current-test lookup. Mocks and timers (attribution), lazy values and expect
|
|
206
|
+
* state read it.
|
|
207
|
+
* @public
|
|
208
|
+
*/
|
|
209
|
+
export declare const currentTest: CurrentTestService;
|
|
210
|
+
/**
|
|
211
|
+
* The part of `process` the listeners need, so an `EventEmitter` stands in for it in tests.
|
|
212
|
+
*/
|
|
213
|
+
type ProcessLike = Pick<NodeJS.EventEmitter, "on" | "removeListener" | "removeAllListeners" | "rawListeners">;
|
|
214
|
+
/**
|
|
215
|
+
* The timer functions deadlines use.
|
|
216
|
+
* @public
|
|
217
|
+
*/
|
|
218
|
+
interface RealTimers {
|
|
219
|
+
readonly setTimeout: typeof globalThis.setTimeout;
|
|
220
|
+
readonly clearTimeout: typeof globalThis.clearTimeout;
|
|
221
|
+
}
|
|
222
|
+
/** What a try-task listener is told about the attempt it brackets. */
|
|
223
|
+
interface TryTaskInfo {
|
|
224
|
+
readonly test: TestTask;
|
|
225
|
+
/**
|
|
226
|
+
* The attempt's test context, the same object its hooks and body get. A getter, built on the
|
|
227
|
+
* first read: it is not an own key, so a spread of the info or `Object.keys` does not carry it.
|
|
228
|
+
*/
|
|
229
|
+
readonly ctx: TestContext;
|
|
230
|
+
readonly attempt: number;
|
|
231
|
+
readonly repeat: number;
|
|
232
|
+
/** `false` in `onBeforeTryTask`; in `onAfterTryTask`, whether the attempt has failed so far. */
|
|
233
|
+
readonly failed: boolean;
|
|
234
|
+
/**
|
|
235
|
+
* Adds an error to the attempt, as one of its own: a listener with several (two soft failures)
|
|
236
|
+
* reports each, where a thrown value is one error.
|
|
237
|
+
*/
|
|
238
|
+
fail(error: unknown): void;
|
|
239
|
+
}
|
|
240
|
+
/** Called around an attempt's hooks and body, in the attempt's own async context. */
|
|
241
|
+
type TryTaskListener = (info: TryTaskInfo) => void | Promise<void>;
|
|
242
|
+
/**
|
|
243
|
+
* The name of the frame through which core calls a function a file registered (a describe body, a
|
|
244
|
+
* test, a hook, a teardown, a test callback): the first of Provino's frames outward from that
|
|
245
|
+
* function on any stack its synchronous part captures. Not on a stack after an `await` in it.
|
|
246
|
+
* @public
|
|
247
|
+
*/
|
|
248
|
+
export declare const USER_CALL_FRAME = "provinoUserCall";
|
|
249
|
+
/**
|
|
250
|
+
* What a runtime is built from.
|
|
251
|
+
* @public
|
|
252
|
+
*/
|
|
253
|
+
interface RuntimeOptions {
|
|
254
|
+
readonly policy: CorePolicy;
|
|
255
|
+
/** Loads `formatEachTitle`, `formatValue` and `orderHooks` (the worker's one loader). */
|
|
256
|
+
readonly behaviours: BehaviourLoader;
|
|
257
|
+
readonly sink: EventSink;
|
|
258
|
+
/** Loads a test file; the worker passes the loader's import. */
|
|
259
|
+
readonly importFile: ImportFile;
|
|
260
|
+
/** Test paths are reported relative to this directory, in POSIX form. */
|
|
261
|
+
readonly rootDir: string;
|
|
262
|
+
/** Part of every task id. Default `''`. */
|
|
263
|
+
readonly projectName?: string;
|
|
264
|
+
/** Whether this is a CI run (`allowOnly: 'not-in-ci'`). Default `false`. */
|
|
265
|
+
readonly ci?: boolean;
|
|
266
|
+
/** Whether diffs print in full (Jest's `--expand`), as `policy.shapeTestError` is told. Default `false`. */
|
|
267
|
+
readonly expand?: boolean;
|
|
268
|
+
/** Capture task and hook locations. Default `true`. */
|
|
269
|
+
readonly locations?: boolean;
|
|
270
|
+
/** `-t`: tests whose joined full name doesn't match are skipped. */
|
|
271
|
+
readonly testNamePattern?: string | RegExp;
|
|
272
|
+
/** Only these test ids run. */
|
|
273
|
+
readonly testIds?: readonly string[];
|
|
274
|
+
/** The timers deadlines use. Default: those global when core loaded. */
|
|
275
|
+
readonly realTimers?: RealTimers;
|
|
276
|
+
/** A monotonic clock in ms. Default `performance.now`. */
|
|
277
|
+
readonly now?: () => number;
|
|
278
|
+
}
|
|
279
|
+
/**
|
|
280
|
+
* What applies to one file only.
|
|
281
|
+
* @public
|
|
282
|
+
*/
|
|
283
|
+
interface RunFileOptions {
|
|
284
|
+
/** Only tests (or suites) on these lines run (Vitest's `file:line`). */
|
|
285
|
+
readonly lines?: readonly number[];
|
|
286
|
+
/**
|
|
287
|
+
* `-t` for this file only: replaces the runtime's `testNamePattern`. A string that is not a valid
|
|
288
|
+
* regular expression fails the file (`CORE_INVALID_ARGUMENT`, the `SyntaxError` as its cause)
|
|
289
|
+
* before it is imported. So does a value that is neither a string nor a `RegExp`, and a `testIds`
|
|
290
|
+
* or `lines` that is not an array (the error names the option): `FileJob` crosses a link
|
|
291
|
+
* unvalidated.
|
|
292
|
+
*/
|
|
293
|
+
readonly testNamePattern?: string | RegExp;
|
|
294
|
+
/** Only these test ids run in this file: replaces the runtime's `testIds`. */
|
|
295
|
+
readonly testIds?: readonly string[];
|
|
296
|
+
/**
|
|
297
|
+
* The file's id, assigned by the coordinator (D23; `FileJob.fileId`). Every event of the file and
|
|
298
|
+
* every task id in it derives from this. Absent (a runtime used on its own), core computes it
|
|
299
|
+
* from the project name and the file's path relative to the root. A value that is not a
|
|
300
|
+
* non-empty string fails the file (`CORE_INVALID_ARGUMENT`), and its events then carry the
|
|
301
|
+
* computed id.
|
|
302
|
+
*/
|
|
303
|
+
readonly fileId?: TaskId;
|
|
304
|
+
/**
|
|
305
|
+
* Collect the file and report each test's final mode without running anything: no hook and no
|
|
306
|
+
* test body runs, and each test ends once as `queued` (it would run), `skip` or `todo`. Only
|
|
307
|
+
* `true` is accepted; any other value fails the file (`CORE_INVALID_ARGUMENT`).
|
|
308
|
+
*/
|
|
309
|
+
readonly collectOnly?: true;
|
|
310
|
+
/**
|
|
311
|
+
* Shuffle every suite of this file with a generator built from this seed (`CorePolicy.shuffle`:
|
|
312
|
+
* Jest's `--randomize`). It must be a number, taken as it is (the factory decides what a fraction
|
|
313
|
+
* means), and the policy must have a `shuffle`; otherwise the file fails (`CORE_INVALID_ARGUMENT`)
|
|
314
|
+
* before it is imported.
|
|
315
|
+
*/
|
|
316
|
+
readonly shuffleSeed?: number;
|
|
317
|
+
/**
|
|
318
|
+
* Receives this file's lifecycle events (an environment's `onTestEvent`, Jest's
|
|
319
|
+
* `handleTestEvent`): `file-setup` before the file loads, the definitions as it registers them,
|
|
320
|
+
* the run's events, and `file-teardown` after a collected file ran. The run waits for what the
|
|
321
|
+
* listener returns at each run event; with none, nothing is built or awaited. It must be a
|
|
322
|
+
* function: anything else fails the file (`CORE_INVALID_ARGUMENT`) before it is imported.
|
|
323
|
+
*/
|
|
324
|
+
readonly lifecycle?: LifecycleListener;
|
|
325
|
+
}
|
|
326
|
+
/**
|
|
327
|
+
* A worker's test runtime.
|
|
328
|
+
* @public
|
|
329
|
+
*/
|
|
330
|
+
interface Runtime {
|
|
331
|
+
/** The global functions (`describe`, `test`, hooks, …) a dialect re-exports. */
|
|
332
|
+
readonly api: RuntimeApi;
|
|
333
|
+
readonly currentTest: CurrentTestService;
|
|
334
|
+
/** What `@provino/lazy` builds on. */
|
|
335
|
+
readonly lazyHost: LazyHost;
|
|
336
|
+
/**
|
|
337
|
+
* Collects and runs one test file; resolves with the file's result, whatever its tests do.
|
|
338
|
+
* Rejects with `CORE_BUSY` while another file of this runtime is still collecting or running.
|
|
339
|
+
*/
|
|
340
|
+
runFile(path: string, options?: RunFileOptions): Promise<TaskResult>;
|
|
341
|
+
/**
|
|
342
|
+
* Registers a function that runs at the start of every attempt of every test (before its first
|
|
343
|
+
* `beforeEach`, in the attempt's own async context): the hook point for work the runner owes the
|
|
344
|
+
* test, such as the mock cleanup between tests (T4.10). A function that throws fails the
|
|
345
|
+
* attempt. Returns the function that removes it.
|
|
346
|
+
*/
|
|
347
|
+
onBeforeTryTask(listener: TryTaskListener): () => void;
|
|
348
|
+
/**
|
|
349
|
+
* Registers a function that runs at the end of every attempt (after its last `afterEach` and
|
|
350
|
+
* teardowns, before `onTestFinished`), told whether the attempt has failed: where the
|
|
351
|
+
* assertion-count checks live (T7.8). A function that throws fails the attempt.
|
|
352
|
+
*/
|
|
353
|
+
onAfterTryTask(listener: TryTaskListener): () => void;
|
|
354
|
+
/**
|
|
355
|
+
* Listens on `target` (default: the process) for uncaught exceptions and rejections with no
|
|
356
|
+
* handler, and charges each as `errors.lateErrors` says (T5.11), with the listeners placed as
|
|
357
|
+
* `errors.processListeners` says. The worker calls it once; returns the function that removes
|
|
358
|
+
* the listeners.
|
|
359
|
+
*/
|
|
360
|
+
captureProcessErrors(target?: ProcessLike): () => void;
|
|
361
|
+
/**
|
|
362
|
+
* Sets the timeout that a test or hook with none of its own gets, in place of the policy's, until
|
|
363
|
+
* the file that is running ends (Jest's `jest.setTimeout`). It covers the tests declared before
|
|
364
|
+
* the call too, and is read once when the run starts, after collection (circus copies it into
|
|
365
|
+
* its state at `run_start`): a call during collection or in `setupFilesAfterEnv` takes effect, one
|
|
366
|
+
* made inside a hook or a test body does not. `undefined` leaves the policy's in place. A dialect
|
|
367
|
+
* maps its own odd values (Jest's `0`, `NaN` and negative numbers) before it calls.
|
|
368
|
+
*/
|
|
369
|
+
setDefaultTimeout(ms: number | undefined): void;
|
|
370
|
+
/**
|
|
371
|
+
* Sets the retry that every test with no `retry` of its own gets, until the file that is running
|
|
372
|
+
* ends (Jest's `jest.retryTimes`): how many retries, how long to wait before each, whether they
|
|
373
|
+
* run at once (`immediate`, whatever `retry.timing` says) and whether the errors of the attempts
|
|
374
|
+
* that were retried are kept on the result (`logErrors`). It replaces any earlier call whole, as
|
|
375
|
+
* Jest's globals are overwritten. A suite reads it when it starts running, after its `beforeAll`
|
|
376
|
+
* hooks, and holds it for its own tests: a call from a hook or a test changes the suites that
|
|
377
|
+
* start after it, not the running one. `undefined` clears it. A dialect maps its own odd values
|
|
378
|
+
* before it calls; a count below 1 or that is not a finite number is no retry.
|
|
379
|
+
*/
|
|
380
|
+
setDefaultRetry(retry: DefaultRetry | undefined): void;
|
|
381
|
+
/**
|
|
382
|
+
* Sets the retry of the describe block being collected (the file's root at its top level): when a
|
|
383
|
+
* test below fails, the block's hooks and every test below run again (Jest's `entireDescribe`).
|
|
384
|
+
* A second call for the same block replaces the first. `started` when no block is open: the
|
|
385
|
+
* file's run has begun, and a retry can no longer be set.
|
|
386
|
+
*/
|
|
387
|
+
setDescribeRetry(retry: DescribeRetry): DescribeRetryResult;
|
|
388
|
+
/** Runs the worker teardowns (last first); rejects with an `AggregateError` if any failed. */
|
|
389
|
+
dispose(): Promise<void>;
|
|
390
|
+
}
|
|
391
|
+
/**
|
|
392
|
+
* Builds a runtime. Async because it loads the policy's behaviour functions first, so
|
|
393
|
+
* registration stays synchronous.
|
|
394
|
+
* @public
|
|
395
|
+
*/
|
|
396
|
+
export declare function createRuntime(options: RuntimeOptions): Promise<Runtime>;
|
|
397
|
+
export type { CommonOptions, CoreErrorCode, CurrentTestService, EachFunction, ForFunction, HookSuite, ProcessLike, RealTimers, RetryCondition, RetryOption, RunFileOptions, Runtime, RuntimeApi, RuntimeOptions, SuiteApi, SuiteBody, SuiteOptions, TestApi, TestFunction, TestOptions, TryTaskInfo, TryTaskListener };
|