@provino/snapshot 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/THIRD_PARTY_NOTICES.md +266 -0
- package/dist/index.d.ts +94 -0
- package/dist/index.js +188 -0
- package/dist/node/index.d.ts +100 -0
- package/dist/node/index.js +198 -0
- package/dist/runtime/index.d.ts +241 -0
- package/dist/runtime/index.js +589 -0
- package/package.json +49 -3
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
import { SnapshotUpdateMode } from "@provino/snapshot";
|
|
2
|
+
import { SnapshotFileReport, SnapshotPolicy, SnapshotRunSummary } from "@provino/types";
|
|
3
|
+
/**
|
|
4
|
+
* Adds up the files' snapshot reports the way Jest's `addResult` does: a file counts as added,
|
|
5
|
+
* removed, unmatched or updated when it had any such snapshot, and the totals are plain sums.
|
|
6
|
+
* @public
|
|
7
|
+
*/
|
|
8
|
+
interface SnapshotAggregate {
|
|
9
|
+
add(report: SnapshotFileReport, testFile: string): void;
|
|
10
|
+
/** The run's snapshots, or `undefined` when no file reported any. */
|
|
11
|
+
summary(update: SnapshotUpdateMode): SnapshotRunSummary | undefined;
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Starts an empty aggregate.
|
|
15
|
+
* @public
|
|
16
|
+
*/
|
|
17
|
+
export declare function createSnapshotAggregate(): SnapshotAggregate;
|
|
18
|
+
/**
|
|
19
|
+
* Whether a run's snapshots make it fail. A run that rewrites (`all`) never does. Otherwise an
|
|
20
|
+
* obsolete snapshot, or an obsolete snapshot file, does when the policy says so for the mode:
|
|
21
|
+
* `failCI` when nothing may be written (`none`, CI), `failLocal` when new snapshots are
|
|
22
|
+
* (`new`). Jest: `true` for both (`snapshot.failure` in `TestScheduler`). Vitest: `false` and
|
|
23
|
+
* `true` (it only checks under `none`, in the worker). A snapshot that didn't match is a failed
|
|
24
|
+
* test already.
|
|
25
|
+
* @public
|
|
26
|
+
*/
|
|
27
|
+
export declare function snapshotRunFails(summary: SnapshotRunSummary | undefined, policy: Pick<SnapshotPolicy, "obsolete">): boolean;
|
|
28
|
+
/**
|
|
29
|
+
* The test file a `.snap` file at the default location belongs to: the inverse of
|
|
30
|
+
* `defaultSnapshotPath`, `<dir>/<dirName>/<file><extension>` back to `<dir>/<file>`. It is
|
|
31
|
+
* `undefined` for a path that isn't one (wrong extension, or not inside a `dirName` directory).
|
|
32
|
+
* A project with its own snapshot path resolver has no inverse here: the coordinator asks the
|
|
33
|
+
* resolver the other way round (B23c Phase 4; B23d B1 extends this).
|
|
34
|
+
* @public
|
|
35
|
+
*/
|
|
36
|
+
export declare function testPathOfSnapshot(snapshotPath: string, layout: {
|
|
37
|
+
readonly dirName: string;
|
|
38
|
+
readonly extension: string;
|
|
39
|
+
}): string | undefined;
|
|
40
|
+
/**
|
|
41
|
+
* The test file of a snapshot file in the default layout (`<dir>/<dirName>/<file><extension>`):
|
|
42
|
+
* the inverse of `defaultSnapshotPath`, as Jest's default `resolveTestPath` has it (the parent of
|
|
43
|
+
* the snapshot's directory, whatever that directory is called).
|
|
44
|
+
* @public
|
|
45
|
+
*/
|
|
46
|
+
export declare function defaultSnapshotTestPath(snapshotPath: string, layout: {
|
|
47
|
+
readonly extension: string;
|
|
48
|
+
}): string;
|
|
49
|
+
/**
|
|
50
|
+
* Where to look for obsolete snapshot files, and what to do with them.
|
|
51
|
+
* @public
|
|
52
|
+
*/
|
|
53
|
+
interface ObsoleteSnapshotFilesOptions {
|
|
54
|
+
/** Absolute directories crawled for snapshot files. */
|
|
55
|
+
readonly roots: readonly string[];
|
|
56
|
+
/** The snapshot extension (`.snap`); a file is a snapshot file when its name ends in it. */
|
|
57
|
+
readonly extension: string;
|
|
58
|
+
/**
|
|
59
|
+
* Regular-expression sources: a path any of them matches is not crawled (Jest's
|
|
60
|
+
* `modulePathIgnorePatterns`, which its haste map tests on directory and file paths alike).
|
|
61
|
+
* Whatever the patterns, a path with `node_modules` or a version-control directory in it is not
|
|
62
|
+
* seen either, above the roots too.
|
|
63
|
+
*/
|
|
64
|
+
readonly crawlIgnorePatterns: readonly string[];
|
|
65
|
+
/** Regular-expression sources, joined with `|`: a snapshot whose test path matches is kept. */
|
|
66
|
+
readonly testPathIgnorePatterns: readonly string[];
|
|
67
|
+
/** The test file a snapshot file belongs to (`defaultSnapshotTestPath`, or a resolver's). */
|
|
68
|
+
readonly testPathOf: (snapshotPath: string) => string;
|
|
69
|
+
/** `all` deletes what it finds. */
|
|
70
|
+
readonly update: SnapshotUpdateMode;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* The obsolete snapshot files of a project, sorted; deleted when the mode is `all`.
|
|
74
|
+
* @public
|
|
75
|
+
*/
|
|
76
|
+
export declare function cleanObsoleteSnapshotFiles(options: ObsoleteSnapshotFilesOptions): string[];
|
|
77
|
+
/**
|
|
78
|
+
* What decides a run's update mode.
|
|
79
|
+
* @public
|
|
80
|
+
*/
|
|
81
|
+
interface UpdateModeInput {
|
|
82
|
+
/** `-u`: the user asked for snapshots to be rewritten. */
|
|
83
|
+
readonly update: boolean;
|
|
84
|
+
/** Whether this is a CI run (`--ci`, or the `CI` variable). */
|
|
85
|
+
readonly ci: boolean;
|
|
86
|
+
/** The environment, for the variable the policy names. */
|
|
87
|
+
readonly env: Readonly<Record<string, string | undefined>>;
|
|
88
|
+
readonly policy: Pick<SnapshotPolicy, "ciUpdate" | "updateEnvVar">;
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* The mode a run treats snapshots with. `-u` rewrites. The policy's variable (Vitest's
|
|
92
|
+
* `UPDATE_SNAPSHOT`) names a mode, or any other value means `all`. With neither, CI gets the
|
|
93
|
+
* policy's `ciUpdate` (`none`, in both dialects) and a local run `new`.
|
|
94
|
+
*
|
|
95
|
+
* Jest: `ci && !update ? 'none' : update ? 'all' : 'new'` (jest-config `normalize.ts`). Vitest:
|
|
96
|
+
* `resolveConfig.ts` L661-L672.
|
|
97
|
+
* @public
|
|
98
|
+
*/
|
|
99
|
+
export declare function resolveUpdateMode(input: UpdateModeInput): SnapshotUpdateMode;
|
|
100
|
+
export type { ObsoleteSnapshotFilesOptions, SnapshotAggregate, UpdateModeInput };
|
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
import { basename, dirname, extname, join, resolve, sep } from "node:path";
|
|
2
|
+
import { existsSync, readdirSync, unlinkSync } from "node:fs";
|
|
3
|
+
|
|
4
|
+
// src/node/aggregate.ts
|
|
5
|
+
/**
|
|
6
|
+
* Starts an empty aggregate.
|
|
7
|
+
* @public
|
|
8
|
+
*/
|
|
9
|
+
function createSnapshotAggregate() {
|
|
10
|
+
const counters = {
|
|
11
|
+
added: 0,
|
|
12
|
+
matched: 0,
|
|
13
|
+
unmatched: 0,
|
|
14
|
+
updated: 0,
|
|
15
|
+
unchecked: 0,
|
|
16
|
+
total: 0,
|
|
17
|
+
filesAdded: 0,
|
|
18
|
+
filesRemoved: 0,
|
|
19
|
+
filesUnmatched: 0,
|
|
20
|
+
filesUpdated: 0
|
|
21
|
+
};
|
|
22
|
+
const uncheckedKeysByFile = [];
|
|
23
|
+
const files = /* @__PURE__ */ new Set();
|
|
24
|
+
let reports = 0;
|
|
25
|
+
return {
|
|
26
|
+
add(report, testFile) {
|
|
27
|
+
reports++;
|
|
28
|
+
if (report.added > 0) counters.filesAdded++;
|
|
29
|
+
if (report.fileDeleted) counters.filesRemoved++;
|
|
30
|
+
if (report.unmatched > 0) counters.filesUnmatched++;
|
|
31
|
+
if (report.updated > 0) counters.filesUpdated++;
|
|
32
|
+
counters.added += report.added;
|
|
33
|
+
counters.matched += report.matched;
|
|
34
|
+
counters.unmatched += report.unmatched;
|
|
35
|
+
counters.updated += report.updated;
|
|
36
|
+
counters.unchecked += report.unchecked;
|
|
37
|
+
counters.total += report.added + report.updated + report.unmatched + report.matched;
|
|
38
|
+
if (report.uncheckedKeys.length > 0 && report.unchecked > 0) uncheckedKeysByFile.push({
|
|
39
|
+
file: testFile,
|
|
40
|
+
keys: report.uncheckedKeys
|
|
41
|
+
});
|
|
42
|
+
if (report.file !== null) files.add(report.file);
|
|
43
|
+
},
|
|
44
|
+
summary(update) {
|
|
45
|
+
if (reports === 0) return void 0;
|
|
46
|
+
return {
|
|
47
|
+
counters: { ...counters },
|
|
48
|
+
uncheckedKeysByFile,
|
|
49
|
+
update,
|
|
50
|
+
files: [...files].sort()
|
|
51
|
+
};
|
|
52
|
+
}
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Whether a run's snapshots make it fail. A run that rewrites (`all`) never does. Otherwise an
|
|
57
|
+
* obsolete snapshot, or an obsolete snapshot file, does when the policy says so for the mode:
|
|
58
|
+
* `failCI` when nothing may be written (`none`, CI), `failLocal` when new snapshots are
|
|
59
|
+
* (`new`). Jest: `true` for both (`snapshot.failure` in `TestScheduler`). Vitest: `false` and
|
|
60
|
+
* `true` (it only checks under `none`, in the worker). A snapshot that didn't match is a failed
|
|
61
|
+
* test already.
|
|
62
|
+
* @public
|
|
63
|
+
*/
|
|
64
|
+
function snapshotRunFails(summary, policy) {
|
|
65
|
+
if (summary === void 0 || summary.update === "all") return false;
|
|
66
|
+
const { unchecked, filesRemoved } = summary.counters;
|
|
67
|
+
if (unchecked === 0 && filesRemoved === 0) return false;
|
|
68
|
+
return summary.update === "none" ? policy.obsolete.failCI : policy.obsolete.failLocal;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
// src/node/inverse.ts
|
|
72
|
+
/**
|
|
73
|
+
* The test file a `.snap` file at the default location belongs to: the inverse of
|
|
74
|
+
* `defaultSnapshotPath`, `<dir>/<dirName>/<file><extension>` back to `<dir>/<file>`. It is
|
|
75
|
+
* `undefined` for a path that isn't one (wrong extension, or not inside a `dirName` directory).
|
|
76
|
+
* A project with its own snapshot path resolver has no inverse here: the coordinator asks the
|
|
77
|
+
* resolver the other way round (B23c Phase 4; B23d B1 extends this).
|
|
78
|
+
* @public
|
|
79
|
+
*/
|
|
80
|
+
function testPathOfSnapshot(snapshotPath, layout) {
|
|
81
|
+
const name = basename(snapshotPath);
|
|
82
|
+
const directory = dirname(snapshotPath);
|
|
83
|
+
if (!name.endsWith(layout.extension) || name.length === layout.extension.length) return void 0;
|
|
84
|
+
if (basename(directory) !== layout.dirName) return void 0;
|
|
85
|
+
return join(dirname(directory), name.slice(0, name.length - layout.extension.length));
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
// src/node/obsolete-files.ts
|
|
89
|
+
/**
|
|
90
|
+
* The test file of a snapshot file in the default layout (`<dir>/<dirName>/<file><extension>`):
|
|
91
|
+
* the inverse of `defaultSnapshotPath`, as Jest's default `resolveTestPath` has it (the parent of
|
|
92
|
+
* the snapshot's directory, whatever that directory is called).
|
|
93
|
+
* @public
|
|
94
|
+
*/
|
|
95
|
+
function defaultSnapshotTestPath(snapshotPath, layout) {
|
|
96
|
+
return resolve(dirname(snapshotPath), "..", basename(snapshotPath, layout.extension));
|
|
97
|
+
}
|
|
98
|
+
/** A path with a `node_modules` directory in it: haste map's `retainAllFiles: false` leaves it out. */
|
|
99
|
+
const NODE_MODULES = `${sep}node_modules${sep}`;
|
|
100
|
+
/** Escapes `text` for a regular expression's source. */
|
|
101
|
+
const escapeForRegExp = (text) => text.replaceAll(/[.*+?^${}()|[\]\\/]/g, "\\$&");
|
|
102
|
+
/** jest-haste-map's `VCS_DIRECTORIES` (`index.ts` L107): a path with a `.git`, `.hg` or `.sl` directory in it. */
|
|
103
|
+
const VCS_DIRECTORIES = [
|
|
104
|
+
".git",
|
|
105
|
+
".hg",
|
|
106
|
+
".sl"
|
|
107
|
+
].map((name) => escapeForRegExp(`${sep}${name}${sep}`)).join("|");
|
|
108
|
+
/**
|
|
109
|
+
* What jest-haste-map ignores, as it builds it (`index.ts` L248-L262 and `buildIgnoreMatcher`): a
|
|
110
|
+
* path that matches the project's ignore patterns joined with `|` and the version-control
|
|
111
|
+
* directories, or has `node_modules` in it, wherever it is: the roots' own parents count.
|
|
112
|
+
*/
|
|
113
|
+
function ignorePath(patterns) {
|
|
114
|
+
const ignored = new RegExp([...patterns, VCS_DIRECTORIES].join("|"));
|
|
115
|
+
return (path) => path.includes(NODE_MODULES) || ignored.test(path);
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* Directories a crawl skips unseen: every path below one has `/<name>/` in it, so `ignorePath`
|
|
119
|
+
* drops them all whatever the patterns say.
|
|
120
|
+
*/
|
|
121
|
+
const SKIPPED_DIRECTORIES = /* @__PURE__ */ new Set([
|
|
122
|
+
"node_modules",
|
|
123
|
+
".git",
|
|
124
|
+
".hg",
|
|
125
|
+
".sl"
|
|
126
|
+
]);
|
|
127
|
+
/**
|
|
128
|
+
* The snapshot files under `root`, as jest-haste-map's crawl lists them. Jest 30's default is
|
|
129
|
+
* its `walk` (`forceNodeFilesystemAPI: true`, `lib/walk.ts`: fdir): a directory is entered unless
|
|
130
|
+
* `ignore` drops its path, with the trailing separator taken off, so `/dir$` prunes `dir`; a file
|
|
131
|
+
* is kept when its `path.extname` is the extension (a file named `.snap` has none) and `ignore`
|
|
132
|
+
* doesn't drop its path. A symlink is neither entered nor listed.
|
|
133
|
+
*/
|
|
134
|
+
function crawl(root, extension, ignore, found) {
|
|
135
|
+
let entries;
|
|
136
|
+
try {
|
|
137
|
+
entries = readdirSync(root, { withFileTypes: true });
|
|
138
|
+
} catch {
|
|
139
|
+
return;
|
|
140
|
+
}
|
|
141
|
+
for (const entry of entries) {
|
|
142
|
+
const path = join(root, entry.name);
|
|
143
|
+
if (entry.isDirectory()) {
|
|
144
|
+
if (!SKIPPED_DIRECTORIES.has(entry.name) && !ignore(path)) crawl(path, extension, ignore, found);
|
|
145
|
+
} else if (entry.isFile() && extname(entry.name) === extension && !ignore(path)) found.add(path);
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
/** One regular expression of `|`-joined sources, or `null` for none. */
|
|
149
|
+
function joined(patterns) {
|
|
150
|
+
return patterns.length === 0 ? null : new RegExp(patterns.join("|"));
|
|
151
|
+
}
|
|
152
|
+
/**
|
|
153
|
+
* The obsolete snapshot files of a project, sorted; deleted when the mode is `all`.
|
|
154
|
+
* @public
|
|
155
|
+
*/
|
|
156
|
+
function cleanObsoleteSnapshotFiles(options) {
|
|
157
|
+
const found = /* @__PURE__ */ new Set();
|
|
158
|
+
const ignore = ignorePath(options.crawlIgnorePatterns);
|
|
159
|
+
const versionControl = new RegExp(VCS_DIRECTORIES);
|
|
160
|
+
for (const root of options.roots) {
|
|
161
|
+
const top = `${root}${sep}`;
|
|
162
|
+
if (top.includes(NODE_MODULES) || versionControl.test(top)) continue;
|
|
163
|
+
crawl(root, options.extension, ignore, found);
|
|
164
|
+
}
|
|
165
|
+
const testIgnored = joined(options.testPathIgnorePatterns);
|
|
166
|
+
const obsolete = [];
|
|
167
|
+
for (const snapshotFile of [...found].sort()) {
|
|
168
|
+
const testPath = options.testPathOf(snapshotFile);
|
|
169
|
+
if (testIgnored?.test(testPath) === true) continue;
|
|
170
|
+
if (!existsSync(testPath)) {
|
|
171
|
+
if (options.update === "all") unlinkSync(snapshotFile);
|
|
172
|
+
obsolete.push(snapshotFile);
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
return obsolete;
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
// src/node/update-mode.ts
|
|
179
|
+
const isMode = (value) => value === "all" || value === "new" || value === "none";
|
|
180
|
+
/**
|
|
181
|
+
* The mode a run treats snapshots with. `-u` rewrites. The policy's variable (Vitest's
|
|
182
|
+
* `UPDATE_SNAPSHOT`) names a mode, or any other value means `all`. With neither, CI gets the
|
|
183
|
+
* policy's `ciUpdate` (`none`, in both dialects) and a local run `new`.
|
|
184
|
+
*
|
|
185
|
+
* Jest: `ci && !update ? 'none' : update ? 'all' : 'new'` (jest-config `normalize.ts`). Vitest:
|
|
186
|
+
* `resolveConfig.ts` L661-L672.
|
|
187
|
+
* @public
|
|
188
|
+
*/
|
|
189
|
+
function resolveUpdateMode(input) {
|
|
190
|
+
const { update, ci, env, policy } = input;
|
|
191
|
+
if (update) return "all";
|
|
192
|
+
const fromEnv = policy.updateEnvVar === null ? void 0 : env[policy.updateEnvVar];
|
|
193
|
+
if (isMode(fromEnv)) return fromEnv;
|
|
194
|
+
if (fromEnv !== void 0 && fromEnv !== "") return "all";
|
|
195
|
+
return ci ? policy.ciUpdate : "new";
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
export { cleanObsoleteSnapshotFiles, createSnapshotAggregate, defaultSnapshotTestPath, resolveUpdateMode, snapshotRunFails, testPathOfSnapshot };
|
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
import { SnapshotError, SnapshotErrorCode, SnapshotUpdateMode, SnapshotUpdateMode as SnapshotUpdateMode$1, deepMerge, defaultSnapshotPath, removeExtraLineBreaks } from "@provino/snapshot";
|
|
2
|
+
import { ResolveSnapshotPath, RuntimeEvent, SnapshotFileReport, SnapshotKey, SnapshotPlugin, SnapshotPolicy, SnapshotPrinter, SnapshotViewFactory, SnapshotViewMatchOptions, SnapshotViewMatchResult, SnapshotViewSource } from "@provino/types";
|
|
3
|
+
/**
|
|
4
|
+
* What a state is made from.
|
|
5
|
+
* @public
|
|
6
|
+
*/
|
|
7
|
+
interface SnapshotStateOptions {
|
|
8
|
+
/** The test file. */
|
|
9
|
+
readonly testPath: string;
|
|
10
|
+
/** Its `.snap` file. */
|
|
11
|
+
readonly snapshotPath: string;
|
|
12
|
+
readonly update: SnapshotUpdateMode$1;
|
|
13
|
+
/** Whether diffs show every line. */
|
|
14
|
+
readonly expand: boolean;
|
|
15
|
+
/** The slice's values the state reads. */
|
|
16
|
+
readonly policy: Pick<SnapshotPolicy, "header" | "keyJoin" | "hintJoin" | "format" | "throwErrorBody">;
|
|
17
|
+
/** The key of the n-th snapshot of a test (`SnapshotPolicy.key`, loaded). */
|
|
18
|
+
readonly key: SnapshotKey;
|
|
19
|
+
readonly printer: SnapshotPrinter;
|
|
20
|
+
/** The project's serializers, the first one tried first. */
|
|
21
|
+
readonly serializers?: readonly SnapshotPlugin[];
|
|
22
|
+
/**
|
|
23
|
+
* An inline snapshot that must be written is recorded for the coordinator's writer
|
|
24
|
+
* (`SnapshotFileReport.inline`), as Jest's `_addSnapshot` does; without it (the policy has no
|
|
25
|
+
* writer) such a snapshot fails instead.
|
|
26
|
+
*/
|
|
27
|
+
readonly inlineWrites?: boolean;
|
|
28
|
+
/**
|
|
29
|
+
* The id of the test attempt running now (`SnapshotViewSource.currentTestId`): the worker's
|
|
30
|
+
* current-test lookup, the one the snapshot matchers read their `testId` from. Without it a
|
|
31
|
+
* view's snapshots belong to no attempt.
|
|
32
|
+
*/
|
|
33
|
+
readonly currentTestId?: (() => string | undefined) | undefined;
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* One snapshot assertion: the view's (`SnapshotViewMatchOptions`), which is the matchers' too.
|
|
37
|
+
* @public
|
|
38
|
+
*/
|
|
39
|
+
type MatchOptions = SnapshotViewMatchOptions;
|
|
40
|
+
/**
|
|
41
|
+
* How an assertion went: what a view gets, and whether an inline snapshot could not be written.
|
|
42
|
+
* @public
|
|
43
|
+
*/
|
|
44
|
+
interface MatchResult extends SnapshotViewMatchResult {
|
|
45
|
+
/**
|
|
46
|
+
* The snapshot would have been written into the test's source, and nothing writes there yet
|
|
47
|
+
* (T7.11). `pass` is `false`.
|
|
48
|
+
*/
|
|
49
|
+
readonly inlineNotWritten: boolean;
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* The snapshot state of one test file.
|
|
53
|
+
* @public
|
|
54
|
+
*/
|
|
55
|
+
export declare class SnapshotState implements SnapshotViewSource {
|
|
56
|
+
readonly testPath: string;
|
|
57
|
+
readonly snapshotPath: string;
|
|
58
|
+
readonly update: SnapshotUpdateMode$1;
|
|
59
|
+
expand: boolean;
|
|
60
|
+
/** The pretty-format options every snapshot of the file is serialized with (the policy's `format`). */
|
|
61
|
+
readonly serializeFormat: Readonly<Record<string, unknown>>;
|
|
62
|
+
added: number;
|
|
63
|
+
matched: number;
|
|
64
|
+
unmatched: number;
|
|
65
|
+
updated: number;
|
|
66
|
+
/**
|
|
67
|
+
* The count of snapshots taken per test name, as a live map: the next key of a name follows the
|
|
68
|
+
* count set here. It is there for a dialect's view (`snapshot.contextView`), whose matchers count
|
|
69
|
+
* snapshots of their own; Provino's matchers never read it. A write here, like one to the four
|
|
70
|
+
* counts, belongs to no attempt: `clearTest` keeps it, and puts back only the counters the
|
|
71
|
+
* test's own snapshots touched, each to its value before the test's first snapshot of that name.
|
|
72
|
+
*/
|
|
73
|
+
readonly liveCounters: Map<string, number>;
|
|
74
|
+
private dirty;
|
|
75
|
+
private fileExists;
|
|
76
|
+
private readonly data;
|
|
77
|
+
private readonly uncheckedKeys;
|
|
78
|
+
private readonly rawSnapshots;
|
|
79
|
+
private readonly inlineEdits;
|
|
80
|
+
private readonly attempts;
|
|
81
|
+
private writeCount;
|
|
82
|
+
private plugins;
|
|
83
|
+
private readonly options;
|
|
84
|
+
constructor(options: SnapshotStateOptions);
|
|
85
|
+
/** The serializers in the order they are tried: the one added last first. */
|
|
86
|
+
get serializers(): readonly SnapshotPlugin[];
|
|
87
|
+
/** How a thrown error is stored by `toThrowErrorMatchingSnapshot` (`SnapshotPolicy.throwErrorBody`). */
|
|
88
|
+
get throwErrorBody(): SnapshotPolicy["throwErrorBody"];
|
|
89
|
+
/**
|
|
90
|
+
* A snapshot's test name: the title path joined by the key join, then the hint by the hint
|
|
91
|
+
* join. Jest: `outer inner: hint`. Vitest: `outer > inner > hint`. A hint with no name is
|
|
92
|
+
* dropped, as in Jest (`currentTestName && hint ? ... : currentTestName || ''`).
|
|
93
|
+
*/
|
|
94
|
+
testName(titlePath: readonly string[], hint: string | undefined): string;
|
|
95
|
+
/** The dialect's words, for the matchers. */
|
|
96
|
+
get messages(): SnapshotPrinter["messages"];
|
|
97
|
+
/**
|
|
98
|
+
* Adds a serializer ahead of the others (`expect.addSnapshotSerializer`). The printer's own
|
|
99
|
+
* plugins come after all of them.
|
|
100
|
+
*/
|
|
101
|
+
addSerializer(plugin: SnapshotPlugin): void;
|
|
102
|
+
/**
|
|
103
|
+
* Marks the snapshots of a test that did not run to its end (skipped, todo or failed) as
|
|
104
|
+
* checked, so they are not reported obsolete. A hint is joined to the name before the key is
|
|
105
|
+
* built, so the name recovered from a hinted key is longer than the test's.
|
|
106
|
+
*/
|
|
107
|
+
markCheckedForTest(testName: string): void;
|
|
108
|
+
/**
|
|
109
|
+
* Takes back what a test's earlier attempt did (a retry, or a repeat): its counters, the
|
|
110
|
+
* snapshots it added, the keys it checked and the totals. Other tests' work stays.
|
|
111
|
+
*/
|
|
112
|
+
clearTest(testId: string): void;
|
|
113
|
+
/** The test is over: its attempt record is no longer needed. */
|
|
114
|
+
forgetTest(testId: string): void;
|
|
115
|
+
/**
|
|
116
|
+
* A snapshot that couldn't be taken (the property matchers failed): the count moves on and
|
|
117
|
+
* the key is checked, so the test's other snapshots keep their numbers.
|
|
118
|
+
*/
|
|
119
|
+
fail(testName: string, testId?: string, key?: string): string;
|
|
120
|
+
/** The attempt running now, as the worker's current-test lookup names it (`SnapshotViewSource`). */
|
|
121
|
+
currentTestId(): string | undefined;
|
|
122
|
+
/** Compares one value with its stored snapshot, and writes it when the mode says to. */
|
|
123
|
+
match(options: MatchOptions): MatchResult;
|
|
124
|
+
/**
|
|
125
|
+
* Compares a raw string with the contents of a file (`toMatchFileSnapshot`): no serializing, no
|
|
126
|
+
* extra line breaks, an exact compare. `existing` is the file's text, or `undefined` if it
|
|
127
|
+
* doesn't exist.
|
|
128
|
+
*/
|
|
129
|
+
matchRaw(options: {
|
|
130
|
+
readonly testName: string;
|
|
131
|
+
readonly testId?: string;
|
|
132
|
+
readonly received: unknown;
|
|
133
|
+
readonly file: string;
|
|
134
|
+
readonly existing: string | undefined;
|
|
135
|
+
}): MatchResult;
|
|
136
|
+
getUncheckedCount(): number;
|
|
137
|
+
getUncheckedKeys(): string[];
|
|
138
|
+
/** Under `all`, forgets the obsolete snapshots, so the next save drops them. */
|
|
139
|
+
removeUncheckedKeys(): void;
|
|
140
|
+
/**
|
|
141
|
+
* Writes the `.snap` file (and any raw file) if something changed or something is obsolete,
|
|
142
|
+
* and deletes it under `all` when nothing is left in it.
|
|
143
|
+
*/
|
|
144
|
+
save(): {
|
|
145
|
+
readonly saved: boolean;
|
|
146
|
+
readonly deleted: boolean;
|
|
147
|
+
};
|
|
148
|
+
/**
|
|
149
|
+
* Ends the file: settles what is obsolete, saves, and reports. Call it after the file's skipped
|
|
150
|
+
* and failed tests were marked with `markCheckedForTest`.
|
|
151
|
+
*/
|
|
152
|
+
finish(): SnapshotFileReport;
|
|
153
|
+
/** The contents of a raw snapshot file, or `undefined` when it doesn't exist. */
|
|
154
|
+
static readRaw(file: string): string | undefined;
|
|
155
|
+
private serialize;
|
|
156
|
+
private result;
|
|
157
|
+
private recordFor;
|
|
158
|
+
/** A key only reached by a discarded attempt has to go back to being unchecked. */
|
|
159
|
+
private markKeyChecked;
|
|
160
|
+
/**
|
|
161
|
+
* Counters number keys per full test name, and full names can collide across tests. Undoing an
|
|
162
|
+
* increment could double-undo a collision, so the record keeps each counter's value from before
|
|
163
|
+
* the test first touched it.
|
|
164
|
+
*/
|
|
165
|
+
private bumpCounter;
|
|
166
|
+
private incrementCount;
|
|
167
|
+
private noteWrite;
|
|
168
|
+
private addSnapshot;
|
|
169
|
+
/**
|
|
170
|
+
* An inline snapshot to write (State.ts L167-L184): where the call is comes from the top frame
|
|
171
|
+
* of its stack, so the coordinator's writer can find it in the source. The stack is taken only
|
|
172
|
+
* here, the one place it is read, still inside the matcher's call.
|
|
173
|
+
*/
|
|
174
|
+
private addInline;
|
|
175
|
+
private addRaw;
|
|
176
|
+
}
|
|
177
|
+
/**
|
|
178
|
+
* Follows one test file's events for its snapshot state.
|
|
179
|
+
* @public
|
|
180
|
+
*/
|
|
181
|
+
interface SnapshotLifecycle {
|
|
182
|
+
/** Feeds one runtime event of the file. */
|
|
183
|
+
observe(event: RuntimeEvent): void;
|
|
184
|
+
/**
|
|
185
|
+
* Ends the file: marks the snapshots of the tests that didn't pass as checked, then settles
|
|
186
|
+
* what is obsolete, saves and reports (`SnapshotState.finish`). A file that never collected its
|
|
187
|
+
* tests (it failed to load) has no tests to hold its snapshots against: nothing is settled or
|
|
188
|
+
* saved, and the report is `null`, as in Jest, whose adapter never reaches `_addSnapshotData`.
|
|
189
|
+
*/
|
|
190
|
+
finish(): SnapshotFileReport | null;
|
|
191
|
+
}
|
|
192
|
+
/**
|
|
193
|
+
* Builds the lifecycle of a file's state. `keyJoin` joins a test's title path into the name its
|
|
194
|
+
* snapshots' keys start with.
|
|
195
|
+
* @public
|
|
196
|
+
*/
|
|
197
|
+
export declare function trackSnapshots(state: SnapshotState, options: {
|
|
198
|
+
readonly keyJoin: string;
|
|
199
|
+
}): SnapshotLifecycle;
|
|
200
|
+
/**
|
|
201
|
+
* What the snapshot matchers work on, from a matcher's `snapshotState`: the state a view
|
|
202
|
+
* `openFileSnapshots` built was built over, else the value as it is (the state itself, or whatever
|
|
203
|
+
* else a test put there, which the matchers then refuse).
|
|
204
|
+
* @public
|
|
205
|
+
*/
|
|
206
|
+
export declare function unwrapMatcherSnapshotState(value: unknown): unknown;
|
|
207
|
+
/**
|
|
208
|
+
* What a worker needs to open one test file's snapshots. The behaviours (`key`, `printer`,
|
|
209
|
+
* `resolvePath`, `contextView`) are the policy's refs, loaded once per worker.
|
|
210
|
+
* @public
|
|
211
|
+
*/
|
|
212
|
+
interface OpenSnapshotsOptions {
|
|
213
|
+
readonly testPath: string;
|
|
214
|
+
readonly update: SnapshotUpdateMode$1;
|
|
215
|
+
readonly expand: boolean;
|
|
216
|
+
readonly policy: SnapshotPolicy;
|
|
217
|
+
readonly key: SnapshotKey;
|
|
218
|
+
/** `null`: the policy names no printer, and a snapshot assertion fails with `SNAPSHOT_NO_PRINTER`. */
|
|
219
|
+
readonly printer: SnapshotPrinter | null;
|
|
220
|
+
/** `null`: the default layout beside the test file. */
|
|
221
|
+
readonly resolvePath: ResolveSnapshotPath | null;
|
|
222
|
+
/** `null`: a matcher's `this.snapshotState` is the state itself, not a view of it. */
|
|
223
|
+
readonly contextView: SnapshotViewFactory | null;
|
|
224
|
+
/**
|
|
225
|
+
* The id of the test attempt running now (`SnapshotStateOptions.currentTestId`), from the
|
|
226
|
+
* worker's current-test lookup: what a view's snapshots are recorded against.
|
|
227
|
+
*/
|
|
228
|
+
readonly currentTestId?: () => string | undefined;
|
|
229
|
+
}
|
|
230
|
+
/**
|
|
231
|
+
* Opens a test file's snapshots: its state (reading the `.snap` file), the lifecycle that follows
|
|
232
|
+
* the file's events, and `matcherSnapshotState`, what a matcher finds as `this.snapshotState` (the
|
|
233
|
+
* state, or the policy's view of it; `unwrapMatcherSnapshotState` gives the state back).
|
|
234
|
+
* @public
|
|
235
|
+
*/
|
|
236
|
+
export declare function openFileSnapshots(options: OpenSnapshotsOptions): {
|
|
237
|
+
readonly state: SnapshotState;
|
|
238
|
+
readonly lifecycle: SnapshotLifecycle;
|
|
239
|
+
readonly matcherSnapshotState: object;
|
|
240
|
+
};
|
|
241
|
+
export { type MatchOptions, type MatchResult, type OpenSnapshotsOptions, SnapshotError, type SnapshotErrorCode, type SnapshotLifecycle, type SnapshotStateOptions, type SnapshotUpdateMode, deepMerge, defaultSnapshotPath, removeExtraLineBreaks };
|