@orkestrel/test 0.0.37 → 0.0.39

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.
@@ -1,9 +1,18 @@
1
1
  import type { BigIntStats } from 'node:fs';
2
+ import { Buffer as Buffer_2 } from 'node:buffer';
2
3
  import type { ChooserRequest } from '@orkestrel/test';
3
4
  import type { FrameLocator } from 'playwright';
5
+ import type { Guard } from '@orkestrel/contract';
4
6
  import type { Page } from 'playwright';
7
+ import type { Reporter } from 'vitest/node';
8
+ import type { SerializedError } from 'vitest/node';
5
9
  import type { Server } from 'node:net';
6
10
  import type { Socket } from 'node:net';
11
+ import type { TestCase } from 'vitest/node';
12
+ import type { TestModule } from 'vitest/node';
13
+ import type { TestRunEndReason } from 'vitest/node';
14
+ import type { TestSpecification } from 'vitest/node';
15
+ import type { Vitest } from 'vitest/node';
7
16
  import type { WaitOptions } from '@orkestrel/test';
8
17
 
9
18
  /**
@@ -53,6 +62,51 @@ export declare interface ChooserContext {
53
62
  readonly iframe: FrameLocator;
54
63
  }
55
64
 
65
+ /**
66
+ * Computes where every run a progress file holds stands, one run per writing process.
67
+ *
68
+ * @param events - The file's lines, in file order, from any number of processes.
69
+ * @param now - The wall-clock time of the reading, in milliseconds since the Unix epoch.
70
+ * @returns One run per process id in first-seen order, each computed by `computeProgressRun` from
71
+ * that process's lines alone. A process whose lines no `init` line opens contributes no run.
72
+ *
73
+ * @example
74
+ * ```ts
75
+ * import { computeProgress } from '@orkestrel/test/server'
76
+ *
77
+ * computeProgress(
78
+ * [
79
+ * { event: 'init', version: 1, wall: 1_000, bail: 0, time: 0, pid: 7 },
80
+ * { event: 'init', version: 1, wall: 1_000, bail: 0, time: 0, pid: 8 },
81
+ * ],
82
+ * 4_000,
83
+ * ).map((run) => [run.pid, run.elapsed]) // [[7, 3000], [8, 3000]]
84
+ * ```
85
+ */
86
+ export declare function computeProgress(events: readonly ProgressEvent[], now: number): readonly ProgressRun[];
87
+
88
+ /**
89
+ * Computes where the run one process wrote stands, from its last `init` line on.
90
+ *
91
+ * @param events - The lines one process wrote, in file order. Every line must carry the same `pid`;
92
+ * lines of several processes read as one run and miscompute it, so pass a whole file to
93
+ * `computeProgress`, which groups them first.
94
+ * @param now - The wall-clock time of the reading, in milliseconds since the Unix epoch, which a
95
+ * live run's elapsed time is measured to.
96
+ * @returns The run, or `undefined` when no `init` line opens it.
97
+ *
98
+ * @example
99
+ * ```ts
100
+ * import { computeProgressRun } from '@orkestrel/test/server'
101
+ *
102
+ * computeProgressRun(
103
+ * [{ event: 'init', version: 1, wall: 1_000, bail: 1, time: 0, pid: 7 }],
104
+ * 4_000,
105
+ * )?.elapsed // 3000
106
+ * ```
107
+ */
108
+ export declare function computeProgressRun(events: readonly ProgressEvent[], now: number): ProgressRun | undefined;
109
+
56
110
  /** Holds a name-keyed cookie store a test drives one origin with, filled from real responses. */
57
111
  export declare interface CookieJarInterface {
58
112
  /**
@@ -225,6 +279,76 @@ export declare function createScratch(options?: ScratchOptions): ScratchInterfac
225
279
  */
226
280
  export declare function destroyScratch(scratch: ScratchInterface, options?: WaitOptions): Promise<void>;
227
281
 
282
+ /**
283
+ * Extracts the message line and location a progress line keeps from one Vitest error.
284
+ *
285
+ * @param error - The serialized error Vitest reports.
286
+ * @param root - The run's root directory, which the location is relative to.
287
+ * @returns The error's name and first message line, capped at `PROGRESS_MESSAGE_LIMIT` characters,
288
+ * and the first stack frame outside `node_modules`, or the first frame when every frame sits there.
289
+ *
290
+ * @example
291
+ * ```ts
292
+ * import { extractProgressError } from '@orkestrel/test/server'
293
+ *
294
+ * extractProgressError(
295
+ * {
296
+ * name: 'AssertionError',
297
+ * message: 'expected 1 to be 2\nfull diff',
298
+ * stacks: [{ method: '', file: '/work/tests/a.test.ts', line: 4, column: 9 }],
299
+ * },
300
+ * '/work',
301
+ * )
302
+ * // { message: 'AssertionError: expected 1 to be 2', location: 'tests/a.test.ts:4:9' }
303
+ * ```
304
+ */
305
+ export declare function extractProgressError(error: SerializedError, root: string): ProgressError;
306
+
307
+ /**
308
+ * Extracts the progress lines a text holds, skipping a partial last line.
309
+ *
310
+ * @param text - Progress file text, live or finished.
311
+ * @returns Each complete line's event, in file order. The text after the last line feed is a line
312
+ * the writer can still be appending, so it is never decoded.
313
+ * @throws Thrown when a complete line is not valid JSON, is not a progress event, or is an `init`
314
+ * line of another format version.
315
+ *
316
+ * @example
317
+ * ```ts
318
+ * import { extractProgressEvents } from '@orkestrel/test/server'
319
+ *
320
+ * extractProgressEvents(
321
+ * '{"event":"cancel","reason":"test-failure","wall":1,"time":2,"pid":3}\n{"event":"ca',
322
+ * ).length // 1
323
+ * ```
324
+ */
325
+ export declare function extractProgressEvents(text: string): readonly ProgressEvent[];
326
+
327
+ /**
328
+ * Filters the progress lines of one event.
329
+ *
330
+ * @typeParam TName - The event to keep.
331
+ * @param events - The lines to filter.
332
+ * @param name - The event to keep.
333
+ * @returns The matching lines in order.
334
+ *
335
+ * @example
336
+ * ```ts
337
+ * import { filterProgressEvents } from '@orkestrel/test/server'
338
+ *
339
+ * filterProgressEvents(
340
+ * [
341
+ * { event: 'cancel', reason: 'test-failure', wall: 1, time: 2, pid: 3 },
342
+ * { event: 'ready', project: 'unit', id: 'a', name: 'adds', time: 3, pid: 3 },
343
+ * ],
344
+ * 'cancel',
345
+ * ).length // 1
346
+ * ```
347
+ */
348
+ export declare function filterProgressEvents<TName extends ProgressEvent['event']>(events: readonly ProgressEvent[], name: TName): ReadonlyArray<Extract<ProgressEvent, {
349
+ readonly event: TName;
350
+ }>>;
351
+
228
352
  /**
229
353
  * Reports whether a contained entry exists under a scratch directory without following its final link.
230
354
  *
@@ -280,6 +404,32 @@ export declare interface InventoryOptions {
280
404
  */
281
405
  export declare function isExcluded(key: string, exclusions: readonly string[]): boolean;
282
406
 
407
+ /**
408
+ * Checks whether a value is one error a progress line carries.
409
+ *
410
+ * @example
411
+ * ```ts
412
+ * import { isProgressError } from '@orkestrel/test/server'
413
+ *
414
+ * isProgressError({ message: 'Error: refused', location: 'tests/a.test.ts:4:9' }) // true
415
+ * isProgressError({ location: 'tests/a.test.ts:4:9' }) // false
416
+ * ```
417
+ */
418
+ export declare const isProgressError: Guard<ProgressError>;
419
+
420
+ /**
421
+ * Checks whether a value is one line of a progress file.
422
+ *
423
+ * @example
424
+ * ```ts
425
+ * import { isProgressEvent } from '@orkestrel/test/server'
426
+ *
427
+ * isProgressEvent({ event: 'cancel', reason: 'test-failure', wall: 1, time: 2, pid: 3 }) // true
428
+ * isProgressEvent({ event: 'cancel', reason: 'test-failure' }) // false
429
+ * ```
430
+ */
431
+ export declare const isProgressEvent: Guard<ProgressEvent>;
432
+
283
433
  /**
284
434
  * Reports whether a process id names a live process.
285
435
  *
@@ -348,6 +498,349 @@ export declare interface LoopbackInterface {
348
498
  */
349
499
  export declare function matchesIdentity(current: ScratchIdentity, allocation: ScratchIdentity): boolean;
350
500
 
501
+ /**
502
+ * Reports whether a collected case is one the run plans to report.
503
+ *
504
+ * @param test - A Vitest case, or any value carrying its `options.mode`.
505
+ * @returns True if the case's mode is `run` or `only`; false for a case that `skip`, `todo`, or a
506
+ * name filter removed.
507
+ *
508
+ * @example
509
+ * ```ts
510
+ * import { matchesPlannedCase } from '@orkestrel/test/server'
511
+ *
512
+ * matchesPlannedCase({ options: { mode: 'run' } }) // true
513
+ * matchesPlannedCase({ options: { mode: 'skip' } }) // false
514
+ * ```
515
+ */
516
+ export declare function matchesPlannedCase(test: {
517
+ readonly options: {
518
+ readonly mode: string;
519
+ };
520
+ }): boolean;
521
+
522
+ /**
523
+ * Normalizes a module or stack-frame path to the form a progress line carries.
524
+ *
525
+ * @param file - The path Vitest reports, a Vite `/@fs/` path included.
526
+ * @param root - The run's root directory.
527
+ * @returns The path relative to the root with `/` separators, or the path unchanged when it resolves
528
+ * outside the root.
529
+ *
530
+ * @example
531
+ * ```ts
532
+ * import { normalizeProgressPath } from '@orkestrel/test/server'
533
+ *
534
+ * normalizeProgressPath('/work/tests/a.test.ts', '/work') // 'tests/a.test.ts'
535
+ * normalizeProgressPath('/elsewhere/b.ts', '/work') // '/elsewhere/b.ts'
536
+ * ```
537
+ */
538
+ export declare function normalizeProgressPath(file: string, root: string): string;
539
+
540
+ /**
541
+ * Names the label a rendered progress reading prints for each failure relation.
542
+ */
543
+ export declare const PROGRESS_LABELS: Readonly<Record<ProgressRelation, string>>;
544
+
545
+ /**
546
+ * Caps the characters a progress error message keeps.
547
+ */
548
+ export declare const PROGRESS_MESSAGE_LIMIT = 300;
549
+
550
+ /**
551
+ * Names the format version a progress file's `init` line carries; a reader refuses any other.
552
+ */
553
+ export declare const PROGRESS_VERSION = 1;
554
+
555
+ /** Represents the first cancel a run recorded. */
556
+ export declare interface ProgressCancel {
557
+ /** Holds the reason Vitest delivered. */
558
+ readonly reason: string;
559
+ /** Holds the milliseconds since the reporter started at which the cancel was written. */
560
+ readonly time: number;
561
+ }
562
+
563
+ /** Represents the line a reporter writes each time Vitest cancels the run. */
564
+ export declare interface ProgressCancelEvent extends ProgressStamp {
565
+ /** Names the line's event. */
566
+ readonly event: 'cancel';
567
+ /** Holds the reason Vitest's `onCancel` delivers, such as `test-failure` for a bail. */
568
+ readonly reason: string;
569
+ /** Holds the wall-clock time of the line, in milliseconds since the Unix epoch. */
570
+ readonly wall: number;
571
+ }
572
+
573
+ /** Represents a case that started and has not reported a result. */
574
+ export declare interface ProgressCase {
575
+ /** Names the Vitest project. */
576
+ readonly project: string;
577
+ /** Holds the case's full name. */
578
+ readonly name: string;
579
+ /** Holds how long the case has been running, in milliseconds. */
580
+ readonly duration: number;
581
+ }
582
+
583
+ /** Represents the line a reporter writes once for each planned case's result. */
584
+ export declare interface ProgressCaseEvent extends ProgressStamp {
585
+ /** Names the line's event. */
586
+ readonly event: 'case';
587
+ /** Names the Vitest project. */
588
+ readonly project: string;
589
+ /** Holds the module path relative to the run's root. */
590
+ readonly module: string;
591
+ /** Holds Vitest's id for the case. */
592
+ readonly id: string;
593
+ /** Holds the case's full name, its suites joined by ` > `. */
594
+ readonly name: string;
595
+ /** Holds the case's result state. */
596
+ readonly state: ProgressCaseState;
597
+ /** Holds how long the case ran, in whole milliseconds. Absent when Vitest reports no diagnostic. */
598
+ readonly duration?: number;
599
+ /**
600
+ * Holds the wall-clock time the case started, in milliseconds since the Unix epoch. Absent when
601
+ * Vitest reports no diagnostic.
602
+ */
603
+ readonly start?: number;
604
+ /** Lists each error of a failed case. Absent unless the state is `failed`. */
605
+ readonly errors?: readonly ProgressError[];
606
+ }
607
+
608
+ /** Names the state a case result reports, mirroring Vitest's `TestState`. */
609
+ export declare type ProgressCaseState = 'passed' | 'failed' | 'skipped' | 'pending';
610
+
611
+ /** Represents the line a reporter writes when Vitest collects one module's cases. */
612
+ export declare interface ProgressCollectedEvent extends ProgressStamp {
613
+ /** Names the line's event. */
614
+ readonly event: 'collected';
615
+ /** Names the Vitest project. */
616
+ readonly project: string;
617
+ /** Holds the module path relative to the run's root. */
618
+ readonly module: string;
619
+ /** Counts the collected cases whose mode is `run` or `only`, the cases the run plans to report. */
620
+ readonly planned: number;
621
+ /** Lists the errors the module raised while it was collected. */
622
+ readonly errors: readonly ProgressError[];
623
+ }
624
+
625
+ /** Represents the line a reporter writes when a run ends. */
626
+ export declare interface ProgressEndEvent extends ProgressStamp {
627
+ /** Names the line's event. */
628
+ readonly event: 'end';
629
+ /** Holds why the run ended. */
630
+ readonly reason: ProgressEndReason;
631
+ /** Holds the reporter's own time across every hook since it was initialized, in milliseconds. */
632
+ readonly overhead: number;
633
+ /** Lists the errors Vitest reported outside any case. */
634
+ readonly unhandled: readonly ProgressError[];
635
+ }
636
+
637
+ /** Names why a run ended, mirroring Vitest's `TestRunEndReason`. */
638
+ export declare type ProgressEndReason = 'passed' | 'interrupted' | 'failed';
639
+
640
+ /** Represents one error a progress line carries: its first message line and where it was thrown. */
641
+ export declare interface ProgressError {
642
+ /** Holds the error's name and the first line of its message, stripped of terminal colour codes. */
643
+ readonly message: string;
644
+ /**
645
+ * Names the first stack frame outside `node_modules` as `file:line:column`, relative to the run's
646
+ * root, or the first frame when every frame sits in `node_modules`. Absent when the error carries
647
+ * no parsed stack.
648
+ */
649
+ readonly location?: string;
650
+ }
651
+
652
+ /** Represents one line of a progress file, discriminated by `event`. */
653
+ export declare type ProgressEvent = ProgressInitEvent | ProgressStartEvent | ProgressCollectedEvent | ProgressReadyEvent | ProgressCaseEvent | ProgressCancelEvent | ProgressModuleEvent | ProgressEndEvent;
654
+
655
+ /** Represents one failed case, or one module that failed to collect, in a progress reading. */
656
+ export declare interface ProgressFailure {
657
+ /** Names the Vitest project. */
658
+ readonly project: string;
659
+ /** Holds the module path relative to the run's root. */
660
+ readonly module: string;
661
+ /** Holds the case's full name, or `undefined` for a module that failed to collect. */
662
+ readonly name: string | undefined;
663
+ /** Holds the milliseconds since the reporter started at which the line was written. */
664
+ readonly time: number;
665
+ /** Names how the failure relates to the run's bail. */
666
+ readonly relation: ProgressRelation;
667
+ /** Holds the first error, or `undefined` when the line carried none. */
668
+ readonly error: ProgressError | undefined;
669
+ }
670
+
671
+ /** Represents the line a reporter writes when Vitest initializes it. */
672
+ export declare interface ProgressInitEvent extends ProgressStamp {
673
+ /** Names the line's event. */
674
+ readonly event: 'init';
675
+ /** Holds the format version the line stream follows. */
676
+ readonly version: number;
677
+ /** Holds the wall-clock time of the line, in milliseconds since the Unix epoch. */
678
+ readonly wall: number;
679
+ /** Holds the run's `bail` setting; `0` runs every case. */
680
+ readonly bail: number;
681
+ }
682
+
683
+ /** Represents the line a reporter writes when a module finishes. */
684
+ export declare interface ProgressModuleEvent extends ProgressStamp {
685
+ /** Names the line's event. */
686
+ readonly event: 'module';
687
+ /** Names the Vitest project. */
688
+ readonly project: string;
689
+ /** Holds the module path relative to the run's root. */
690
+ readonly module: string;
691
+ /** Holds the module's final state. */
692
+ readonly state: ProgressModuleState;
693
+ /** Holds how long the module ran, in whole milliseconds. */
694
+ readonly duration: number;
695
+ }
696
+
697
+ /** Names the state a finished module reports, mirroring Vitest's `TestModuleState`. */
698
+ export declare type ProgressModuleState = 'passed' | 'failed' | 'skipped' | 'pending' | 'queued';
699
+
700
+ /** Represents one project's tallies in a progress reading. */
701
+ export declare interface ProgressProject {
702
+ /** Names the Vitest project. */
703
+ readonly name: string;
704
+ /** Counts the cases the project's collected modules plan to report. */
705
+ readonly planned: number;
706
+ /** Counts the cases that reported a result. */
707
+ readonly done: number;
708
+ /** Counts the cases that passed. */
709
+ readonly passed: number;
710
+ /** Counts the cases that failed and the modules that failed to collect. */
711
+ readonly failed: number;
712
+ /** Counts the planned cases that reported a skip at run time, a bail-cut case included. */
713
+ readonly skipped: number;
714
+ /** Counts the modules the run started for the project. */
715
+ readonly modules: number;
716
+ /** Counts the modules Vitest has collected for the project. */
717
+ readonly collected: number;
718
+ }
719
+
720
+ /** Represents the line a reporter writes when a planned case starts. */
721
+ export declare interface ProgressReadyEvent extends ProgressStamp {
722
+ /** Names the line's event. */
723
+ readonly event: 'ready';
724
+ /** Names the Vitest project. */
725
+ readonly project: string;
726
+ /** Holds Vitest's id for the case. */
727
+ readonly id: string;
728
+ /** Holds the case's full name, its suites joined by ` > `. */
729
+ readonly name: string;
730
+ }
731
+
732
+ /**
733
+ * Names how a failure relates to the run's bail: `first` is the earliest failure, `bail` is a
734
+ * failure past the bail setting whose result arrived or whose case ended after the first cancel, and
735
+ * `later` is any other failure.
736
+ */
737
+ export declare type ProgressRelation = 'first' | 'bail' | 'later';
738
+
739
+ /**
740
+ * Appends one JSON line per Vitest run event to the file `--outputFile.progress` names, so a live
741
+ * run's progress and each failure's first error can be read before the run ends.
742
+ *
743
+ * @example
744
+ * ```ts
745
+ * import { defineConfig } from 'vitest/config'
746
+ * import { ProgressReporter } from '@orkestrel/test/server'
747
+ *
748
+ * export default defineConfig({
749
+ * test: {
750
+ * reporters: ['dot', new ProgressReporter()],
751
+ * outputFile: { progress: 'tmp/runs/progress.jsonl' },
752
+ * },
753
+ * })
754
+ * ```
755
+ */
756
+ export declare class ProgressReporter implements Reporter {
757
+ #private;
758
+ constructor();
759
+ onInit(vitest: Vitest): void;
760
+ onTestModuleQueued(): void;
761
+ onTestRunStart(specifications: readonly TestSpecification[]): void;
762
+ onTestModuleCollected(module: TestModule): void;
763
+ onTestCaseReady(test: TestCase): void;
764
+ onTestCaseResult(test: TestCase): void;
765
+ onTestModuleEnd(module: TestModule): void;
766
+ onTestRunEnd(_modules: readonly TestModule[], unhandled: readonly SerializedError[], reason: TestRunEndReason): void;
767
+ }
768
+
769
+ /** Represents where one run stands, read from its progress lines. */
770
+ export declare interface ProgressRun {
771
+ /** Holds the id of the process that wrote the run. */
772
+ readonly pid: number;
773
+ /**
774
+ * Holds the wall-clock time of the `init` line that opens the run, in milliseconds since the Unix
775
+ * epoch, which tells apart runs one file holds.
776
+ */
777
+ readonly wall: number;
778
+ /** Names the run's state. */
779
+ readonly state: ProgressState;
780
+ /** Holds the run's `bail` setting; `0` runs every case. */
781
+ readonly bail: number;
782
+ /** Holds the milliseconds the run has taken, up to its end or to the reading. */
783
+ readonly elapsed: number;
784
+ /** Counts the cases that reported a result, across every project. */
785
+ readonly done: number;
786
+ /** Counts the cases the collected modules plan to report, across every project. */
787
+ readonly planned: number;
788
+ /**
789
+ * True if the run started and every module it started has been collected, so `planned` is exact;
790
+ * false otherwise.
791
+ */
792
+ readonly exact: boolean;
793
+ /** Holds the results per minute since the first case started, or `undefined` before one. */
794
+ readonly rate: number | undefined;
795
+ /**
796
+ * Holds the estimated milliseconds left, or `undefined` once the run ended, before a rate exists,
797
+ * or while a module is still uncollected.
798
+ */
799
+ readonly remaining: number | undefined;
800
+ /** Lists each project's tallies, in first-seen order. */
801
+ readonly projects: readonly ProgressProject[];
802
+ /** Lists the cases still running while the run is live, and none after it ends. */
803
+ readonly running: readonly ProgressCase[];
804
+ /** Holds the first cancel, or `undefined` when the run recorded none. */
805
+ readonly cancel: ProgressCancel | undefined;
806
+ /** Lists the failed cases in result order. */
807
+ readonly failures: readonly ProgressFailure[];
808
+ /** Holds the reporter's own time from the `end` line, or `undefined` while the run is live. */
809
+ readonly overhead: number | undefined;
810
+ /** Lists the errors Vitest reported outside any case, empty while the run is live. */
811
+ readonly unhandled: readonly ProgressError[];
812
+ }
813
+
814
+ /** Names one module a run starts, under the project that runs it, as one Vitest specification. */
815
+ export declare interface ProgressSpecification {
816
+ /** Names the Vitest project. */
817
+ readonly project: string;
818
+ /** Holds the module path relative to the run's root. */
819
+ readonly module: string;
820
+ }
821
+
822
+ /** Represents the stamp every progress line carries. */
823
+ export declare interface ProgressStamp {
824
+ /** Holds the milliseconds since the reporter was constructed, read from the monotonic clock. */
825
+ readonly time: number;
826
+ /** Holds the id of the process that wrote the line. */
827
+ readonly pid: number;
828
+ }
829
+
830
+ /** Represents the line a reporter writes when a run starts, listing the modules it runs. */
831
+ export declare interface ProgressStartEvent extends ProgressStamp {
832
+ /** Names the line's event. */
833
+ readonly event: 'start';
834
+ /**
835
+ * Lists every module the run starts, in Vitest's order, mirroring the specifications Vitest passes
836
+ * `onTestRunStart`.
837
+ */
838
+ readonly specifications: readonly ProgressSpecification[];
839
+ }
840
+
841
+ /** Names a run's state as a reader sees it: `live` until its `end` line, then the end reason. */
842
+ export declare type ProgressState = 'live' | ProgressEndReason;
843
+
351
844
  /**
352
845
  * Reads the lowercase hexadecimal SHA-256 digest of a captured file's bytes.
353
846
  *
@@ -384,6 +877,24 @@ export declare function readCapture(path: string): Promise<string>;
384
877
  */
385
878
  export declare function readErrorCode(error: unknown): string | undefined;
386
879
 
880
+ /**
881
+ * Reads the bytes a file holds when it is opened, leaving out every byte appended during the read.
882
+ *
883
+ * @param path - The file to read.
884
+ * @returns The bytes up to the length the file had at open.
885
+ * @throws Thrown when the host refuses to open, inspect, or read the file.
886
+ *
887
+ * @example
888
+ * ```ts
889
+ * import { writeFileSync } from 'node:fs'
890
+ * import { readFileSnapshot } from '@orkestrel/test/server'
891
+ *
892
+ * writeFileSync('progress.jsonl', '{"event":"init"}\n')
893
+ * readFileSnapshot('progress.jsonl').length // 17
894
+ * ```
895
+ */
896
+ export declare function readFileSnapshot(path: string): Buffer_2;
897
+
387
898
  /**
388
899
  * Reads the identity of one allocated directory off a host status.
389
900
  *
@@ -433,6 +944,27 @@ export declare function readInventory(root: URL | string, targets: readonly stri
433
944
  */
434
945
  export declare function readLoopClock(): number;
435
946
 
947
+ /**
948
+ * Reads where every run a progress file holds stands, live or finished.
949
+ *
950
+ * @param path - The progress file.
951
+ * @param now - The wall-clock time of the reading. Default: `Date.now()`.
952
+ * @returns One run per writing process.
953
+ * @throws Thrown when the host refuses to read the file, or when a complete line is not a progress
954
+ * event of this format version.
955
+ * @remarks Reads the file once, up to its length at open, decodes complete lines only, holds no
956
+ * timer, and writes nothing.
957
+ *
958
+ * @example
959
+ * ```ts
960
+ * import { readProgress } from '@orkestrel/test/server'
961
+ *
962
+ * const [run] = readProgress('tmp/runs/journey.progress.jsonl')
963
+ * run?.state // 'live' while the run writes, then its end reason
964
+ * ```
965
+ */
966
+ export declare function readProgress(path: string, now?: number): readonly ProgressRun[];
967
+
436
968
  /**
437
969
  * Caps the attempts `removeTree` makes before rethrowing a retryable removal error.
438
970
  */
@@ -474,6 +1006,42 @@ export declare const REMOVE_TREE_RETRYABLE_CODES: readonly string[];
474
1006
  */
475
1007
  export declare function removeTree(path: string): void;
476
1008
 
1009
+ /**
1010
+ * Renders a duration as whole minutes and seconds.
1011
+ *
1012
+ * @param milliseconds - The duration. A negative or non-finite duration renders as zero.
1013
+ * @returns The duration as `<minutes>m<seconds>s`, the seconds padded to two digits.
1014
+ *
1015
+ * @example
1016
+ * ```ts
1017
+ * import { renderDuration } from '@orkestrel/test/server'
1018
+ *
1019
+ * renderDuration(65_400) // '1m05s'
1020
+ * renderDuration(Number.NaN) // '0m00s'
1021
+ * ```
1022
+ */
1023
+ export declare function renderDuration(milliseconds: number): string;
1024
+
1025
+ /**
1026
+ * Renders progress runs as the text a person reads mid-run.
1027
+ *
1028
+ * @param runs - The runs to render.
1029
+ * @returns One block per run: a summary line with done against planned cases, elapsed time, rate, and
1030
+ * estimate; a line per project; the running cases; the cancel; each failure labelled `FIRST`,
1031
+ * `AFTER-BAIL`, or `FAILED` under its module and case, or its module alone when the module failed to
1032
+ * collect, with its first message line and location; each unhandled error; and, after the end, the
1033
+ * reporter's overhead.
1034
+ *
1035
+ * @example
1036
+ * ```ts
1037
+ * import { readProgress, renderProgress } from '@orkestrel/test/server'
1038
+ *
1039
+ * renderProgress(readProgress('tmp/runs/journey.progress.jsonl'))
1040
+ * // 'run 37252 interrupted bail=1: 52/52 cases, elapsed 0m51s, rate 61.2/min, ETA -\n…'
1041
+ * ```
1042
+ */
1043
+ export declare function renderProgress(runs: readonly ProgressRun[]): string;
1044
+
477
1045
  /**
478
1046
  * Drives a real client upgrade request against a loopback port and reports what the server did.
479
1047
  *