@provino/expect 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/expect
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 `expect` engine: the front end, the per-test matcher state and the global matcher slot. A dialect supplies the matchers, the asymmetric matchers and every message the engine prints.
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,322 @@
1
+ import { equals } from "@jest/expect-utils";
2
+ import { AsymmetricMatcherLike, CurrentTest, EqualityTester, ExpectMessages, ExpectPolicy, ExpectStatic, ExpectTable, Matcher, MatcherResult, MatcherSet, MatcherState, PromiseVoice } from "@provino/types";
3
+ /**
4
+ * A matcher's `this`: the current state (copied, as Jest spreads it), equality, the dialect's
5
+ * `utils`, and how the call was made.
6
+ * @public
7
+ */
8
+ interface MatcherContext extends Readonly<MatcherState> {
9
+ readonly isNot: boolean;
10
+ /** Absent in an asymmetric matcher's context, as in Jest. */
11
+ readonly promise?: PromiseVoice;
12
+ readonly equals: typeof equals;
13
+ readonly customTesters: readonly EqualityTester[];
14
+ /** The dialect's helpers (Jest: `jest-matcher-utils` plus `iterableEquality`/`subsetEquality`). */
15
+ readonly utils: object;
16
+ /** The error the failure will reuse, under `.resolves`/`.rejects`. */
17
+ readonly error?: Error | undefined;
18
+ /** Records a failure instead of throwing it (snapshot matchers). */
19
+ dontThrow(): void;
20
+ }
21
+ /**
22
+ * The base every asymmetric matcher extends.
23
+ * @public
24
+ */
25
+ export declare abstract class AsymmetricMatcher<T> implements AsymmetricMatcherLike {
26
+ readonly $$typeof: symbol;
27
+ protected readonly sample: T;
28
+ protected readonly inverse: boolean;
29
+ constructor(sample: T, inverse?: boolean);
30
+ /**
31
+ * A matcher context like the one a matcher gets (Jest's `getMatcherContext`): the current
32
+ * state, the realm's equality testers and `utils`, and `isNot` from `inverse`. It reads the
33
+ * slot, so it works under whichever engine installed it.
34
+ */
35
+ protected getMatcherContext(): MatcherContext;
36
+ abstract asymmetricMatch(other: unknown, customTesters?: readonly EqualityTester[]): boolean;
37
+ abstract toString(): string;
38
+ getExpectedType?(): string;
39
+ toAsymmetricMatcher?(): string;
40
+ }
41
+ /**
42
+ * The stack of a matcher's call, its first frame the user's call, taken when the thunk runs (the
43
+ * state calls it only when it writes an inline snapshot, inside the same `match` call). Under
44
+ * `.resolves`/`.rejects` it is the error the engine made at the call (Jest's `context.error`).
45
+ * Otherwise it is Jest's rule (State.ts `_addSnapshot`, utils.ts
46
+ * `removeLinesBeforeExternalMatcherTrap`): the lines after the innermost matcher call, past the
47
+ * engine's frames, which Jest's `getTopFrame` passes over in `node_modules` and which, run from
48
+ * source, are outside it here. Jest registers its own snapshot matchers with `expect.extend`, so
49
+ * they run inside a trap as a custom one does; Provino's are built-ins with no trap, so for them
50
+ * the innermost call is the engine's `throwingMatcher`. Either way a matcher called through
51
+ * `expect` inside a custom matcher writes into that matcher's body
52
+ * (`ecosystem/custom-snapshot-inline-nested`).
53
+ * @public
54
+ */
55
+ export declare function matcherCallStack(error: Error | undefined): () => string;
56
+ /**
57
+ * Options for `createStateSource`.
58
+ * @public
59
+ */
60
+ interface StateSourceOptions {
61
+ /** Joins a test's full name into `currentTestName`: the core policy's `nameSeparator`. */
62
+ readonly nameSeparator: string;
63
+ /** Whether diffs show every line: `ExpectPolicy.expand` (Jest sets it once, from `--expand`). */
64
+ readonly expand: boolean;
65
+ /**
66
+ * `ExpectPolicy.outsideTestCounts`, `'drop'` when left out. Under `'next-test'` the counters
67
+ * made outside a test go to one attempt: in a sequential run the next test to end, as Jest's
68
+ * one state carries them. Under concurrency, the first attempt that asserts, or that ends with
69
+ * none having asserted (Jest shares one state; the declared improvement).
70
+ */
71
+ readonly outsideTestCounts?: "drop" | "next-test";
72
+ }
73
+ /**
74
+ * Where the engine finds the matcher state of the code that is running.
75
+ * @public
76
+ */
77
+ interface StateSource {
78
+ /** The running test attempt's state, or the file's when no test is running. */
79
+ current(): MatcherState;
80
+ /** The file's state. */
81
+ file(): MatcherState;
82
+ /**
83
+ * Starts a file: a fresh file state with `testPath`, and the last file's test states dropped.
84
+ */
85
+ startFile(testPath: string | undefined): void;
86
+ /**
87
+ * The state of one run of a test (its attempt and repeat, as `test-attempt-end` reports them),
88
+ * if that run read or counted any. A pure lookup: it moves nothing.
89
+ */
90
+ stateOf(testId: string, run: TestRun): MatcherState | undefined;
91
+ /**
92
+ * Ends a run: its state, made now when the run made none and (under `outsideTestCounts:
93
+ * 'next-test'`) the file state holds counts to take, else what `stateOf` gives. The end-of-test
94
+ * check calls it once, where Jest's `test_done` reads the counters.
95
+ */
96
+ settle(testId: string, run: TestRun): MatcherState | undefined;
97
+ }
98
+ /**
99
+ * Which run of a test: the retry attempt and the repeat, both from 0.
100
+ * @public
101
+ */
102
+ interface TestRun {
103
+ readonly attempt: number;
104
+ readonly repeat: number;
105
+ }
106
+ /**
107
+ * Builds the state source from the worker's current-test lookup (core's `currentTest`). Typed by
108
+ * `@provino/types`' `CurrentTest`, so the engine never imports core (Track 7 §Per-test state).
109
+ * @public
110
+ */
111
+ export declare function createStateSource(currentTest: CurrentTest, options: StateSourceOptions): StateSource;
112
+ /**
113
+ * What the end-of-test check reads from the policy.
114
+ * @public
115
+ */
116
+ interface EndOfTestOptions {
117
+ readonly source: StateSource;
118
+ /** The table's messages (`ExpectTable.messages`). */
119
+ readonly messages: ExpectMessages;
120
+ /** `ExpectPolicy.requireAssertions`. */
121
+ readonly policy: Pick<ExpectPolicy, "requireAssertions">;
122
+ /**
123
+ * `CorePolicy.errors.hasAssertionsWhenFailed`, passed in because this package reads only its own
124
+ * slice. `skip` (Jest): on an attempt that already failed, the count errors are left out when
125
+ * `expect.hasAssertions()` was called, and `requireAssertions` adds none. `check`: they are added
126
+ * either way.
127
+ */
128
+ readonly hasAssertionsWhenFailed: "skip" | "check";
129
+ }
130
+ /**
131
+ * The attempt that ended: what core's `TryTaskInfo` carries, without importing core.
132
+ * @public
133
+ */
134
+ interface EndOfTestAttempt extends TestRun {
135
+ readonly test: {
136
+ readonly id: string;
137
+ };
138
+ /** Whether the attempt had already failed when the check runs. */
139
+ readonly failed: boolean;
140
+ }
141
+ /**
142
+ * Checks one attempt's state and returns its new errors, in the order to report them. Empty when
143
+ * the attempt owes nothing.
144
+ * @public
145
+ */
146
+ type EndOfTest = (attempt: EndOfTestAttempt) => readonly Error[];
147
+ /**
148
+ * Builds the end-of-test check.
149
+ * @public
150
+ */
151
+ export declare function createEndOfTest(options: EndOfTestOptions): EndOfTest;
152
+ /**
153
+ * The testers an `ExpectPolicy.equality` asks for, in the order they go ahead of the others.
154
+ * Jest's values ask for none.
155
+ * @public
156
+ */
157
+ export declare function equalityTesters(equality: ExpectPolicy["equality"]): EqualityTester[];
158
+ /**
159
+ * Stable codes for `ExpectError`.
160
+ * @public
161
+ */
162
+ type ExpectErrorCode = "EXPECT_SLOT_TAKEN" | "EXPECT_NOT_IMPLEMENTED" | "EXPECT_NO_MATCHER_TABLE" | "EXPECT_OUTSIDE_TEST" | "EXPECT_POLL_UNSUPPORTED" | "EXPECT_INVALID_ARGUMENT";
163
+ /**
164
+ * An error from the engine itself, never from an assertion.
165
+ * @public
166
+ */
167
+ export declare class ExpectError extends Error {
168
+ readonly code: ExpectErrorCode;
169
+ constructor(code: ExpectErrorCode, message: string);
170
+ }
171
+ /**
172
+ * The clocks `expect.poll` waits with. Everything is optional: it falls back to the real timers
173
+ * that were on `globalThis` when the engine was built, and to no fake clock.
174
+ * @public
175
+ */
176
+ interface PollTimers {
177
+ /** Starts a timer. Default: the real `setTimeout`. */
178
+ readonly setTimeout?: (callback: () => void, ms: number) => unknown;
179
+ /** Cancels a timer `setTimeout` returned. Default: the real `clearTimeout`. */
180
+ readonly clearTimeout?: (handle: unknown) => void;
181
+ /**
182
+ * Moves the file's fake clock forward by `ms`; returns `undefined` when none is installed. The
183
+ * poll calls it after each wait between tries, as Vitest does.
184
+ */
185
+ readonly advance?: (ms: number) => Promise<void> | undefined;
186
+ }
187
+ /**
188
+ * The slot's key. Both runners use it (Track 7 F3).
189
+ * @public
190
+ */
191
+ export declare const MATCHERS_SLOT: unique symbol;
192
+ /**
193
+ * The matchers, equality testers and matcher `utils` of one `expect`. The slot exposes the same
194
+ * objects, so `expect.extend` and code that reads the slot always agree.
195
+ * @public
196
+ */
197
+ interface MatcherRegistry {
198
+ readonly matchers: Record<string, Matcher>;
199
+ readonly customEqualityTesters: EqualityTester[];
200
+ /** `this.utils`; the dialect's table sets it when `createExpect` runs. */
201
+ utils: object;
202
+ }
203
+ /**
204
+ * An empty registry, made before the slot so the slot exists before any matcher module loads.
205
+ * @public
206
+ */
207
+ export declare function createMatcherRegistry(): MatcherRegistry;
208
+ /**
209
+ * A registry's contents at one moment, to go back to.
210
+ * @beta
211
+ */
212
+ interface RegistrySnapshot {
213
+ /**
214
+ * Puts the registry back as it was when the snapshot was taken: matchers added since are
215
+ * deleted, any it replaced are put back, and `customEqualityTesters` is reset to its contents
216
+ * then. The registry's objects stay the same ones, so the slot keeps sharing them. When the
217
+ * snapshot was given the `expect` function, the own properties of `expect` and of `expect.not`
218
+ * go back too (the asymmetric forms `expect.extend` defines). It can be called again after each
219
+ * file.
220
+ */
221
+ restore(): void;
222
+ }
223
+ /**
224
+ * Remembers what `registry` holds now, and, when `expect` is given, the own properties of `expect`
225
+ * and of `expect.not`. The worker takes one after `createExpect` has registered the dialect's
226
+ * matchers (an earlier one would restore them away), and restores it after each file when the
227
+ * environment is file-scoped, as Jest gives each file a fresh `expect`.
228
+ *
229
+ * `expect.extend` puts a custom matcher's asymmetric form (`expect.toBeEven()`) on `expect` and on
230
+ * `expect.not`, outside the registry; pass `expect` so those are undone too.
231
+ * @beta
232
+ */
233
+ export declare function snapshotRegistry(registry: MatcherRegistry, expect?: ExpectStatic): RegistrySnapshot;
234
+ /**
235
+ * The installed slot.
236
+ * @public
237
+ */
238
+ interface SlotHandle {
239
+ /** Removes the slot, if it is still this one. */
240
+ uninstall(): void;
241
+ }
242
+ /**
243
+ * What the slot holds, as third-party code reads it.
244
+ * @public
245
+ */
246
+ interface MatchersSlot {
247
+ readonly matchers: Record<string, Matcher>;
248
+ readonly customEqualityTesters: EqualityTester[];
249
+ readonly state: MatcherState;
250
+ /**
251
+ * `this.utils`, for the asymmetric base. Ours only, and not enumerable, so the slot's own keys
252
+ * stay Jest's three.
253
+ */
254
+ readonly utils?: object;
255
+ }
256
+ /**
257
+ * Installs the slot on `globalThis`. Throws `EXPECT_SLOT_TAKEN` if another one is there: a
258
+ * non-configurable one means Jest's `expect` loaded first in this realm, which the worker must
259
+ * prevent (the slot comes before any matcher module).
260
+ * @public
261
+ */
262
+ export declare function installMatchersSlot(source: StateSource, registry: MatcherRegistry): SlotHandle;
263
+ /**
264
+ * The error a failed assertion throws under `errorShape: 'matcher-result'`: an `Error` whose text
265
+ * is in `message`, with the matcher's result attached (Jest's `JestAssertionError`). Its `name`
266
+ * is `Error`, so reports print `Error: …` as Jest's do.
267
+ * @public
268
+ */
269
+ export declare class MatcherResultError extends Error {
270
+ matcherResult: (Omit<MatcherResult, "message"> & {
271
+ readonly message: string;
272
+ }) | undefined;
273
+ }
274
+ /**
275
+ * Whether the engine holds an unawaited `.resolves`/`.rejects`/`expect.poll` against the test:
276
+ * `'fail'` tracks them and `endOfTest` reports each that is left; `'ignore'` (Jest) does neither,
277
+ * and the assertion is the plain promise it always was. `CorePolicy.unawaitedAsyncAssertion`
278
+ * decides it; the worker passes it in, because this package reads only its own slice.
279
+ * @public
280
+ */
281
+ type UnawaitedAssertion = "ignore" | "fail";
282
+ /**
283
+ * What `createExpect` needs.
284
+ * @public
285
+ */
286
+ interface CreateExpectOptions {
287
+ readonly policy: ExpectPolicy;
288
+ /** The dialect's table, loaded from `policy.matcherTable`. */
289
+ readonly table: ExpectTable;
290
+ readonly source: StateSource;
291
+ /** The registry the slot was installed with; a fresh one when there is no slot. */
292
+ readonly registry?: MatcherRegistry;
293
+ /** Default `'ignore'`. */
294
+ readonly unawaited?: UnawaitedAssertion;
295
+ /** What `expect.poll` waits with: the file's fake clock and, in tests, a manual scheduler. */
296
+ readonly pollTimers?: PollTimers;
297
+ }
298
+ /**
299
+ * Builds a dialect's `expect`. Throws `EXPECT_NOT_IMPLEMENTED` for policy values a later task
300
+ * builds, rather than running them half-way.
301
+ * @public
302
+ */
303
+ export declare function createExpect(options: CreateExpectOptions): ExpectStatic;
304
+ /**
305
+ * Options for `snapshotMatchers`.
306
+ * @public
307
+ */
308
+ interface SnapshotMatchersOptions {
309
+ /** Include `toMatchFileSnapshot`, which Vitest has and Jest doesn't. */
310
+ readonly fileSnapshot: boolean;
311
+ }
312
+ /**
313
+ * The snapshot matchers a dialect's table includes, and the `.resolves`/`.rejects` form of the
314
+ * two that read a thrown error (Jest's `getPromiseMatcher`: the settled value is the error, so the
315
+ * matcher is told not to call it).
316
+ * @public
317
+ */
318
+ export declare function snapshotMatchers(options: SnapshotMatchersOptions): {
319
+ readonly matchers: MatcherSet;
320
+ readonly promiseMatchers: MatcherSet;
321
+ };
322
+ export type { CreateExpectOptions, EndOfTest, EndOfTestAttempt, EndOfTestOptions, ExpectErrorCode, MatcherContext, MatcherRegistry, MatchersSlot, PollTimers, RegistrySnapshot, SlotHandle, SnapshotMatchersOptions, StateSource, StateSourceOptions, TestRun, UnawaitedAssertion };