@orkestrel/test 0.0.28 → 0.0.30
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 +5 -5
- package/dist/src/browser/index.d.ts +162 -38
- package/dist/src/browser/index.js +227 -73
- package/dist/src/browser/index.js.map +1 -1
- package/dist/src/core/index.cjs +10 -10
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +1 -1
- package/dist/src/core/index.d.ts +1 -1
- package/dist/src/core/index.js +10 -10
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +31 -12
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +34 -20
- package/dist/src/server/index.d.ts +34 -20
- package/dist/src/server/index.js +31 -13
- package/dist/src/server/index.js.map +1 -1
- package/package.json +7 -7
|
@@ -187,7 +187,7 @@ export declare function createScratch(options?: ScratchOptions): ScratchInterfac
|
|
|
187
187
|
*
|
|
188
188
|
* @param scratch - The scratch directory to destroy.
|
|
189
189
|
* @param options - The time bounds and abort signal.
|
|
190
|
-
* @returns A promise that resolves
|
|
190
|
+
* @returns A promise that resolves after `destroy()` returns without throwing.
|
|
191
191
|
* @throws The abort reason, or an `Error` when a bound is invalid or the budget elapses. The
|
|
192
192
|
* exhaustion error carries the last host refusal as its `cause`.
|
|
193
193
|
* @remarks Default budget: `10000` milliseconds. Default interval: `25` milliseconds. A host holds a
|
|
@@ -215,7 +215,7 @@ export declare function destroyScratch(scratch: ScratchInterface, options?: Wait
|
|
|
215
215
|
* @param root - The absolute scratch directory path.
|
|
216
216
|
* @param target - The relative or absolute contained entry to inspect.
|
|
217
217
|
* @returns True if the root directory and entry exist; false otherwise.
|
|
218
|
-
* @throws Thrown when the target
|
|
218
|
+
* @throws Thrown when the target resolves outside the root, the root is a symbolic link or not a directory,
|
|
219
219
|
* or the host refuses to inspect either path.
|
|
220
220
|
* @remarks Checks containment before inspecting the root. Intermediate links are followed; a
|
|
221
221
|
* dangling final link counts as present. The root's allocation identity is not checked.
|
|
@@ -272,7 +272,7 @@ export declare function isExcluded(key: string, exclusions: readonly string[]):
|
|
|
272
272
|
* pid the host refuses.
|
|
273
273
|
* @throws Nothing. Every host refusal reads as false.
|
|
274
274
|
* @remarks This is an instantaneous observation rather than a claim of ownership. A host reuses a
|
|
275
|
-
* process id after the process holding it exits, so a true answer says some process holds that id
|
|
275
|
+
* process id after the process holding it exits, so a true answer says some process holds that id at the time of the check
|
|
276
276
|
* and never says it is the process the caller started. Two host answers are worth knowing. A POSIX
|
|
277
277
|
* host refuses signal `0` to a process another user owns with `EPERM`, and that refusal reads as
|
|
278
278
|
* false here. A pid of `0` names the caller's own process group on POSIX and the system idle process
|
|
@@ -312,11 +312,11 @@ export declare interface LoopbackInterface {
|
|
|
312
312
|
/**
|
|
313
313
|
* Reports whether two directory identities name the same allocation.
|
|
314
314
|
*
|
|
315
|
-
* @param current - The identity read from the path
|
|
315
|
+
* @param current - The identity read from the path.
|
|
316
316
|
* @param allocation - The identity recorded when the directory was allocated.
|
|
317
317
|
* @returns True if the device, the index node, and the creation time all match; false otherwise.
|
|
318
318
|
* @remarks All three fields are compared because none of them alone identifies an allocation. A
|
|
319
|
-
* device is shared by every directory on one filesystem, an index node is reused
|
|
319
|
+
* device is shared by every directory on one filesystem, an index node is reused after its directory
|
|
320
320
|
* is removed, and a creation time repeats within the host's timestamp resolution.
|
|
321
321
|
*
|
|
322
322
|
* @example
|
|
@@ -332,6 +332,20 @@ export declare interface LoopbackInterface {
|
|
|
332
332
|
*/
|
|
333
333
|
export declare function matchesIdentity(current: ScratchIdentity, allocation: ScratchIdentity): boolean;
|
|
334
334
|
|
|
335
|
+
/**
|
|
336
|
+
* Reads the lowercase hexadecimal SHA-256 digest of a captured file's bytes.
|
|
337
|
+
*
|
|
338
|
+
* @param path - The absolute screenshot path returned by the browser provider.
|
|
339
|
+
* @throws Thrown when the path is relative or the file cannot be read.
|
|
340
|
+
* @remarks Register a browser command that checks Vitest's file-access policy before calling this
|
|
341
|
+
* helper. Only the digest crosses back to the browser; the file is read in Node.
|
|
342
|
+
* @example
|
|
343
|
+
* ```ts
|
|
344
|
+
* const digest = await readCapture(written)
|
|
345
|
+
* ```
|
|
346
|
+
*/
|
|
347
|
+
export declare function readCapture(path: string): Promise<string>;
|
|
348
|
+
|
|
335
349
|
/**
|
|
336
350
|
* Reads the `code` an unknown thrown value carries.
|
|
337
351
|
*
|
|
@@ -406,7 +420,7 @@ export declare const REMOVE_TREE_RETRYABLE_CODES: readonly string[];
|
|
|
406
420
|
* Removes a directory tree, retrying past a transient Windows handle-release race.
|
|
407
421
|
*
|
|
408
422
|
* @param path - The absolute directory to remove.
|
|
409
|
-
* @throws The last removal error
|
|
423
|
+
* @throws The last removal error after {@link REMOVE_TREE_MAX_ATTEMPTS} attempts are exhausted,
|
|
410
424
|
* or immediately for any error whose code is not in {@link REMOVE_TREE_RETRYABLE_CODES}.
|
|
411
425
|
* @remarks On Windows, a directory that a recently exited process still holds as its current
|
|
412
426
|
* working directory throws `EPERM` for a short interval after that process exits. Node's own
|
|
@@ -462,16 +476,16 @@ export declare function removeTree(path: string): void;
|
|
|
462
476
|
export declare function requestUpgrade(port: number, options?: UpgradeOptions): Promise<UpgradeResult>;
|
|
463
477
|
|
|
464
478
|
/**
|
|
465
|
-
* Resolves a target that stays below a root directory, refusing
|
|
479
|
+
* Resolves a target that stays below a root directory, refusing a path outside it.
|
|
466
480
|
*
|
|
467
481
|
* @param root - The absolute root directory.
|
|
468
482
|
* @param target - The relative or absolute target to resolve.
|
|
469
483
|
* @returns The absolute target below the root.
|
|
470
|
-
* @throws An `Error` reading `Path outside scratch directory: <target>` when the target
|
|
484
|
+
* @throws An `Error` reading `Path outside scratch directory: <target>` when the target resolves outside the
|
|
471
485
|
* root.
|
|
472
486
|
* @remarks This is {@link resolveContained} with the refusal every contained scratch operation makes
|
|
473
|
-
* of
|
|
474
|
-
*
|
|
487
|
+
* of a path outside the root, so the check and its one message are stated once. Read `resolveContained` where
|
|
488
|
+
* a path outside the root is an answer rather than a refusal.
|
|
475
489
|
*
|
|
476
490
|
* @example
|
|
477
491
|
* ```ts
|
|
@@ -490,7 +504,7 @@ export declare function requireContained(root: string, target: string): string;
|
|
|
490
504
|
*
|
|
491
505
|
* @param root - The absolute root directory.
|
|
492
506
|
* @param target - The relative or absolute target to resolve.
|
|
493
|
-
* @returns The absolute target, or `undefined` when the target
|
|
507
|
+
* @returns The absolute target, or `undefined` when the target resolves outside the root.
|
|
494
508
|
*/
|
|
495
509
|
export declare function resolveContained(root: string, target: string): string | undefined;
|
|
496
510
|
|
|
@@ -514,7 +528,7 @@ export declare interface ScratchInterface {
|
|
|
514
528
|
* @param target - A relative or absolute file path contained by the scratch directory.
|
|
515
529
|
* @param text - The file contents.
|
|
516
530
|
* @returns The absolute path of the written file.
|
|
517
|
-
* @throws When the target
|
|
531
|
+
* @throws When the target resolves outside the scratch directory, the scratch root is missing, a symbolic
|
|
518
532
|
* link, or a file, or the host refuses to write the file.
|
|
519
533
|
*/
|
|
520
534
|
write(target: string, text: string): string;
|
|
@@ -524,7 +538,7 @@ export declare interface ScratchInterface {
|
|
|
524
538
|
* @param target - A relative or absolute file path contained by the scratch directory.
|
|
525
539
|
* @returns The file contents, or `undefined` when no file can be read, including through a
|
|
526
540
|
* symbolic link whose target is missing.
|
|
527
|
-
* @throws When the path is a directory,
|
|
541
|
+
* @throws When the path is a directory, resolves outside the scratch directory, or its root is a symbolic
|
|
528
542
|
* link or file. Reading follows links, so a link the host cannot resolve — a cycle, for one —
|
|
529
543
|
* surfaces the host's own error rather than `undefined`.
|
|
530
544
|
*/
|
|
@@ -535,7 +549,7 @@ export declare interface ScratchInterface {
|
|
|
535
549
|
* @param target - A relative or absolute path contained by the scratch directory.
|
|
536
550
|
* @returns True if the entry exists, including a symbolic link whose target is
|
|
537
551
|
* missing; false otherwise.
|
|
538
|
-
* @throws When the path
|
|
552
|
+
* @throws When the path resolves outside the scratch directory or its root is a symbolic link or file.
|
|
539
553
|
*/
|
|
540
554
|
has(target: string): boolean;
|
|
541
555
|
/**
|
|
@@ -544,7 +558,7 @@ export declare interface ScratchInterface {
|
|
|
544
558
|
* @param target - A relative or absolute directory path contained by the scratch directory.
|
|
545
559
|
* Default: the scratch root.
|
|
546
560
|
* @returns The sorted entry names, without their parent paths.
|
|
547
|
-
* @throws When the path
|
|
561
|
+
* @throws When the path resolves outside the scratch directory, the target is missing or is not a
|
|
548
562
|
* directory, or the scratch root is a symbolic link or file.
|
|
549
563
|
*/
|
|
550
564
|
names(target?: string): readonly string[];
|
|
@@ -553,7 +567,7 @@ export declare interface ScratchInterface {
|
|
|
553
567
|
*
|
|
554
568
|
* @param target - A relative or absolute directory path contained by the scratch directory.
|
|
555
569
|
* @returns The absolute path of the directory.
|
|
556
|
-
* @throws When the path
|
|
570
|
+
* @throws When the path resolves outside the scratch directory, the target exists and is not a directory,
|
|
557
571
|
* or the scratch root is missing, a symbolic link, or a file.
|
|
558
572
|
*/
|
|
559
573
|
ensure(target: string): string;
|
|
@@ -567,7 +581,7 @@ export declare interface ScratchInterface {
|
|
|
567
581
|
* destination, but its exact text is not promised. The path may name a destination outside the
|
|
568
582
|
* scratch directory and is not containment-checked.
|
|
569
583
|
* @returns The absolute path of the created link, whatever host mechanism created it.
|
|
570
|
-
* @throws When the target
|
|
584
|
+
* @throws When the target resolves outside the scratch directory, the scratch root is missing, a symbolic
|
|
571
585
|
* link, or a file, or the host refuses to create the link, including a host that creates no
|
|
572
586
|
* symbolic link when the source names an existing non-directory.
|
|
573
587
|
* @remarks {@link createLink} owns the host-specific link mechanism.
|
|
@@ -578,7 +592,7 @@ export declare interface ScratchInterface {
|
|
|
578
592
|
*
|
|
579
593
|
* @param target - A relative or absolute path contained by the scratch directory. A missing target
|
|
580
594
|
* is a no-op. A final symbolic link is removed without following it, so its destination survives.
|
|
581
|
-
* @throws When the target
|
|
595
|
+
* @throws When the target resolves outside the scratch directory, when it names the allocation itself
|
|
582
596
|
* lexically or through an intermediate symbolic link, when the scratch root is missing, a symbolic
|
|
583
597
|
* link, or a file, or when the host refuses to remove the target.
|
|
584
598
|
*/
|
|
@@ -608,7 +622,7 @@ export declare interface ScratchOptions {
|
|
|
608
622
|
readonly prefix?: string;
|
|
609
623
|
/**
|
|
610
624
|
* Holds the files to write on allocation, keyed by path below the scratch directory. Allocation
|
|
611
|
-
* removes its directory and rethrows when a key
|
|
625
|
+
* removes its directory and rethrows when a key resolves outside it or the host refuses a write.
|
|
612
626
|
*/
|
|
613
627
|
readonly files?: Readonly<Record<string, string>>;
|
|
614
628
|
}
|
|
@@ -702,7 +716,7 @@ export declare function supportsFileLinks(): boolean;
|
|
|
702
716
|
* remove it afterwards, both propagate.
|
|
703
717
|
* @remarks POSIX reports `mode & 0o777 === 0o700` and Windows reports `0o666` regardless, so the
|
|
704
718
|
* answer is true on POSIX and false on Windows. Storing a bit is a narrower question than enforcing
|
|
705
|
-
* it: a POSIX host running as uid `0` stores every bit faithfully and
|
|
719
|
+
* it: a POSIX host running as uid `0` stores every bit faithfully and is exempt from the access check the
|
|
706
720
|
* bits describe, so a caller that needs a permission to be enforced probes the refusal it needs
|
|
707
721
|
* rather than reading this.
|
|
708
722
|
*
|
package/dist/src/server/index.js
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import { Buffer } from "node:buffer";
|
|
2
|
+
import { createHash } from "node:crypto";
|
|
2
3
|
import { lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
|
|
4
|
+
import { readFile } from "node:fs/promises";
|
|
3
5
|
import { request } from "node:http";
|
|
4
6
|
import { tmpdir } from "node:os";
|
|
5
7
|
import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
|
|
@@ -27,11 +29,27 @@ var REMOVE_TREE_RETRYABLE_CODES = Object.freeze([
|
|
|
27
29
|
//#endregion
|
|
28
30
|
//#region src/server/helpers.ts
|
|
29
31
|
/**
|
|
32
|
+
* Reads the lowercase hexadecimal SHA-256 digest of a captured file's bytes.
|
|
33
|
+
*
|
|
34
|
+
* @param path - The absolute screenshot path returned by the browser provider.
|
|
35
|
+
* @throws Thrown when the path is relative or the file cannot be read.
|
|
36
|
+
* @remarks Register a browser command that checks Vitest's file-access policy before calling this
|
|
37
|
+
* helper. Only the digest crosses back to the browser; the file is read in Node.
|
|
38
|
+
* @example
|
|
39
|
+
* ```ts
|
|
40
|
+
* const digest = await readCapture(written)
|
|
41
|
+
* ```
|
|
42
|
+
*/
|
|
43
|
+
async function readCapture(path) {
|
|
44
|
+
if (!isAbsolute(path)) throw new Error(`Capture path must be absolute: ${path}`);
|
|
45
|
+
return createHash("sha256").update(await readFile(path)).digest("hex");
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
30
48
|
* Resolves a target that stays below a root directory.
|
|
31
49
|
*
|
|
32
50
|
* @param root - The absolute root directory.
|
|
33
51
|
* @param target - The relative or absolute target to resolve.
|
|
34
|
-
* @returns The absolute target, or `undefined` when the target
|
|
52
|
+
* @returns The absolute target, or `undefined` when the target resolves outside the root.
|
|
35
53
|
*/
|
|
36
54
|
function resolveContained(root, target) {
|
|
37
55
|
const candidate = resolve(root, target);
|
|
@@ -40,16 +58,16 @@ function resolveContained(root, target) {
|
|
|
40
58
|
return candidate;
|
|
41
59
|
}
|
|
42
60
|
/**
|
|
43
|
-
* Resolves a target that stays below a root directory, refusing
|
|
61
|
+
* Resolves a target that stays below a root directory, refusing a path outside it.
|
|
44
62
|
*
|
|
45
63
|
* @param root - The absolute root directory.
|
|
46
64
|
* @param target - The relative or absolute target to resolve.
|
|
47
65
|
* @returns The absolute target below the root.
|
|
48
|
-
* @throws An `Error` reading `Path outside scratch directory: <target>` when the target
|
|
66
|
+
* @throws An `Error` reading `Path outside scratch directory: <target>` when the target resolves outside the
|
|
49
67
|
* root.
|
|
50
68
|
* @remarks This is {@link resolveContained} with the refusal every contained scratch operation makes
|
|
51
|
-
* of
|
|
52
|
-
*
|
|
69
|
+
* of a path outside the root, so the check and its one message are stated once. Read `resolveContained` where
|
|
70
|
+
* a path outside the root is an answer rather than a refusal.
|
|
53
71
|
*
|
|
54
72
|
* @example
|
|
55
73
|
* ```ts
|
|
@@ -95,7 +113,7 @@ function readIdentity(status) {
|
|
|
95
113
|
* @param root - The absolute scratch directory path.
|
|
96
114
|
* @param target - The relative or absolute contained entry to inspect.
|
|
97
115
|
* @returns True if the root directory and entry exist; false otherwise.
|
|
98
|
-
* @throws Thrown when the target
|
|
116
|
+
* @throws Thrown when the target resolves outside the root, the root is a symbolic link or not a directory,
|
|
99
117
|
* or the host refuses to inspect either path.
|
|
100
118
|
* @remarks Checks containment before inspecting the root. Intermediate links are followed; a
|
|
101
119
|
* dangling final link counts as present. The root's allocation identity is not checked.
|
|
@@ -147,11 +165,11 @@ function readErrorCode(error) {
|
|
|
147
165
|
/**
|
|
148
166
|
* Reports whether two directory identities name the same allocation.
|
|
149
167
|
*
|
|
150
|
-
* @param current - The identity read from the path
|
|
168
|
+
* @param current - The identity read from the path.
|
|
151
169
|
* @param allocation - The identity recorded when the directory was allocated.
|
|
152
170
|
* @returns True if the device, the index node, and the creation time all match; false otherwise.
|
|
153
171
|
* @remarks All three fields are compared because none of them alone identifies an allocation. A
|
|
154
|
-
* device is shared by every directory on one filesystem, an index node is reused
|
|
172
|
+
* device is shared by every directory on one filesystem, an index node is reused after its directory
|
|
155
173
|
* is removed, and a creation time repeats within the host's timestamp resolution.
|
|
156
174
|
*
|
|
157
175
|
* @example
|
|
@@ -225,7 +243,7 @@ function createLink(path, source) {
|
|
|
225
243
|
* Removes a directory tree, retrying past a transient Windows handle-release race.
|
|
226
244
|
*
|
|
227
245
|
* @param path - The absolute directory to remove.
|
|
228
|
-
* @throws The last removal error
|
|
246
|
+
* @throws The last removal error after {@link REMOVE_TREE_MAX_ATTEMPTS} attempts are exhausted,
|
|
229
247
|
* or immediately for any error whose code is not in {@link REMOVE_TREE_RETRYABLE_CODES}.
|
|
230
248
|
* @remarks On Windows, a directory that a recently exited process still holds as its current
|
|
231
249
|
* working directory throws `EPERM` for a short interval after that process exits. Node's own
|
|
@@ -335,7 +353,7 @@ function readInventory(root, targets, options) {
|
|
|
335
353
|
* pid the host refuses.
|
|
336
354
|
* @throws Nothing. Every host refusal reads as false.
|
|
337
355
|
* @remarks This is an instantaneous observation rather than a claim of ownership. A host reuses a
|
|
338
|
-
* process id after the process holding it exits, so a true answer says some process holds that id
|
|
356
|
+
* process id after the process holding it exits, so a true answer says some process holds that id at the time of the check
|
|
339
357
|
* and never says it is the process the caller started. Two host answers are worth knowing. A POSIX
|
|
340
358
|
* host refuses signal `0` to a process another user owns with `EPERM`, and that refusal reads as
|
|
341
359
|
* false here. A pid of `0` names the caller's own process group on POSIX and the system idle process
|
|
@@ -442,7 +460,7 @@ async function waitForSocketClose(socket, options) {
|
|
|
442
460
|
*
|
|
443
461
|
* @param scratch - The scratch directory to destroy.
|
|
444
462
|
* @param options - The time bounds and abort signal.
|
|
445
|
-
* @returns A promise that resolves
|
|
463
|
+
* @returns A promise that resolves after `destroy()` returns without throwing.
|
|
446
464
|
* @throws The abort reason, or an `Error` when a bound is invalid or the budget elapses. The
|
|
447
465
|
* exhaustion error carries the last host refusal as its `cause`.
|
|
448
466
|
* @remarks Default budget: `10000` milliseconds. Default interval: `25` milliseconds. A host holds a
|
|
@@ -653,7 +671,7 @@ function supportsFileLinks() {
|
|
|
653
671
|
* remove it afterwards, both propagate.
|
|
654
672
|
* @remarks POSIX reports `mode & 0o777 === 0o700` and Windows reports `0o666` regardless, so the
|
|
655
673
|
* answer is true on POSIX and false on Windows. Storing a bit is a narrower question than enforcing
|
|
656
|
-
* it: a POSIX host running as uid `0` stores every bit faithfully and
|
|
674
|
+
* it: a POSIX host running as uid `0` stores every bit faithfully and is exempt from the access check the
|
|
657
675
|
* bits describe, so a caller that needs a permission to be enforced probes the refusal it needs
|
|
658
676
|
* rather than reading this.
|
|
659
677
|
*
|
|
@@ -1024,6 +1042,6 @@ function createCookieJar() {
|
|
|
1024
1042
|
};
|
|
1025
1043
|
}
|
|
1026
1044
|
//#endregion
|
|
1027
|
-
export { REMOVE_TREE_MAX_ATTEMPTS, REMOVE_TREE_RETRYABLE_CODES, REMOVE_TREE_RETRY_DELAY_MS, chooseFiles, createCookieJar, createLink, createLoopback, createScratch, destroyScratch, hasScratchPath, isExcluded, isRunning, matchesIdentity, readErrorCode, readIdentity, readInventory, removeTree, requestUpgrade, requireContained, resolveContained, supportsBytes, supportsCase, supportsDirectoryLinks, supportsFileLinks, supportsMode, waitForSocketClose };
|
|
1045
|
+
export { REMOVE_TREE_MAX_ATTEMPTS, REMOVE_TREE_RETRYABLE_CODES, REMOVE_TREE_RETRY_DELAY_MS, chooseFiles, createCookieJar, createLink, createLoopback, createScratch, destroyScratch, hasScratchPath, isExcluded, isRunning, matchesIdentity, readCapture, readErrorCode, readIdentity, readInventory, removeTree, requestUpgrade, requireContained, resolveContained, supportsBytes, supportsCase, supportsDirectoryLinks, supportsFileLinks, supportsMode, waitForSocketClose };
|
|
1028
1046
|
|
|
1029
1047
|
//# sourceMappingURL=index.js.map
|