@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 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
- # Temporary Holding Version
1
+ # @provino/core
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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)
@@ -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 };