@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.
@@ -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 once `destroy()` returns without throwing.
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 escapes the root, the root is a symbolic link or not a directory,
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 now
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 now.
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 once its directory
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 once {@link REMOVE_TREE_MAX_ATTEMPTS} attempts are exhausted,
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 an escape.
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 escapes the
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 an escape, so the check and its one message are stated once. Read `resolveContained` where an
474
- * escape is an answer rather than a refusal.
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 escapes the root.
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 escapes the scratch directory, the scratch root is missing, a symbolic
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, escapes the scratch directory, or its root is a symbolic
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 escapes the scratch directory or its root is a symbolic link or file.
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 escapes the scratch directory, the target is missing or is not a
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 escapes the scratch directory, the target exists and is not a directory,
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 escapes the scratch directory, the scratch root is missing, a symbolic
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 escapes the scratch directory, when it names the allocation itself
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 escapes or the host refuses a write.
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 bypasses the access check the
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
  *
@@ -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 escapes the root.
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 an escape.
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 escapes the
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 an escape, so the check and its one message are stated once. Read `resolveContained` where an
52
- * escape is an answer rather than a refusal.
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 escapes the root, the root is a symbolic link or not a directory,
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 now.
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 once its directory
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 once {@link REMOVE_TREE_MAX_ATTEMPTS} attempts are exhausted,
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 now
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 once `destroy()` returns without throwing.
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 bypasses the access check the
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