@simplysf/simply-utam-core 0.2.0 → 0.3.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/README.md +72 -16
- package/lib/forceignore/forceignore-manager.d.ts +30 -0
- package/lib/forceignore/forceignore-manager.js +28 -10
- package/lib/forceignore/forceignore-manager.js.map +1 -1
- package/lib/forceignore/index.d.ts +1 -1
- package/lib/forceignore/index.js +1 -1
- package/lib/forceignore/index.js.map +1 -1
- package/lib/gitignore/gitignore-manager.d.ts +64 -0
- package/lib/gitignore/gitignore-manager.js +96 -0
- package/lib/gitignore/gitignore-manager.js.map +1 -0
- package/lib/gitignore/index.d.ts +1 -0
- package/lib/gitignore/index.js +17 -0
- package/lib/gitignore/index.js.map +1 -0
- package/lib/index.d.ts +3 -1
- package/lib/index.js +3 -1
- package/lib/index.js.map +1 -1
- package/lib/namespaces/namespace-map.d.ts +18 -0
- package/lib/namespaces/namespace-map.js +75 -0
- package/lib/namespaces/namespace-map.js.map +1 -0
- package/lib/namespaces/namespace-rewriter.js +2 -47
- package/lib/namespaces/namespace-rewriter.js.map +1 -1
- package/lib/scaffold/project-scaffolder.d.ts +26 -1
- package/lib/scaffold/project-scaffolder.js +81 -11
- package/lib/scaffold/project-scaffolder.js.map +1 -1
- package/lib/snapshot/capture.d.ts +56 -0
- package/lib/snapshot/capture.js +115 -0
- package/lib/snapshot/capture.js.map +1 -0
- package/lib/snapshot/console.d.ts +25 -0
- package/lib/snapshot/console.js +74 -0
- package/lib/snapshot/console.js.map +1 -0
- package/lib/snapshot/describe.d.ts +27 -0
- package/lib/snapshot/describe.js +76 -0
- package/lib/snapshot/describe.js.map +1 -0
- package/lib/snapshot/files.d.ts +85 -0
- package/lib/snapshot/files.js +185 -0
- package/lib/snapshot/files.js.map +1 -0
- package/lib/snapshot/find.d.ts +36 -0
- package/lib/snapshot/find.js +186 -0
- package/lib/snapshot/find.js.map +1 -0
- package/lib/snapshot/format.d.ts +96 -0
- package/lib/snapshot/format.js +100 -0
- package/lib/snapshot/format.js.map +1 -0
- package/lib/snapshot/header.d.ts +38 -0
- package/lib/snapshot/header.js +120 -0
- package/lib/snapshot/header.js.map +1 -0
- package/lib/snapshot/index.d.ts +13 -0
- package/lib/snapshot/index.js +28 -0
- package/lib/snapshot/index.js.map +1 -0
- package/lib/snapshot/locate.d.ts +61 -0
- package/lib/snapshot/locate.js +110 -0
- package/lib/snapshot/locate.js.map +1 -0
- package/lib/snapshot/lookup.d.ts +53 -0
- package/lib/snapshot/lookup.js +188 -0
- package/lib/snapshot/lookup.js.map +1 -0
- package/lib/snapshot/page-object-index.d.ts +149 -0
- package/lib/snapshot/page-object-index.js +806 -0
- package/lib/snapshot/page-object-index.js.map +1 -0
- package/lib/snapshot/page-object-packages.d.ts +41 -0
- package/lib/snapshot/page-object-packages.js +115 -0
- package/lib/snapshot/page-object-packages.js.map +1 -0
- package/lib/snapshot/path.d.ts +102 -0
- package/lib/snapshot/path.js +381 -0
- package/lib/snapshot/path.js.map +1 -0
- package/lib/snapshot/query-result.d.ts +20 -0
- package/lib/snapshot/query-result.js +32 -0
- package/lib/snapshot/query-result.js.map +1 -0
- package/lib/snapshot/selector.d.ts +103 -0
- package/lib/snapshot/selector.js +280 -0
- package/lib/snapshot/selector.js.map +1 -0
- package/lib/snapshot/tree.d.ts +76 -0
- package/lib/snapshot/tree.js +201 -0
- package/lib/snapshot/tree.js.map +1 -0
- package/lib/snapshot/walker.js +532 -0
- package/package.json +11 -3
- package/templates/dom-snapshot.steps.mjs +34 -0
- package/templates/wdio.conf.mjs +81 -4
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Copyright (c) 2026, SimplySF.
|
|
3
|
+
*
|
|
4
|
+
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
* you may not use this file except in compliance with the License.
|
|
6
|
+
* You may obtain a copy of the License at
|
|
7
|
+
*
|
|
8
|
+
* http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
*
|
|
10
|
+
* Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
* See the License for the specific language governing permissions and
|
|
14
|
+
* limitations under the License.
|
|
15
|
+
*/
|
|
16
|
+
import { readFileSync } from 'node:fs';
|
|
17
|
+
import { parseDomSnapshot } from './format.js';
|
|
18
|
+
export const SNAPSHOT_MASK_ENV = 'UTAM_SNAPSHOT_MASK';
|
|
19
|
+
let walkerSourceCache;
|
|
20
|
+
/** The walker's source text, exactly as it ships in `walker.js`. */
|
|
21
|
+
export function walkerSource() {
|
|
22
|
+
walkerSourceCache ??= readFileSync(new URL('./walker.js', import.meta.url), 'utf8');
|
|
23
|
+
return walkerSourceCache;
|
|
24
|
+
}
|
|
25
|
+
function browserPage(browser) {
|
|
26
|
+
return {
|
|
27
|
+
async evaluate(source) {
|
|
28
|
+
return String(await browser.execute(`return ${source};`));
|
|
29
|
+
},
|
|
30
|
+
};
|
|
31
|
+
}
|
|
32
|
+
function resolveMask(options) {
|
|
33
|
+
const value = options.mask ?? (options.env ?? process.env)[SNAPSHOT_MASK_ENV];
|
|
34
|
+
return value === 'structure' || value === 'aria' || value === 'full' ? value : 'labels';
|
|
35
|
+
}
|
|
36
|
+
/** The default warning sink. */
|
|
37
|
+
export function warn(message) {
|
|
38
|
+
// eslint-disable-next-line no-console -- the default sink; `log` lets a caller redirect it
|
|
39
|
+
console.warn(message);
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* The expression that runs the walker with these options, `(<walker>)(<options>)`, as every way of
|
|
43
|
+
* capturing sends it to a page. Warns through `log` when the mask is `full`.
|
|
44
|
+
*/
|
|
45
|
+
export function walkerExpression(options) {
|
|
46
|
+
const mask = resolveMask(options);
|
|
47
|
+
if (mask === 'full')
|
|
48
|
+
(options.log ?? warn)('DOM snapshot: mask "full" keeps record data in the snapshot.');
|
|
49
|
+
const walkerOptions = {
|
|
50
|
+
trigger: options.trigger ?? 'manual',
|
|
51
|
+
label: options.label,
|
|
52
|
+
mask,
|
|
53
|
+
maxNodes: options.maxNodes,
|
|
54
|
+
maxHiddenNodes: options.maxHiddenNodes,
|
|
55
|
+
timeBudgetMs: options.timeBudgetMs,
|
|
56
|
+
focus: options.focus,
|
|
57
|
+
};
|
|
58
|
+
return `(${walkerSource()})(${JSON.stringify(walkerOptions)})`;
|
|
59
|
+
}
|
|
60
|
+
// Assertion libraries color their messages; the snapshot is read as text, not in a terminal.
|
|
61
|
+
// eslint-disable-next-line no-control-regex -- matching the escape character is the point
|
|
62
|
+
const ANSI_ESCAPE = /\u001b\[[0-9;]*m/g;
|
|
63
|
+
function stripAnsi(text) {
|
|
64
|
+
return text.replace(ANSI_ESCAPE, '');
|
|
65
|
+
}
|
|
66
|
+
function errorMessage(error) {
|
|
67
|
+
if (error === undefined || error === null)
|
|
68
|
+
return undefined;
|
|
69
|
+
if (error instanceof Error)
|
|
70
|
+
return error.message;
|
|
71
|
+
if (typeof error === 'object' && 'message' in error)
|
|
72
|
+
return String(error.message);
|
|
73
|
+
return typeof error === 'string' ? error : JSON.stringify(error);
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Capture a DOM snapshot of the current page. Never throws: on any failure it logs a warning and
|
|
77
|
+
* returns `undefined`.
|
|
78
|
+
*
|
|
79
|
+
* @param options What to capture and how.
|
|
80
|
+
*/
|
|
81
|
+
export async function captureDomSnapshot(options = {}) {
|
|
82
|
+
const log = options.log ?? warn;
|
|
83
|
+
try {
|
|
84
|
+
const source = walkerExpression({ ...options, log });
|
|
85
|
+
const timeoutMs = options.timeoutMs ?? 10_000;
|
|
86
|
+
let page = options.page;
|
|
87
|
+
if (!page) {
|
|
88
|
+
const browser = options.browser ?? globalThis.browser;
|
|
89
|
+
if (!browser || typeof browser.execute !== 'function')
|
|
90
|
+
throw new Error('no browser to capture');
|
|
91
|
+
page = browserPage(browser);
|
|
92
|
+
}
|
|
93
|
+
let timer;
|
|
94
|
+
const json = await Promise.race([
|
|
95
|
+
page.evaluate(source, timeoutMs),
|
|
96
|
+
new Promise((_, reject) => {
|
|
97
|
+
timer = setTimeout(() => reject(new Error(`timed out after ${timeoutMs} ms`)), timeoutMs);
|
|
98
|
+
}),
|
|
99
|
+
]).finally(() => clearTimeout(timer));
|
|
100
|
+
const snapshot = parseDomSnapshot(json);
|
|
101
|
+
if (options.scenario)
|
|
102
|
+
snapshot.meta.scenario = options.scenario;
|
|
103
|
+
if (options.step)
|
|
104
|
+
snapshot.meta.step = options.step;
|
|
105
|
+
const message = errorMessage(options.error);
|
|
106
|
+
if (message !== undefined)
|
|
107
|
+
snapshot.meta.error = stripAnsi(message);
|
|
108
|
+
return snapshot;
|
|
109
|
+
}
|
|
110
|
+
catch (error) {
|
|
111
|
+
log(`DOM snapshot not captured: ${errorMessage(error) ?? 'unknown error'}`);
|
|
112
|
+
return undefined;
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
//# sourceMappingURL=capture.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"capture.js","sourceRoot":"","sources":["../../src/snapshot/capture.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import { type WalkerOptions } from './capture.js';
|
|
2
|
+
import { type DomSnapshot } from './format.js';
|
|
3
|
+
export type DomSnapshotSnippetOptions = Omit<WalkerOptions, 'trigger' | 'label'>;
|
|
4
|
+
export type ImportDomSnapshotOptions = {
|
|
5
|
+
/** Replaces the snapshot's label when given. */
|
|
6
|
+
label?: string;
|
|
7
|
+
};
|
|
8
|
+
/**
|
|
9
|
+
* The console snippet: the walker with its options, wrapped to copy the snapshot JSON to the
|
|
10
|
+
* clipboard (or download it, where the console's `copy` isn't defined) and return a one-line summary.
|
|
11
|
+
* The mask is fixed here, because masking runs in the page. The snippet is ASCII only, so no clipboard
|
|
12
|
+
* or terminal encoding can change it.
|
|
13
|
+
*
|
|
14
|
+
* @param options The walker's options; the trigger is always `manual`, and a label is set on import.
|
|
15
|
+
*/
|
|
16
|
+
export declare function domSnapshotSnippet(options?: DomSnapshotSnippetOptions): string;
|
|
17
|
+
/**
|
|
18
|
+
* Read snapshot JSON from outside a test run, such as what the console snippet copied, for
|
|
19
|
+
* `writeDomSnapshot`. The rest of `meta` is kept as captured.
|
|
20
|
+
*
|
|
21
|
+
* @param json The snapshot's JSON text.
|
|
22
|
+
* @param options The label to set.
|
|
23
|
+
* @throws {DomSnapshotError} When the text isn't a snapshot this version can read.
|
|
24
|
+
*/
|
|
25
|
+
export declare function importDomSnapshot(json: string, options?: ImportDomSnapshotOptions): DomSnapshot;
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Copyright (c) 2026, SimplySF.
|
|
3
|
+
*
|
|
4
|
+
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
* you may not use this file except in compliance with the License.
|
|
6
|
+
* You may obtain a copy of the License at
|
|
7
|
+
*
|
|
8
|
+
* http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
*
|
|
10
|
+
* Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
* See the License for the specific language governing permissions and
|
|
14
|
+
* limitations under the License.
|
|
15
|
+
*/
|
|
16
|
+
import { walkerExpression } from './capture.js';
|
|
17
|
+
import { parseDomSnapshot } from './format.js';
|
|
18
|
+
/** The command that saves what the snippet copied, as the summary names it. */
|
|
19
|
+
const IMPORT_COMMAND = 'npx simply-utam snapshot console import';
|
|
20
|
+
// Runs in the browser's console. `copy` is the console's own utility; anywhere else, such as an
|
|
21
|
+
// agent's browser tool, the JSON is downloaded instead. The JSON is made ASCII only, as the snippet
|
|
22
|
+
// is, so no clipboard encoding changes it. It returns a summary, never the snapshot, so a tool that
|
|
23
|
+
// runs it doesn't get the whole snapshot back.
|
|
24
|
+
const WRAPPER = String.raw `(() => {
|
|
25
|
+
const json = __WALKER__.replace(/[\u0080-\uffff]/g, (c) => '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0'));
|
|
26
|
+
const meta = JSON.parse(json).meta;
|
|
27
|
+
const truncated = meta.truncated ? ', TRUNCATED (' + meta.truncated.reasons.join(', ') + ')' : '';
|
|
28
|
+
const summary = 'DOM snapshot of ' + meta.url + ' (' + Math.ceil(json.length / 1024) + ' KB, mask ' + meta.mask + truncated + ')';
|
|
29
|
+
if (typeof copy === 'function') {
|
|
30
|
+
copy(json);
|
|
31
|
+
return summary + ' copied to the clipboard. Save it with: __IMPORT__';
|
|
32
|
+
}
|
|
33
|
+
const name = 'dom-snapshot-' + meta.capturedAt.replace(/[-:]/g, '').slice(0, 15) + '.json';
|
|
34
|
+
const link = document.createElement('a');
|
|
35
|
+
link.href = URL.createObjectURL(new Blob([json], { type: 'application/json' }));
|
|
36
|
+
link.download = name;
|
|
37
|
+
document.body.appendChild(link);
|
|
38
|
+
link.click();
|
|
39
|
+
link.remove();
|
|
40
|
+
setTimeout(() => URL.revokeObjectURL(link.href), 60000);
|
|
41
|
+
return summary + ' downloaded as ' + name + '. Save it with: __IMPORT__ --file <path to ' + name + '>';
|
|
42
|
+
})()`;
|
|
43
|
+
/** Every character outside ASCII as a `\u` escape, which means the same in JS source, strings and comments alike. */
|
|
44
|
+
function asciiOnly(source) {
|
|
45
|
+
return source.replace(/[\u0080-\uffff]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`);
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* The console snippet: the walker with its options, wrapped to copy the snapshot JSON to the
|
|
49
|
+
* clipboard (or download it, where the console's `copy` isn't defined) and return a one-line summary.
|
|
50
|
+
* The mask is fixed here, because masking runs in the page. The snippet is ASCII only, so no clipboard
|
|
51
|
+
* or terminal encoding can change it.
|
|
52
|
+
*
|
|
53
|
+
* @param options The walker's options; the trigger is always `manual`, and a label is set on import.
|
|
54
|
+
*/
|
|
55
|
+
export function domSnapshotSnippet(options = {}) {
|
|
56
|
+
const expression = walkerExpression({ ...options, trigger: 'manual' });
|
|
57
|
+
return asciiOnly(WRAPPER.replace('__WALKER__', () => expression).replace(/__IMPORT__/g, () => IMPORT_COMMAND));
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Read snapshot JSON from outside a test run, such as what the console snippet copied, for
|
|
61
|
+
* `writeDomSnapshot`. The rest of `meta` is kept as captured.
|
|
62
|
+
*
|
|
63
|
+
* @param json The snapshot's JSON text.
|
|
64
|
+
* @param options The label to set.
|
|
65
|
+
* @throws {DomSnapshotError} When the text isn't a snapshot this version can read.
|
|
66
|
+
*/
|
|
67
|
+
export function importDomSnapshot(json, options = {}) {
|
|
68
|
+
// A clipboard on Windows can hand back a byte order mark before the text.
|
|
69
|
+
const snapshot = parseDomSnapshot(json.replace(/^\uFEFF/, ''));
|
|
70
|
+
if (options.label)
|
|
71
|
+
snapshot.meta.label = options.label;
|
|
72
|
+
return snapshot;
|
|
73
|
+
}
|
|
74
|
+
//# sourceMappingURL=console.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"console.js","sourceRoot":"","sources":["../../src/snapshot/console.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,gBAAgB,EAAsB,MAAM,cAAc,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAoB,MAAM,aAAa,CAAC;AASjE,+EAA+E;AAC/E,MAAM,cAAc,GAAG,yCAAyC,CAAC;AAEjE,gGAAgG;AAChG,oGAAoG;AACpG,oGAAoG;AACpG,+CAA+C;AAC/C,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;KAkBrB,CAAC;AAEN,qHAAqH;AACrH,SAAS,SAAS,CAAC,MAAc;IAC/B,OAAO,MAAM,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;AAChH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAAqC,EAAE;IACxE,MAAM,UAAU,GAAG,gBAAgB,CAAC,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;IACvE,OAAO,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC;AACjH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,UAAoC,EAAE;IACpF,0EAA0E;IAC1E,MAAM,QAAQ,GAAG,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC;IAC/D,IAAI,OAAO,CAAC,KAAK;QAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IACvD,OAAO,QAAQ,CAAC;AAClB,CAAC"}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import type { DomNode } from './format.js';
|
|
2
|
+
/**
|
|
3
|
+
* Cut a value to `max` characters, ending with `…` when it was longer.
|
|
4
|
+
*
|
|
5
|
+
* @param value The text.
|
|
6
|
+
* @param max The most characters to keep.
|
|
7
|
+
*/
|
|
8
|
+
export declare function clip(value: string, max?: number): string;
|
|
9
|
+
/**
|
|
10
|
+
* A value as one POSIX shell word, for a command the output suggests: double-quoted, or
|
|
11
|
+
* single-quoted when it has a double quote.
|
|
12
|
+
*
|
|
13
|
+
* @param value The text, such as a selector.
|
|
14
|
+
*/
|
|
15
|
+
export declare function shellQuote(value: string): string;
|
|
16
|
+
/**
|
|
17
|
+
* A node in one line: tag, id and classes as CSS, other attributes, own text and shadow text.
|
|
18
|
+
*
|
|
19
|
+
* @param node The node.
|
|
20
|
+
*/
|
|
21
|
+
export declare function describeNode(node: DomNode): string;
|
|
22
|
+
/**
|
|
23
|
+
* A node in one line, without its own text: for naming a container.
|
|
24
|
+
*
|
|
25
|
+
* @param node The node.
|
|
26
|
+
*/
|
|
27
|
+
export declare function describePlain(node: DomNode): string;
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Copyright (c) 2026, SimplySF.
|
|
3
|
+
*
|
|
4
|
+
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
* you may not use this file except in compliance with the License.
|
|
6
|
+
* You may obtain a copy of the License at
|
|
7
|
+
*
|
|
8
|
+
* http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
*
|
|
10
|
+
* Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
* See the License for the specific language governing permissions and
|
|
14
|
+
* limitations under the License.
|
|
15
|
+
*/
|
|
16
|
+
/**
|
|
17
|
+
* Cut a value to `max` characters, ending with `…` when it was longer.
|
|
18
|
+
*
|
|
19
|
+
* @param value The text.
|
|
20
|
+
* @param max The most characters to keep.
|
|
21
|
+
*/
|
|
22
|
+
export function clip(value, max = 60) {
|
|
23
|
+
return value.length > max ? `${value.slice(0, max - 1)}…` : value;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* A value as one POSIX shell word, for a command the output suggests: double-quoted, or
|
|
27
|
+
* single-quoted when it has a double quote.
|
|
28
|
+
*
|
|
29
|
+
* @param value The text, such as a selector.
|
|
30
|
+
*/
|
|
31
|
+
export function shellQuote(value) {
|
|
32
|
+
return value.includes('"') ? `'${value.replaceAll("'", "'\\''")}'` : `"${value}"`;
|
|
33
|
+
}
|
|
34
|
+
// Aura and LWC bookkeeping: never useful in a selector, and on every node of a Lightning page.
|
|
35
|
+
const NOISE_ATTRS = new Set(['data-aura-rendered-by', 'data-data-rendering-service-uid', 'data-aura-class']);
|
|
36
|
+
/**
|
|
37
|
+
* A node in one line: tag, id and classes as CSS, other attributes, own text and shadow text.
|
|
38
|
+
*
|
|
39
|
+
* @param node The node.
|
|
40
|
+
*/
|
|
41
|
+
export function describeNode(node) {
|
|
42
|
+
const attrs = node.attrs ?? {};
|
|
43
|
+
let out = node.tag;
|
|
44
|
+
if (attrs.id)
|
|
45
|
+
out += `#${attrs.id}`;
|
|
46
|
+
if (attrs.class)
|
|
47
|
+
out += attrs.class
|
|
48
|
+
.trim()
|
|
49
|
+
.split(/\s+/)
|
|
50
|
+
.map((name) => `.${name}`)
|
|
51
|
+
.join('');
|
|
52
|
+
for (const [name, value] of Object.entries(attrs)) {
|
|
53
|
+
if (name !== 'id' && name !== 'class' && !NOISE_ATTRS.has(name))
|
|
54
|
+
out += `[${name}="${clip(value)}"]`;
|
|
55
|
+
}
|
|
56
|
+
if (node.text)
|
|
57
|
+
out += ` "${node.text}"`;
|
|
58
|
+
if (node.shadow?.text)
|
|
59
|
+
out += ` #shadow "${node.shadow.text}"`;
|
|
60
|
+
if (node.shadow?.mode === 'unreadable')
|
|
61
|
+
out += ' #shadow(unreadable: UTAM selectors cannot reach inside)';
|
|
62
|
+
if (node.src)
|
|
63
|
+
out += ` src="${node.src}"`;
|
|
64
|
+
if (node.notCaptured)
|
|
65
|
+
out += ' (iframe content not captured)';
|
|
66
|
+
return out;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* A node in one line, without its own text: for naming a container.
|
|
70
|
+
*
|
|
71
|
+
* @param node The node.
|
|
72
|
+
*/
|
|
73
|
+
export function describePlain(node) {
|
|
74
|
+
return describeNode({ ...node, text: undefined });
|
|
75
|
+
}
|
|
76
|
+
//# sourceMappingURL=describe.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"describe.js","sourceRoot":"","sources":["../../src/snapshot/describe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;;;GAKG;AACH,MAAM,UAAU,IAAI,CAAC,KAAa,EAAE,GAAG,GAAG,EAAE;IAC1C,OAAO,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;AACpE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC;AACpF,CAAC;AAED,+FAA+F;AAC/F,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,uBAAuB,EAAE,iCAAiC,EAAE,iBAAiB,CAAC,CAAC,CAAC;AAE7G;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAAa;IACxC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;IAC/B,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;IACnB,IAAI,KAAK,CAAC,EAAE;QAAE,GAAG,IAAI,IAAI,KAAK,CAAC,EAAE,EAAE,CAAC;IACpC,IAAI,KAAK,CAAC,KAAK;QACb,GAAG,IAAI,KAAK,CAAC,KAAK;aACf,IAAI,EAAE;aACN,KAAK,CAAC,KAAK,CAAC;aACZ,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;aACzB,IAAI,CAAC,EAAE,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAClD,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,GAAG,IAAI,IAAI,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACvG,CAAC;IACD,IAAI,IAAI,CAAC,IAAI;QAAE,GAAG,IAAI,KAAK,IAAI,CAAC,IAAI,GAAG,CAAC;IACxC,IAAI,IAAI,CAAC,MAAM,EAAE,IAAI;QAAE,GAAG,IAAI,aAAa,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC;IAC/D,IAAI,IAAI,CAAC,MAAM,EAAE,IAAI,KAAK,YAAY;QAAE,GAAG,IAAI,0DAA0D,CAAC;IAC1G,IAAI,IAAI,CAAC,GAAG;QAAE,GAAG,IAAI,SAAS,IAAI,CAAC,GAAG,GAAG,CAAC;IAC1C,IAAI,IAAI,CAAC,WAAW;QAAE,GAAG,IAAI,gCAAgC,CAAC;IAC9D,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAAa;IACzC,OAAO,YAAY,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;AACpD,CAAC"}
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import type { EnvLike } from '../test-environment.js';
|
|
2
|
+
import { type DomSnapshot } from './format.js';
|
|
3
|
+
/** Set once per test run (the scaffolded `onPrepare` hook does), so every worker writes to one folder. */
|
|
4
|
+
export declare const SNAPSHOT_RUN_ID_ENV = "UTAM_SNAPSHOT_RUN_ID";
|
|
5
|
+
/** Where snapshots are written, relative to the project. */
|
|
6
|
+
export declare const SNAPSHOTS_DIR = ".utam/snapshots";
|
|
7
|
+
/** The run id for captures made outside a test run, such as from the console; pruning keeps its folder. */
|
|
8
|
+
export declare const MANUAL_RUN_ID = "manual";
|
|
9
|
+
/** A copy of the most recent snapshot, relative to the project: the query commands' default. */
|
|
10
|
+
export declare const LATEST_SNAPSHOT = ".utam/snapshots/latest.json";
|
|
11
|
+
/** The file system calls `writeDomSnapshot` and `pruneDomSnapshots` make. */
|
|
12
|
+
export type SnapshotFileSystem = {
|
|
13
|
+
mkdir(dir: string, options: {
|
|
14
|
+
recursive: true;
|
|
15
|
+
}): Promise<unknown>;
|
|
16
|
+
writeFile(file: string, data: string, options?: {
|
|
17
|
+
flag?: string;
|
|
18
|
+
}): Promise<void>;
|
|
19
|
+
readdir(dir: string, options: {
|
|
20
|
+
withFileTypes: true;
|
|
21
|
+
}): Promise<Array<{
|
|
22
|
+
name: string;
|
|
23
|
+
isDirectory(): boolean;
|
|
24
|
+
}>>;
|
|
25
|
+
stat(target: string): Promise<{
|
|
26
|
+
mtimeMs: number;
|
|
27
|
+
}>;
|
|
28
|
+
rm(target: string, options: {
|
|
29
|
+
recursive: true;
|
|
30
|
+
force: true;
|
|
31
|
+
}): Promise<void>;
|
|
32
|
+
rename(from: string, to: string): Promise<void>;
|
|
33
|
+
};
|
|
34
|
+
export type WriteDomSnapshotOptions = {
|
|
35
|
+
/** The project folder. Defaults to the current directory. */
|
|
36
|
+
projectDir?: string;
|
|
37
|
+
/**
|
|
38
|
+
* The run folder's id, such as `MANUAL_RUN_ID`. Defaults to `UTAM_SNAPSHOT_RUN_ID`, then the time this
|
|
39
|
+
* process first wrote a snapshot.
|
|
40
|
+
*/
|
|
41
|
+
runId?: string;
|
|
42
|
+
/** Where `UTAM_SNAPSHOT_RUN_ID` is read from. Defaults to `process.env`. */
|
|
43
|
+
env?: EnvLike;
|
|
44
|
+
fs?: SnapshotFileSystem;
|
|
45
|
+
/** Page-object package versions to record; looked up from `projectDir` when omitted. */
|
|
46
|
+
pageObjectPackages?: Record<string, string>;
|
|
47
|
+
};
|
|
48
|
+
export type PruneDomSnapshotsOptions = {
|
|
49
|
+
/** The project folder. Defaults to the current directory. */
|
|
50
|
+
projectDir?: string;
|
|
51
|
+
/** How many run folders to keep, newest first. Defaults to 10. */
|
|
52
|
+
keepRuns?: number;
|
|
53
|
+
fs?: SnapshotFileSystem;
|
|
54
|
+
};
|
|
55
|
+
/**
|
|
56
|
+
* A run id for `UTAM_SNAPSHOT_RUN_ID`: the time as `20261016T120000`.
|
|
57
|
+
*
|
|
58
|
+
* @param date The time; now when omitted.
|
|
59
|
+
*/
|
|
60
|
+
export declare function snapshotRunId(date?: Date): string;
|
|
61
|
+
/**
|
|
62
|
+
* Write a snapshot to `.utam/snapshots/<run id>/<name>.json`, and a copy as
|
|
63
|
+
* `.utam/snapshots/latest.json`, replaced in one step through a temporary file and a rename. The run
|
|
64
|
+
* id comes from `runId`, then `UTAM_SNAPSHOT_RUN_ID`, then the time this process first wrote a snapshot.
|
|
65
|
+
* A name already taken gets a number; files are created exclusively, so two workers can't both take
|
|
66
|
+
* one name. Records the version of each page-object package the project's namespaces map to in the
|
|
67
|
+
* file's `meta.pageObjectPackages`, leaving `snapshot` unchanged; the versions are looked up once per
|
|
68
|
+
* project folder in a process.
|
|
69
|
+
*
|
|
70
|
+
* @param snapshot The snapshot to write.
|
|
71
|
+
* @param options Where and how to write it.
|
|
72
|
+
* @returns The path of the file written, relative to the project folder.
|
|
73
|
+
*/
|
|
74
|
+
export declare function writeDomSnapshot(snapshot: DomSnapshot, options?: WriteDomSnapshotOptions): Promise<string>;
|
|
75
|
+
/**
|
|
76
|
+
* Delete all but the newest `keepRuns` run folders under `.utam/snapshots/`. A folder's age is when
|
|
77
|
+
* it was last written to, so run ids of any form mix: a custom `build-42` and a timestamp compare by
|
|
78
|
+
* when their snapshots were written. Folders written at the same moment compare by name, numbers in
|
|
79
|
+
* it as numbers (`build-9` before `build-10`). `latest.json` is kept, and so is the `manual` folder
|
|
80
|
+
* of captures made by hand, which isn't counted as a run.
|
|
81
|
+
*
|
|
82
|
+
* @param options The project, how many runs to keep, and the file system.
|
|
83
|
+
* @returns The run folders deleted, relative to the project folder.
|
|
84
|
+
*/
|
|
85
|
+
export declare function pruneDomSnapshots(options?: PruneDomSnapshotsOptions): Promise<string[]>;
|
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Copyright (c) 2026, SimplySF.
|
|
3
|
+
*
|
|
4
|
+
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
* you may not use this file except in compliance with the License.
|
|
6
|
+
* You may obtain a copy of the License at
|
|
7
|
+
*
|
|
8
|
+
* http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
*
|
|
10
|
+
* Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
* See the License for the specific language governing permissions and
|
|
14
|
+
* limitations under the License.
|
|
15
|
+
*/
|
|
16
|
+
import * as nodeFs from 'node:fs/promises';
|
|
17
|
+
import * as path from 'node:path';
|
|
18
|
+
import { serializeDomSnapshot } from './format.js';
|
|
19
|
+
import { discoverPageObjectPackages, readNamespaceConfig } from './page-object-packages.js';
|
|
20
|
+
/** Set once per test run (the scaffolded `onPrepare` hook does), so every worker writes to one folder. */
|
|
21
|
+
export const SNAPSHOT_RUN_ID_ENV = 'UTAM_SNAPSHOT_RUN_ID';
|
|
22
|
+
/** Where snapshots are written, relative to the project. */
|
|
23
|
+
export const SNAPSHOTS_DIR = '.utam/snapshots';
|
|
24
|
+
/** The run id for captures made outside a test run, such as from the console; pruning keeps its folder. */
|
|
25
|
+
export const MANUAL_RUN_ID = 'manual';
|
|
26
|
+
/** A copy of the most recent snapshot, relative to the project: the query commands' default. */
|
|
27
|
+
export const LATEST_SNAPSHOT = `${SNAPSHOTS_DIR}/latest.json`;
|
|
28
|
+
const MAX_PART = 60;
|
|
29
|
+
function cleanPart(value) {
|
|
30
|
+
return value
|
|
31
|
+
.replace(/[^A-Za-z0-9-]+/g, '-')
|
|
32
|
+
.replace(/-+/g, '-')
|
|
33
|
+
.replace(/^-|-$/g, '')
|
|
34
|
+
.slice(0, MAX_PART);
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* A run id for `UTAM_SNAPSHOT_RUN_ID`: the time as `20261016T120000`.
|
|
38
|
+
*
|
|
39
|
+
* @param date The time; now when omitted.
|
|
40
|
+
*/
|
|
41
|
+
export function snapshotRunId(date = new Date()) {
|
|
42
|
+
return date.toISOString().replace(/[-:]/g, '').slice(0, 15);
|
|
43
|
+
}
|
|
44
|
+
const MAX_NAME_TRIES = 1000;
|
|
45
|
+
/**
|
|
46
|
+
* Replace `file` in one step, so a reader never sees it half-written while another worker writes it.
|
|
47
|
+
* Where the rename can't replace it (on Windows, while another process has it open or renames onto
|
|
48
|
+
* it too), the temporary file is removed and `file` is written in place instead, as
|
|
49
|
+
* `ensureForceignore` does.
|
|
50
|
+
*/
|
|
51
|
+
async function replaceFile(fs, file, data) {
|
|
52
|
+
const temp = `${file}.${process.pid}-${Math.random().toString(36).slice(2, 10)}.tmp`;
|
|
53
|
+
await fs.writeFile(temp, data);
|
|
54
|
+
try {
|
|
55
|
+
await fs.rename(temp, file);
|
|
56
|
+
}
|
|
57
|
+
catch {
|
|
58
|
+
await fs.rm(temp, { recursive: true, force: true });
|
|
59
|
+
await fs.writeFile(file, data);
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* `<scenario>--<step>` for a failure; `<scenario>--<label>`, or the scenario numbered, otherwise. A
|
|
64
|
+
* capture with no scenario, such as one taken by hand, uses `manual` in its place.
|
|
65
|
+
*/
|
|
66
|
+
function baseName(snapshot) {
|
|
67
|
+
const { meta } = snapshot;
|
|
68
|
+
if (meta.trigger === 'failure') {
|
|
69
|
+
const scenario = cleanPart(meta.scenario ?? '') || 'scenario';
|
|
70
|
+
return { name: `${scenario}--${cleanPart(meta.step ?? '') || 'step'}`, numbered: false };
|
|
71
|
+
}
|
|
72
|
+
const scenario = cleanPart(meta.scenario ?? '') || 'manual';
|
|
73
|
+
const label = cleanPart(meta.label ?? '');
|
|
74
|
+
return label ? { name: `${scenario}--${label}`, numbered: false } : { name: scenario, numbered: true };
|
|
75
|
+
}
|
|
76
|
+
/** The run id for captures made outside a run that set one: the time of this process's first capture. */
|
|
77
|
+
let processRunId;
|
|
78
|
+
/** Each project folder's page-object package versions, looked up once per process. */
|
|
79
|
+
const packageVersions = new Map();
|
|
80
|
+
/**
|
|
81
|
+
* The version of each page-object package the index reads for this project. Packages don't change
|
|
82
|
+
* during a test run, so it's read once per project folder, not on every write.
|
|
83
|
+
*/
|
|
84
|
+
function installedPageObjectPackages(projectDir) {
|
|
85
|
+
const dir = path.resolve(projectDir);
|
|
86
|
+
let versions = packageVersions.get(dir);
|
|
87
|
+
if (!versions) {
|
|
88
|
+
const { packages } = discoverPageObjectPackages(dir, readNamespaceConfig(dir));
|
|
89
|
+
versions = Object.fromEntries(packages.flatMap((pkg) => (pkg.version ? [[pkg.name, pkg.version]] : [])));
|
|
90
|
+
packageVersions.set(dir, versions);
|
|
91
|
+
}
|
|
92
|
+
return versions;
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* Write a snapshot to `.utam/snapshots/<run id>/<name>.json`, and a copy as
|
|
96
|
+
* `.utam/snapshots/latest.json`, replaced in one step through a temporary file and a rename. The run
|
|
97
|
+
* id comes from `runId`, then `UTAM_SNAPSHOT_RUN_ID`, then the time this process first wrote a snapshot.
|
|
98
|
+
* A name already taken gets a number; files are created exclusively, so two workers can't both take
|
|
99
|
+
* one name. Records the version of each page-object package the project's namespaces map to in the
|
|
100
|
+
* file's `meta.pageObjectPackages`, leaving `snapshot` unchanged; the versions are looked up once per
|
|
101
|
+
* project folder in a process.
|
|
102
|
+
*
|
|
103
|
+
* @param snapshot The snapshot to write.
|
|
104
|
+
* @param options Where and how to write it.
|
|
105
|
+
* @returns The path of the file written, relative to the project folder.
|
|
106
|
+
*/
|
|
107
|
+
export async function writeDomSnapshot(snapshot, options = {}) {
|
|
108
|
+
const projectDir = options.projectDir ?? process.cwd();
|
|
109
|
+
const fs = options.fs ?? nodeFs;
|
|
110
|
+
const env = options.env ?? process.env;
|
|
111
|
+
const packages = options.pageObjectPackages ?? installedPageObjectPackages(projectDir);
|
|
112
|
+
// The caller's snapshot is left as it is; only the file gets the versions.
|
|
113
|
+
const written = Object.keys(packages).length > 0
|
|
114
|
+
? { ...snapshot, meta: { ...snapshot.meta, pageObjectPackages: packages } }
|
|
115
|
+
: snapshot;
|
|
116
|
+
// Without a run id, captures share one folder per process, so pruning counts them as one run.
|
|
117
|
+
const dir = path.join(SNAPSHOTS_DIR, cleanPart(options.runId ?? env[SNAPSHOT_RUN_ID_ENV] ?? '') || (processRunId ??= snapshotRunId()));
|
|
118
|
+
await fs.mkdir(path.join(projectDir, dir), { recursive: true });
|
|
119
|
+
const json = serializeDomSnapshot(written);
|
|
120
|
+
const { name, numbered } = baseName(snapshot);
|
|
121
|
+
for (let n = 1;; n++) {
|
|
122
|
+
const file = path.join(dir, numbered ? `${name}--${n}.json` : n === 1 ? `${name}.json` : `${name}-${n}.json`);
|
|
123
|
+
try {
|
|
124
|
+
// Names are tried one at a time: `wx` fails on a name another writer already took.
|
|
125
|
+
// eslint-disable-next-line no-await-in-loop
|
|
126
|
+
await fs.writeFile(path.join(projectDir, file), json, { flag: 'wx' });
|
|
127
|
+
}
|
|
128
|
+
catch (error) {
|
|
129
|
+
if (error.code !== 'EEXIST')
|
|
130
|
+
throw error;
|
|
131
|
+
if (n < MAX_NAME_TRIES)
|
|
132
|
+
continue;
|
|
133
|
+
throw new Error(`Can't name a snapshot in ${dir}: ${MAX_NAME_TRIES} files named after ${name} already exist. Prune the folder or set another ${SNAPSHOT_RUN_ID_ENV}.`, { cause: error });
|
|
134
|
+
}
|
|
135
|
+
// eslint-disable-next-line no-await-in-loop -- runs once, after the loop's last attempt
|
|
136
|
+
await replaceFile(fs, path.join(projectDir, LATEST_SNAPSHOT), json);
|
|
137
|
+
return file;
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
/**
|
|
141
|
+
* Delete all but the newest `keepRuns` run folders under `.utam/snapshots/`. A folder's age is when
|
|
142
|
+
* it was last written to, so run ids of any form mix: a custom `build-42` and a timestamp compare by
|
|
143
|
+
* when their snapshots were written. Folders written at the same moment compare by name, numbers in
|
|
144
|
+
* it as numbers (`build-9` before `build-10`). `latest.json` is kept, and so is the `manual` folder
|
|
145
|
+
* of captures made by hand, which isn't counted as a run.
|
|
146
|
+
*
|
|
147
|
+
* @param options The project, how many runs to keep, and the file system.
|
|
148
|
+
* @returns The run folders deleted, relative to the project folder.
|
|
149
|
+
*/
|
|
150
|
+
export async function pruneDomSnapshots(options = {}) {
|
|
151
|
+
const projectDir = options.projectDir ?? process.cwd();
|
|
152
|
+
const fs = options.fs ?? nodeFs;
|
|
153
|
+
const keepRuns = Math.max(0, options.keepRuns ?? 10);
|
|
154
|
+
let entries;
|
|
155
|
+
try {
|
|
156
|
+
entries = await fs.readdir(path.join(projectDir, SNAPSHOTS_DIR), { withFileTypes: true });
|
|
157
|
+
}
|
|
158
|
+
catch (error) {
|
|
159
|
+
if (error.code === 'ENOENT')
|
|
160
|
+
return [];
|
|
161
|
+
throw error;
|
|
162
|
+
}
|
|
163
|
+
const named = entries
|
|
164
|
+
.filter((entry) => entry.isDirectory() && entry.name !== MANUAL_RUN_ID)
|
|
165
|
+
.map((entry) => entry.name);
|
|
166
|
+
const dated = await Promise.all(named.map(async (name) => {
|
|
167
|
+
try {
|
|
168
|
+
return { name, mtimeMs: (await fs.stat(path.join(projectDir, SNAPSHOTS_DIR, name))).mtimeMs };
|
|
169
|
+
}
|
|
170
|
+
catch (error) {
|
|
171
|
+
// Already gone, perhaps pruned by another run.
|
|
172
|
+
if (error.code === 'ENOENT')
|
|
173
|
+
return undefined;
|
|
174
|
+
throw error;
|
|
175
|
+
}
|
|
176
|
+
}));
|
|
177
|
+
const runs = dated
|
|
178
|
+
.filter((run) => run !== undefined)
|
|
179
|
+
.sort((a, b) => a.mtimeMs - b.mtimeMs || a.name.localeCompare(b.name, 'en', { numeric: true }))
|
|
180
|
+
.map((run) => run.name);
|
|
181
|
+
const removed = runs.slice(0, Math.max(0, runs.length - keepRuns)).map((run) => path.join(SNAPSHOTS_DIR, run));
|
|
182
|
+
await Promise.all(removed.map((dir) => fs.rm(path.join(projectDir, dir), { recursive: true, force: true })));
|
|
183
|
+
return removed;
|
|
184
|
+
}
|
|
185
|
+
//# sourceMappingURL=files.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"files.js","sourceRoot":"","sources":["../../src/snapshot/files.ts"],"names":[],"mappings":"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"}
|