@orkestrel/test 0.0.39 → 0.0.41
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 +17 -10
- package/dist/src/browser/index.d.ts +238 -48
- package/dist/src/browser/index.js +356 -105
- package/dist/src/browser/index.js.map +1 -1
- package/dist/src/server/index.cjs +113 -20
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +107 -9
- package/dist/src/server/index.d.ts +107 -9
- package/dist/src/server/index.js +112 -22
- package/dist/src/server/index.js.map +1 -1
- package/package.json +11 -21
- package/dist/bin/reporter.d.ts +0 -5
- package/dist/bin/reporter.js +0 -6
- package/dist/bin/reporter.js.map +0 -1
|
@@ -13,6 +13,7 @@ import type { TestModule } from 'vitest/node';
|
|
|
13
13
|
import type { TestRunEndReason } from 'vitest/node';
|
|
14
14
|
import type { TestSpecification } from 'vitest/node';
|
|
15
15
|
import type { Vitest } from 'vitest/node';
|
|
16
|
+
import type { VitestPluginContext } from 'vitest/node';
|
|
16
17
|
import type { WaitOptions } from '@orkestrel/test';
|
|
17
18
|
|
|
18
19
|
/**
|
|
@@ -179,6 +180,33 @@ export declare function createLink(path: string, source: string): void;
|
|
|
179
180
|
*/
|
|
180
181
|
export declare function createLoopback(server: Server): Promise<LoopbackInterface>;
|
|
181
182
|
|
|
183
|
+
/**
|
|
184
|
+
* Creates a Vitest plugin that adds one `ProgressReporter` to every run naming a progress file, so
|
|
185
|
+
* the reporter still runs when command-line `--reporter` flags replace the configured reporters.
|
|
186
|
+
*
|
|
187
|
+
* @remarks Mount the value in the root `plugins` of a configuration. Vitest calls its hook once per
|
|
188
|
+
* project that carries it, and the hook adds a reporter only while the run's reporters hold no
|
|
189
|
+
* `ProgressReporter` from any copy of this package, read by its `PROGRESS_BRAND` brand, so a run
|
|
190
|
+
* writes one `init` line wherever the plugin is mounted, a configuration that imports the package
|
|
191
|
+
* by a file path included. The hook adds
|
|
192
|
+
* a reporter when the resolved `outputFile` names `progress`, from `--outputFile.progress` or from
|
|
193
|
+
* the configuration's `outputFile`, and adds none otherwise, because `ProgressReporter` refuses to
|
|
194
|
+
* initialize without that file.
|
|
195
|
+
*
|
|
196
|
+
* @example
|
|
197
|
+
* ```ts
|
|
198
|
+
* import { defineConfig } from 'vitest/config'
|
|
199
|
+
* import { createProgressPlugin } from '@orkestrel/test/server'
|
|
200
|
+
*
|
|
201
|
+
* export default defineConfig({
|
|
202
|
+
* plugins: [createProgressPlugin()],
|
|
203
|
+
* test: { projects: [() => ({ test: { name: 'unit' } })] },
|
|
204
|
+
* })
|
|
205
|
+
* // npx vitest run --reporter=dot --outputFile.progress=tmp/runs/progress.jsonl
|
|
206
|
+
* ```
|
|
207
|
+
*/
|
|
208
|
+
export declare function createProgressPlugin(): ProgressPluginInterface;
|
|
209
|
+
|
|
182
210
|
/**
|
|
183
211
|
* Allocates an owned temporary directory with contained file operations.
|
|
184
212
|
*
|
|
@@ -431,11 +459,11 @@ export declare const isProgressError: Guard<ProgressError>;
|
|
|
431
459
|
export declare const isProgressEvent: Guard<ProgressEvent>;
|
|
432
460
|
|
|
433
461
|
/**
|
|
434
|
-
* Reports whether a process id names a live process.
|
|
462
|
+
* Reports whether a process id names a live process, reading each of its threads on Linux.
|
|
435
463
|
*
|
|
436
464
|
* @param pid - The process id to read.
|
|
437
|
-
* @returns True if a process holds that id at the moment of the call
|
|
438
|
-
* pid the host refuses.
|
|
465
|
+
* @returns True if a process holds that id at the moment of the call and, on Linux, one of its
|
|
466
|
+
* threads has not exited; false otherwise, including a pid the host refuses.
|
|
439
467
|
* @throws Nothing. Every host refusal reads as false.
|
|
440
468
|
* @remarks This is an instantaneous observation rather than a claim of ownership. A host reuses a
|
|
441
469
|
* process id after the process holding it exits, so a true answer says some process holds that id at the time of the check
|
|
@@ -444,8 +472,14 @@ export declare const isProgressEvent: Guard<ProgressEvent>;
|
|
|
444
472
|
* false here. A pid of `0` names the caller's own process group on POSIX and the system idle process
|
|
445
473
|
* on Windows, so it reads as true on both without naming a process anyone started.
|
|
446
474
|
*
|
|
447
|
-
* A
|
|
448
|
-
*
|
|
475
|
+
* A signal reaches a Linux process that has exited but whose parent has not reaped it, so on Linux
|
|
476
|
+
* the answer also reads `/proc/<pid>/task`. The process has ended only when two readings taken one
|
|
477
|
+
* after the other list the same threads and every thread in both reads `Z` (exited) or `X` (dead).
|
|
478
|
+
* The leader thread's own state decides nothing: a process whose main thread has exited reads `Z`
|
|
479
|
+
* for its leader while another thread still runs, as a Node process does for milliseconds while its
|
|
480
|
+
* worker threads stop during exit, and it reads as true. A thread whose `stat` cannot be read has
|
|
481
|
+
* gone and counts as exited, and a process whose `task` directory cannot be listed reads as false.
|
|
482
|
+
* The thread table is Linux's layout, so every other host keeps the signal answer.
|
|
449
483
|
*
|
|
450
484
|
* @example
|
|
451
485
|
* ```ts
|
|
@@ -519,6 +553,27 @@ export declare function matchesPlannedCase(test: {
|
|
|
519
553
|
};
|
|
520
554
|
}): boolean;
|
|
521
555
|
|
|
556
|
+
/**
|
|
557
|
+
* Checks whether a value is a progress reporter from any copy of this package, by the brand each
|
|
558
|
+
* one carries under `PROGRESS_BRAND`.
|
|
559
|
+
*
|
|
560
|
+
* @param value - The value to inspect, such as an entry of `vitest.config.reporters`.
|
|
561
|
+
* @returns True if the value holds an own `PROGRESS_BRAND` property whose value is the value
|
|
562
|
+
* itself; false otherwise, a value whose inspection throws included.
|
|
563
|
+
* @remarks A configuration that imports the package by a file path loads a separate copy of the
|
|
564
|
+
* module for each evaluation, so an `instanceof` check against one copy's class misses the
|
|
565
|
+
* reporters another copy made, and the brand recognizes them all.
|
|
566
|
+
*
|
|
567
|
+
* @example
|
|
568
|
+
* ```ts
|
|
569
|
+
* import { matchesProgressReporter, ProgressReporter } from '@orkestrel/test/server'
|
|
570
|
+
*
|
|
571
|
+
* matchesProgressReporter(new ProgressReporter()) // true
|
|
572
|
+
* matchesProgressReporter('dot') // false
|
|
573
|
+
* ```
|
|
574
|
+
*/
|
|
575
|
+
export declare function matchesProgressReporter(value: unknown): boolean;
|
|
576
|
+
|
|
522
577
|
/**
|
|
523
578
|
* Normalizes a module or stack-frame path to the form a progress line carries.
|
|
524
579
|
*
|
|
@@ -537,6 +592,12 @@ export declare function matchesPlannedCase(test: {
|
|
|
537
592
|
*/
|
|
538
593
|
export declare function normalizeProgressPath(file: string, root: string): string;
|
|
539
594
|
|
|
595
|
+
/**
|
|
596
|
+
* Keys the brand every `ProgressReporter` carries, registered so that each copy of this package
|
|
597
|
+
* reads the same key.
|
|
598
|
+
*/
|
|
599
|
+
export declare const PROGRESS_BRAND: unique symbol;
|
|
600
|
+
|
|
540
601
|
/**
|
|
541
602
|
* Names the label a rendered progress reading prints for each failure relation.
|
|
542
603
|
*/
|
|
@@ -697,20 +758,47 @@ export declare interface ProgressModuleEvent extends ProgressStamp {
|
|
|
697
758
|
/** Names the state a finished module reports, mirroring Vitest's `TestModuleState`. */
|
|
698
759
|
export declare type ProgressModuleState = 'passed' | 'failed' | 'skipped' | 'pending' | 'queued';
|
|
699
760
|
|
|
761
|
+
/** Represents the Vitest plugin that adds one progress reporter to every run naming a progress file. */
|
|
762
|
+
export declare interface ProgressPluginInterface {
|
|
763
|
+
/** Names the plugin to Vite. */
|
|
764
|
+
readonly name: string;
|
|
765
|
+
/**
|
|
766
|
+
* Adds a `ProgressReporter` to the run's reporters when `outputFile` names `progress`, and adds
|
|
767
|
+
* nothing when no progress file is named or the reporters already hold a `ProgressReporter` from
|
|
768
|
+
* any copy of this package.
|
|
769
|
+
*
|
|
770
|
+
* @remarks Mirrors the `configureVitest` hook of a Vitest plugin, which Vitest calls once per
|
|
771
|
+
* project that carries the plugin and before it constructs the run's reporters.
|
|
772
|
+
*/
|
|
773
|
+
configureVitest(context: VitestPluginContext): void;
|
|
774
|
+
}
|
|
775
|
+
|
|
700
776
|
/** Represents one project's tallies in a progress reading. */
|
|
701
777
|
export declare interface ProgressProject {
|
|
702
778
|
/** Names the Vitest project. */
|
|
703
779
|
readonly name: string;
|
|
704
780
|
/** Counts the cases the project's collected modules plan to report. */
|
|
705
781
|
readonly planned: number;
|
|
706
|
-
/**
|
|
782
|
+
/**
|
|
783
|
+
* Counts the cases that reported a settled result: passed, failed, or skipped, the cases a bail's
|
|
784
|
+
* cancel skipped included.
|
|
785
|
+
*/
|
|
707
786
|
readonly done: number;
|
|
708
787
|
/** Counts the cases that passed. */
|
|
709
788
|
readonly passed: number;
|
|
710
789
|
/** Counts the cases that failed and the modules that failed to collect. */
|
|
711
790
|
readonly failed: number;
|
|
712
|
-
/**
|
|
791
|
+
/**
|
|
792
|
+
* Counts the planned cases that reported a skip at run time. Under a bail, Vitest reports a skip
|
|
793
|
+
* for the case a module is running when the cancel arrives and for each case left after it in
|
|
794
|
+
* that module, and gives a reporter nothing that tells them from a case that skipped itself.
|
|
795
|
+
*/
|
|
713
796
|
readonly skipped: number;
|
|
797
|
+
/**
|
|
798
|
+
* Counts the planned cases that reported a `pending` result, which Vitest gives each case a bail
|
|
799
|
+
* leaves in a module that was running no case when the cancel arrived.
|
|
800
|
+
*/
|
|
801
|
+
readonly pending: number;
|
|
714
802
|
/** Counts the modules the run started for the project. */
|
|
715
803
|
readonly modules: number;
|
|
716
804
|
/** Counts the modules Vitest has collected for the project. */
|
|
@@ -740,6 +828,10 @@ export declare type ProgressRelation = 'first' | 'bail' | 'later';
|
|
|
740
828
|
* Appends one JSON line per Vitest run event to the file `--outputFile.progress` names, so a live
|
|
741
829
|
* run's progress and each failure's first error can be read before the run ends.
|
|
742
830
|
*
|
|
831
|
+
* @remarks Only the first instance in `vitest.config.reporters` writes; a later instance in the same
|
|
832
|
+
* Vitest writes nothing, so a run is never counted twice. Each instance carries the
|
|
833
|
+
* `PROGRESS_BRAND` brand, so an instance from another copy of this package counts as earlier.
|
|
834
|
+
*
|
|
743
835
|
* @example
|
|
744
836
|
* ```ts
|
|
745
837
|
* import { defineConfig } from 'vitest/config'
|
|
@@ -781,7 +873,10 @@ export declare interface ProgressRun {
|
|
|
781
873
|
readonly bail: number;
|
|
782
874
|
/** Holds the milliseconds the run has taken, up to its end or to the reading. */
|
|
783
875
|
readonly elapsed: number;
|
|
784
|
-
/**
|
|
876
|
+
/**
|
|
877
|
+
* Counts the cases that reported a settled result across every project, the cases a bail's cancel
|
|
878
|
+
* skipped included.
|
|
879
|
+
*/
|
|
785
880
|
readonly done: number;
|
|
786
881
|
/** Counts the cases the collected modules plan to report, across every project. */
|
|
787
882
|
readonly planned: number;
|
|
@@ -790,7 +885,10 @@ export declare interface ProgressRun {
|
|
|
790
885
|
* false otherwise.
|
|
791
886
|
*/
|
|
792
887
|
readonly exact: boolean;
|
|
793
|
-
/**
|
|
888
|
+
/**
|
|
889
|
+
* Holds the settled results per minute since the first case started, the cases a bail's cancel
|
|
890
|
+
* skipped included, or `undefined` before one.
|
|
891
|
+
*/
|
|
794
892
|
readonly rate: number | undefined;
|
|
795
893
|
/**
|
|
796
894
|
* Holds the estimated milliseconds left, or `undefined` once the run ended, before a rate exists,
|
|
@@ -13,6 +13,7 @@ import type { TestModule } from 'vitest/node';
|
|
|
13
13
|
import type { TestRunEndReason } from 'vitest/node';
|
|
14
14
|
import type { TestSpecification } from 'vitest/node';
|
|
15
15
|
import type { Vitest } from 'vitest/node';
|
|
16
|
+
import type { VitestPluginContext } from 'vitest/node';
|
|
16
17
|
import type { WaitOptions } from '@orkestrel/test';
|
|
17
18
|
|
|
18
19
|
/**
|
|
@@ -179,6 +180,33 @@ export declare function createLink(path: string, source: string): void;
|
|
|
179
180
|
*/
|
|
180
181
|
export declare function createLoopback(server: Server): Promise<LoopbackInterface>;
|
|
181
182
|
|
|
183
|
+
/**
|
|
184
|
+
* Creates a Vitest plugin that adds one `ProgressReporter` to every run naming a progress file, so
|
|
185
|
+
* the reporter still runs when command-line `--reporter` flags replace the configured reporters.
|
|
186
|
+
*
|
|
187
|
+
* @remarks Mount the value in the root `plugins` of a configuration. Vitest calls its hook once per
|
|
188
|
+
* project that carries it, and the hook adds a reporter only while the run's reporters hold no
|
|
189
|
+
* `ProgressReporter` from any copy of this package, read by its `PROGRESS_BRAND` brand, so a run
|
|
190
|
+
* writes one `init` line wherever the plugin is mounted, a configuration that imports the package
|
|
191
|
+
* by a file path included. The hook adds
|
|
192
|
+
* a reporter when the resolved `outputFile` names `progress`, from `--outputFile.progress` or from
|
|
193
|
+
* the configuration's `outputFile`, and adds none otherwise, because `ProgressReporter` refuses to
|
|
194
|
+
* initialize without that file.
|
|
195
|
+
*
|
|
196
|
+
* @example
|
|
197
|
+
* ```ts
|
|
198
|
+
* import { defineConfig } from 'vitest/config'
|
|
199
|
+
* import { createProgressPlugin } from '@orkestrel/test/server'
|
|
200
|
+
*
|
|
201
|
+
* export default defineConfig({
|
|
202
|
+
* plugins: [createProgressPlugin()],
|
|
203
|
+
* test: { projects: [() => ({ test: { name: 'unit' } })] },
|
|
204
|
+
* })
|
|
205
|
+
* // npx vitest run --reporter=dot --outputFile.progress=tmp/runs/progress.jsonl
|
|
206
|
+
* ```
|
|
207
|
+
*/
|
|
208
|
+
export declare function createProgressPlugin(): ProgressPluginInterface;
|
|
209
|
+
|
|
182
210
|
/**
|
|
183
211
|
* Allocates an owned temporary directory with contained file operations.
|
|
184
212
|
*
|
|
@@ -431,11 +459,11 @@ export declare const isProgressError: Guard<ProgressError>;
|
|
|
431
459
|
export declare const isProgressEvent: Guard<ProgressEvent>;
|
|
432
460
|
|
|
433
461
|
/**
|
|
434
|
-
* Reports whether a process id names a live process.
|
|
462
|
+
* Reports whether a process id names a live process, reading each of its threads on Linux.
|
|
435
463
|
*
|
|
436
464
|
* @param pid - The process id to read.
|
|
437
|
-
* @returns True if a process holds that id at the moment of the call
|
|
438
|
-
* pid the host refuses.
|
|
465
|
+
* @returns True if a process holds that id at the moment of the call and, on Linux, one of its
|
|
466
|
+
* threads has not exited; false otherwise, including a pid the host refuses.
|
|
439
467
|
* @throws Nothing. Every host refusal reads as false.
|
|
440
468
|
* @remarks This is an instantaneous observation rather than a claim of ownership. A host reuses a
|
|
441
469
|
* process id after the process holding it exits, so a true answer says some process holds that id at the time of the check
|
|
@@ -444,8 +472,14 @@ export declare const isProgressEvent: Guard<ProgressEvent>;
|
|
|
444
472
|
* false here. A pid of `0` names the caller's own process group on POSIX and the system idle process
|
|
445
473
|
* on Windows, so it reads as true on both without naming a process anyone started.
|
|
446
474
|
*
|
|
447
|
-
* A
|
|
448
|
-
*
|
|
475
|
+
* A signal reaches a Linux process that has exited but whose parent has not reaped it, so on Linux
|
|
476
|
+
* the answer also reads `/proc/<pid>/task`. The process has ended only when two readings taken one
|
|
477
|
+
* after the other list the same threads and every thread in both reads `Z` (exited) or `X` (dead).
|
|
478
|
+
* The leader thread's own state decides nothing: a process whose main thread has exited reads `Z`
|
|
479
|
+
* for its leader while another thread still runs, as a Node process does for milliseconds while its
|
|
480
|
+
* worker threads stop during exit, and it reads as true. A thread whose `stat` cannot be read has
|
|
481
|
+
* gone and counts as exited, and a process whose `task` directory cannot be listed reads as false.
|
|
482
|
+
* The thread table is Linux's layout, so every other host keeps the signal answer.
|
|
449
483
|
*
|
|
450
484
|
* @example
|
|
451
485
|
* ```ts
|
|
@@ -519,6 +553,27 @@ export declare function matchesPlannedCase(test: {
|
|
|
519
553
|
};
|
|
520
554
|
}): boolean;
|
|
521
555
|
|
|
556
|
+
/**
|
|
557
|
+
* Checks whether a value is a progress reporter from any copy of this package, by the brand each
|
|
558
|
+
* one carries under `PROGRESS_BRAND`.
|
|
559
|
+
*
|
|
560
|
+
* @param value - The value to inspect, such as an entry of `vitest.config.reporters`.
|
|
561
|
+
* @returns True if the value holds an own `PROGRESS_BRAND` property whose value is the value
|
|
562
|
+
* itself; false otherwise, a value whose inspection throws included.
|
|
563
|
+
* @remarks A configuration that imports the package by a file path loads a separate copy of the
|
|
564
|
+
* module for each evaluation, so an `instanceof` check against one copy's class misses the
|
|
565
|
+
* reporters another copy made, and the brand recognizes them all.
|
|
566
|
+
*
|
|
567
|
+
* @example
|
|
568
|
+
* ```ts
|
|
569
|
+
* import { matchesProgressReporter, ProgressReporter } from '@orkestrel/test/server'
|
|
570
|
+
*
|
|
571
|
+
* matchesProgressReporter(new ProgressReporter()) // true
|
|
572
|
+
* matchesProgressReporter('dot') // false
|
|
573
|
+
* ```
|
|
574
|
+
*/
|
|
575
|
+
export declare function matchesProgressReporter(value: unknown): boolean;
|
|
576
|
+
|
|
522
577
|
/**
|
|
523
578
|
* Normalizes a module or stack-frame path to the form a progress line carries.
|
|
524
579
|
*
|
|
@@ -537,6 +592,12 @@ export declare function matchesPlannedCase(test: {
|
|
|
537
592
|
*/
|
|
538
593
|
export declare function normalizeProgressPath(file: string, root: string): string;
|
|
539
594
|
|
|
595
|
+
/**
|
|
596
|
+
* Keys the brand every `ProgressReporter` carries, registered so that each copy of this package
|
|
597
|
+
* reads the same key.
|
|
598
|
+
*/
|
|
599
|
+
export declare const PROGRESS_BRAND: unique symbol;
|
|
600
|
+
|
|
540
601
|
/**
|
|
541
602
|
* Names the label a rendered progress reading prints for each failure relation.
|
|
542
603
|
*/
|
|
@@ -697,20 +758,47 @@ export declare interface ProgressModuleEvent extends ProgressStamp {
|
|
|
697
758
|
/** Names the state a finished module reports, mirroring Vitest's `TestModuleState`. */
|
|
698
759
|
export declare type ProgressModuleState = 'passed' | 'failed' | 'skipped' | 'pending' | 'queued';
|
|
699
760
|
|
|
761
|
+
/** Represents the Vitest plugin that adds one progress reporter to every run naming a progress file. */
|
|
762
|
+
export declare interface ProgressPluginInterface {
|
|
763
|
+
/** Names the plugin to Vite. */
|
|
764
|
+
readonly name: string;
|
|
765
|
+
/**
|
|
766
|
+
* Adds a `ProgressReporter` to the run's reporters when `outputFile` names `progress`, and adds
|
|
767
|
+
* nothing when no progress file is named or the reporters already hold a `ProgressReporter` from
|
|
768
|
+
* any copy of this package.
|
|
769
|
+
*
|
|
770
|
+
* @remarks Mirrors the `configureVitest` hook of a Vitest plugin, which Vitest calls once per
|
|
771
|
+
* project that carries the plugin and before it constructs the run's reporters.
|
|
772
|
+
*/
|
|
773
|
+
configureVitest(context: VitestPluginContext): void;
|
|
774
|
+
}
|
|
775
|
+
|
|
700
776
|
/** Represents one project's tallies in a progress reading. */
|
|
701
777
|
export declare interface ProgressProject {
|
|
702
778
|
/** Names the Vitest project. */
|
|
703
779
|
readonly name: string;
|
|
704
780
|
/** Counts the cases the project's collected modules plan to report. */
|
|
705
781
|
readonly planned: number;
|
|
706
|
-
/**
|
|
782
|
+
/**
|
|
783
|
+
* Counts the cases that reported a settled result: passed, failed, or skipped, the cases a bail's
|
|
784
|
+
* cancel skipped included.
|
|
785
|
+
*/
|
|
707
786
|
readonly done: number;
|
|
708
787
|
/** Counts the cases that passed. */
|
|
709
788
|
readonly passed: number;
|
|
710
789
|
/** Counts the cases that failed and the modules that failed to collect. */
|
|
711
790
|
readonly failed: number;
|
|
712
|
-
/**
|
|
791
|
+
/**
|
|
792
|
+
* Counts the planned cases that reported a skip at run time. Under a bail, Vitest reports a skip
|
|
793
|
+
* for the case a module is running when the cancel arrives and for each case left after it in
|
|
794
|
+
* that module, and gives a reporter nothing that tells them from a case that skipped itself.
|
|
795
|
+
*/
|
|
713
796
|
readonly skipped: number;
|
|
797
|
+
/**
|
|
798
|
+
* Counts the planned cases that reported a `pending` result, which Vitest gives each case a bail
|
|
799
|
+
* leaves in a module that was running no case when the cancel arrived.
|
|
800
|
+
*/
|
|
801
|
+
readonly pending: number;
|
|
714
802
|
/** Counts the modules the run started for the project. */
|
|
715
803
|
readonly modules: number;
|
|
716
804
|
/** Counts the modules Vitest has collected for the project. */
|
|
@@ -740,6 +828,10 @@ export declare type ProgressRelation = 'first' | 'bail' | 'later';
|
|
|
740
828
|
* Appends one JSON line per Vitest run event to the file `--outputFile.progress` names, so a live
|
|
741
829
|
* run's progress and each failure's first error can be read before the run ends.
|
|
742
830
|
*
|
|
831
|
+
* @remarks Only the first instance in `vitest.config.reporters` writes; a later instance in the same
|
|
832
|
+
* Vitest writes nothing, so a run is never counted twice. Each instance carries the
|
|
833
|
+
* `PROGRESS_BRAND` brand, so an instance from another copy of this package counts as earlier.
|
|
834
|
+
*
|
|
743
835
|
* @example
|
|
744
836
|
* ```ts
|
|
745
837
|
* import { defineConfig } from 'vitest/config'
|
|
@@ -781,7 +873,10 @@ export declare interface ProgressRun {
|
|
|
781
873
|
readonly bail: number;
|
|
782
874
|
/** Holds the milliseconds the run has taken, up to its end or to the reading. */
|
|
783
875
|
readonly elapsed: number;
|
|
784
|
-
/**
|
|
876
|
+
/**
|
|
877
|
+
* Counts the cases that reported a settled result across every project, the cases a bail's cancel
|
|
878
|
+
* skipped included.
|
|
879
|
+
*/
|
|
785
880
|
readonly done: number;
|
|
786
881
|
/** Counts the cases the collected modules plan to report, across every project. */
|
|
787
882
|
readonly planned: number;
|
|
@@ -790,7 +885,10 @@ export declare interface ProgressRun {
|
|
|
790
885
|
* false otherwise.
|
|
791
886
|
*/
|
|
792
887
|
readonly exact: boolean;
|
|
793
|
-
/**
|
|
888
|
+
/**
|
|
889
|
+
* Holds the settled results per minute since the first case started, the cases a bail's cancel
|
|
890
|
+
* skipped included, or `undefined` before one.
|
|
891
|
+
*/
|
|
794
892
|
readonly rate: number | undefined;
|
|
795
893
|
/**
|
|
796
894
|
* Holds the estimated milliseconds left, or `undefined` once the run ended, before a rate exists,
|
package/dist/src/server/index.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { arrayOf, isFunction, isNumber, isObject, isString, literalOf, recordOf, unionOf } from "@orkestrel/contract";
|
|
1
|
+
import { arrayOf, attempt, holds, isFunction, isNumber, isObject, isString, literalOf, recordOf, unionOf } from "@orkestrel/contract";
|
|
2
2
|
import { Buffer } from "node:buffer";
|
|
3
3
|
import { createHash } from "node:crypto";
|
|
4
4
|
import { appendFileSync, closeSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
|
|
@@ -37,6 +37,11 @@ var PROGRESS_VERSION = 1;
|
|
|
37
37
|
*/
|
|
38
38
|
var PROGRESS_MESSAGE_LIMIT = 300;
|
|
39
39
|
/**
|
|
40
|
+
* Keys the brand every `ProgressReporter` carries, registered so that each copy of this package
|
|
41
|
+
* reads the same key.
|
|
42
|
+
*/
|
|
43
|
+
var PROGRESS_BRAND = Symbol.for("@orkestrel/test.ProgressReporter");
|
|
44
|
+
/**
|
|
40
45
|
* Names the label a rendered progress reading prints for each failure relation.
|
|
41
46
|
*/
|
|
42
47
|
var PROGRESS_LABELS = Object.freeze({
|
|
@@ -458,11 +463,11 @@ function readInventory(root, targets, options) {
|
|
|
458
463
|
return Object.fromEntries(Array.from(contents).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0));
|
|
459
464
|
}
|
|
460
465
|
/**
|
|
461
|
-
* Reports whether a process id names a live process.
|
|
466
|
+
* Reports whether a process id names a live process, reading each of its threads on Linux.
|
|
462
467
|
*
|
|
463
468
|
* @param pid - The process id to read.
|
|
464
|
-
* @returns True if a process holds that id at the moment of the call
|
|
465
|
-
* pid the host refuses.
|
|
469
|
+
* @returns True if a process holds that id at the moment of the call and, on Linux, one of its
|
|
470
|
+
* threads has not exited; false otherwise, including a pid the host refuses.
|
|
466
471
|
* @throws Nothing. Every host refusal reads as false.
|
|
467
472
|
* @remarks This is an instantaneous observation rather than a claim of ownership. A host reuses a
|
|
468
473
|
* process id after the process holding it exits, so a true answer says some process holds that id at the time of the check
|
|
@@ -471,8 +476,14 @@ function readInventory(root, targets, options) {
|
|
|
471
476
|
* false here. A pid of `0` names the caller's own process group on POSIX and the system idle process
|
|
472
477
|
* on Windows, so it reads as true on both without naming a process anyone started.
|
|
473
478
|
*
|
|
474
|
-
* A
|
|
475
|
-
*
|
|
479
|
+
* A signal reaches a Linux process that has exited but whose parent has not reaped it, so on Linux
|
|
480
|
+
* the answer also reads `/proc/<pid>/task`. The process has ended only when two readings taken one
|
|
481
|
+
* after the other list the same threads and every thread in both reads `Z` (exited) or `X` (dead).
|
|
482
|
+
* The leader thread's own state decides nothing: a process whose main thread has exited reads `Z`
|
|
483
|
+
* for its leader while another thread still runs, as a Node process does for milliseconds while its
|
|
484
|
+
* worker threads stop during exit, and it reads as true. A thread whose `stat` cannot be read has
|
|
485
|
+
* gone and counts as exited, and a process whose `task` directory cannot be listed reads as false.
|
|
486
|
+
* The thread table is Linux's layout, so every other host keeps the signal answer.
|
|
476
487
|
*
|
|
477
488
|
* @example
|
|
478
489
|
* ```ts
|
|
@@ -488,14 +499,23 @@ function isRunning(pid) {
|
|
|
488
499
|
} catch {
|
|
489
500
|
return false;
|
|
490
501
|
}
|
|
491
|
-
if (process.platform !== "linux") return true;
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
const
|
|
495
|
-
return
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
502
|
+
if (process.platform !== "linux" || pid === 0) return true;
|
|
503
|
+
const directory = join("/proc", String(pid), "task");
|
|
504
|
+
const [first, second] = Array.from({ length: 2 }, () => {
|
|
505
|
+
const listing = attempt(() => readdirSync(directory));
|
|
506
|
+
return listing.success ? listing.value.flatMap((thread) => {
|
|
507
|
+
const status = attempt(() => readFileSync(join(directory, thread, "stat"), "utf8"));
|
|
508
|
+
if (!status.success) return [];
|
|
509
|
+
const boundary = status.value.lastIndexOf(") ");
|
|
510
|
+
return [{
|
|
511
|
+
thread,
|
|
512
|
+
state: boundary < 0 ? "" : status.value.slice(boundary + 2, boundary + 3)
|
|
513
|
+
}];
|
|
514
|
+
}) : void 0;
|
|
515
|
+
});
|
|
516
|
+
if (first === void 0 || second === void 0) return false;
|
|
517
|
+
const [listed, relisted] = [first, second].map((reading) => reading.map(({ thread }) => thread).toSorted().join(" "));
|
|
518
|
+
return listed !== relisted || [...first, ...second].some(({ state }) => state !== "Z" && state !== "X");
|
|
499
519
|
}
|
|
500
520
|
/**
|
|
501
521
|
* Waits for a socket to close, accepting a peer reset as a forced close.
|
|
@@ -996,7 +1016,9 @@ async function chooseFiles(context, request) {
|
|
|
996
1016
|
* ```
|
|
997
1017
|
*/
|
|
998
1018
|
function normalizeProgressPath(file, root) {
|
|
999
|
-
const
|
|
1019
|
+
const named = file.startsWith("/@fs/") ? file.slice(5) : file;
|
|
1020
|
+
const absolute = named === file || named.startsWith("/") || /^[a-z]:/iu.test(named) ? named : `/${named}`;
|
|
1021
|
+
const path = relative(root, absolute).replaceAll("\\", "/");
|
|
1000
1022
|
return path === ".." || path.startsWith("../") || isAbsolute(path) ? file : path;
|
|
1001
1023
|
}
|
|
1002
1024
|
/**
|
|
@@ -1050,6 +1072,28 @@ function matchesPlannedCase(test) {
|
|
|
1050
1072
|
return test.options.mode === "run" || test.options.mode === "only";
|
|
1051
1073
|
}
|
|
1052
1074
|
/**
|
|
1075
|
+
* Checks whether a value is a progress reporter from any copy of this package, by the brand each
|
|
1076
|
+
* one carries under `PROGRESS_BRAND`.
|
|
1077
|
+
*
|
|
1078
|
+
* @param value - The value to inspect, such as an entry of `vitest.config.reporters`.
|
|
1079
|
+
* @returns True if the value holds an own `PROGRESS_BRAND` property whose value is the value
|
|
1080
|
+
* itself; false otherwise, a value whose inspection throws included.
|
|
1081
|
+
* @remarks A configuration that imports the package by a file path loads a separate copy of the
|
|
1082
|
+
* module for each evaluation, so an `instanceof` check against one copy's class misses the
|
|
1083
|
+
* reporters another copy made, and the brand recognizes them all.
|
|
1084
|
+
*
|
|
1085
|
+
* @example
|
|
1086
|
+
* ```ts
|
|
1087
|
+
* import { matchesProgressReporter, ProgressReporter } from '@orkestrel/test/server'
|
|
1088
|
+
*
|
|
1089
|
+
* matchesProgressReporter(new ProgressReporter()) // true
|
|
1090
|
+
* matchesProgressReporter('dot') // false
|
|
1091
|
+
* ```
|
|
1092
|
+
*/
|
|
1093
|
+
function matchesProgressReporter(value) {
|
|
1094
|
+
return holds(() => isObject(value) && Object.hasOwn(value, PROGRESS_BRAND) && Reflect.get(value, PROGRESS_BRAND) === value);
|
|
1095
|
+
}
|
|
1096
|
+
/**
|
|
1053
1097
|
* Reads the bytes a file holds when it is opened, leaving out every byte appended during the read.
|
|
1054
1098
|
*
|
|
1055
1099
|
* @param path - The file to read.
|
|
@@ -1151,6 +1195,7 @@ function computeProgressRun(events, now) {
|
|
|
1151
1195
|
const specifications = filterProgressEvents(own, "start").flatMap((start) => start.specifications);
|
|
1152
1196
|
const collections = filterProgressEvents(own, "collected");
|
|
1153
1197
|
const cases = filterProgressEvents(own, "case");
|
|
1198
|
+
const settled = cases.filter((entry) => entry.state !== "pending");
|
|
1154
1199
|
const cancel = filterProgressEvents(own, "cancel").at(0);
|
|
1155
1200
|
const end = filterProgressEvents(own, "end").at(0);
|
|
1156
1201
|
const clock = end?.time ?? now - init.wall + init.time;
|
|
@@ -1164,19 +1209,20 @@ function computeProgressRun(events, now) {
|
|
|
1164
1209
|
return {
|
|
1165
1210
|
name,
|
|
1166
1211
|
planned: collected.reduce((total, entry) => total + entry.planned, 0),
|
|
1167
|
-
done: results.length,
|
|
1212
|
+
done: results.filter((entry) => entry.state !== "pending").length,
|
|
1168
1213
|
passed: results.filter((entry) => entry.state === "passed").length,
|
|
1169
1214
|
failed: results.filter((entry) => entry.state === "failed").length + collected.filter((entry) => entry.errors.length > 0).length,
|
|
1170
1215
|
skipped: results.filter((entry) => entry.state === "skipped").length,
|
|
1216
|
+
pending: results.filter((entry) => entry.state === "pending").length,
|
|
1171
1217
|
modules: specifications.filter((entry) => entry.project === name).length,
|
|
1172
1218
|
collected: collected.length
|
|
1173
1219
|
};
|
|
1174
1220
|
});
|
|
1175
1221
|
const planned = projects.reduce((total, project) => total + project.planned, 0);
|
|
1176
1222
|
const exact = specifications.length > 0 && projects.every((project) => project.collected >= project.modules);
|
|
1177
|
-
const first =
|
|
1223
|
+
const first = settled.at(0);
|
|
1178
1224
|
const span = first === void 0 ? 0 : clock - (first.time - (first.duration ?? 0));
|
|
1179
|
-
const rate =
|
|
1225
|
+
const rate = settled.length > 0 && span > 0 ? settled.length / span * 6e4 : void 0;
|
|
1180
1226
|
const finished = new Set(cases.map((entry) => entry.id));
|
|
1181
1227
|
const position = cancel === void 0 ? -1 : own.indexOf(cancel);
|
|
1182
1228
|
const trigger = own.find((event) => event.event === "case" && event.state === "failed");
|
|
@@ -1200,11 +1246,11 @@ function computeProgressRun(events, now) {
|
|
|
1200
1246
|
state: end?.reason ?? "live",
|
|
1201
1247
|
bail: init.bail,
|
|
1202
1248
|
elapsed: clock,
|
|
1203
|
-
done:
|
|
1249
|
+
done: settled.length,
|
|
1204
1250
|
planned,
|
|
1205
1251
|
exact,
|
|
1206
1252
|
rate,
|
|
1207
|
-
remaining: end === void 0 && exact && rate !== void 0 ? Math.max(0, (planned -
|
|
1253
|
+
remaining: end === void 0 && exact && rate !== void 0 ? Math.max(0, (planned - settled.length) / rate * 6e4) : void 0,
|
|
1208
1254
|
projects,
|
|
1209
1255
|
running: end === void 0 ? filterProgressEvents(own, "ready").filter((ready) => !finished.has(ready.id)).map((ready) => ({
|
|
1210
1256
|
project: ready.project,
|
|
@@ -1310,7 +1356,7 @@ function renderProgress(runs) {
|
|
|
1310
1356
|
const width = Math.max(0, ...run.projects.map((project) => project.name.length));
|
|
1311
1357
|
return [
|
|
1312
1358
|
`run ${run.pid} ${run.state} ${run.bail === 0 ? "full" : `bail=${run.bail}`}: ${run.done}/${run.planned}${run.exact ? "" : "+"} cases, elapsed ${renderDuration(run.elapsed)}, rate ${run.rate === void 0 ? "-" : `${run.rate.toFixed(1)}/min`}, ETA ${run.remaining === void 0 ? "-" : renderDuration(run.remaining)}`,
|
|
1313
|
-
...run.projects.map((project) => ` ${project.name.padEnd(width)} ${project.done}/${project.planned} passed ${project.passed} failed ${project.failed} skipped ${project.skipped}${project.collected < project.modules ? ` (${project.collected}/${project.modules} modules collected)` : ""}`),
|
|
1359
|
+
...run.projects.map((project) => ` ${project.name.padEnd(width)} ${project.done}/${project.planned} passed ${project.passed} failed ${project.failed} skipped ${project.skipped}${project.pending > 0 ? ` pending ${project.pending}` : ""}${project.collected < project.modules ? ` (${project.collected}/${project.modules} modules collected)` : ""}`),
|
|
1314
1360
|
...run.running.map((entry) => ` running ${renderDuration(entry.duration)} [${entry.project}] ${entry.name}`),
|
|
1315
1361
|
...run.cancel === void 0 ? [] : [` cancelled (${run.cancel.reason}) at ${renderDuration(run.cancel.time)}`],
|
|
1316
1362
|
...[...run.failures.map((failure) => ({
|
|
@@ -1557,6 +1603,10 @@ function createCookieJar() {
|
|
|
1557
1603
|
* Appends one JSON line per Vitest run event to the file `--outputFile.progress` names, so a live
|
|
1558
1604
|
* run's progress and each failure's first error can be read before the run ends.
|
|
1559
1605
|
*
|
|
1606
|
+
* @remarks Only the first instance in `vitest.config.reporters` writes; a later instance in the same
|
|
1607
|
+
* Vitest writes nothing, so a run is never counted twice. Each instance carries the
|
|
1608
|
+
* `PROGRESS_BRAND` brand, so an instance from another copy of this package counts as earlier.
|
|
1609
|
+
*
|
|
1560
1610
|
* @example
|
|
1561
1611
|
* ```ts
|
|
1562
1612
|
* import { defineConfig } from 'vitest/config'
|
|
@@ -1579,12 +1629,15 @@ var ProgressReporter = class {
|
|
|
1579
1629
|
#overhead = 0;
|
|
1580
1630
|
constructor() {
|
|
1581
1631
|
this.#listener = this.#cancel.bind(this);
|
|
1632
|
+
Object.defineProperty(this, PROGRESS_BRAND, { value: this });
|
|
1582
1633
|
}
|
|
1583
1634
|
onInit(vitest) {
|
|
1584
1635
|
this.#measure(() => {
|
|
1585
1636
|
const output = vitest.config.outputFile;
|
|
1586
1637
|
const named = typeof output === "object" ? output.progress : void 0;
|
|
1587
1638
|
if (named === void 0) throw new Error("ProgressReporter writes no file: pass --outputFile.progress=<file>, or set outputFile: { progress: <file> } in the test config");
|
|
1639
|
+
const writer = vitest.config.reporters.find((entry) => matchesProgressReporter(entry));
|
|
1640
|
+
if (writer !== void 0 && writer !== this) return;
|
|
1588
1641
|
this.#vitest = vitest;
|
|
1589
1642
|
this.#path = resolve(vitest.config.root, named);
|
|
1590
1643
|
mkdirSync(dirname(this.#path), { recursive: true });
|
|
@@ -1716,6 +1769,43 @@ var ProgressReporter = class {
|
|
|
1716
1769
|
appendFileSync(this.#path, `${JSON.stringify(event)}\n`);
|
|
1717
1770
|
}
|
|
1718
1771
|
};
|
|
1719
|
-
|
|
1772
|
+
// src/server/plugins.ts
|
|
1773
|
+
/**
|
|
1774
|
+
* Creates a Vitest plugin that adds one `ProgressReporter` to every run naming a progress file, so
|
|
1775
|
+
* the reporter still runs when command-line `--reporter` flags replace the configured reporters.
|
|
1776
|
+
*
|
|
1777
|
+
* @remarks Mount the value in the root `plugins` of a configuration. Vitest calls its hook once per
|
|
1778
|
+
* project that carries it, and the hook adds a reporter only while the run's reporters hold no
|
|
1779
|
+
* `ProgressReporter` from any copy of this package, read by its `PROGRESS_BRAND` brand, so a run
|
|
1780
|
+
* writes one `init` line wherever the plugin is mounted, a configuration that imports the package
|
|
1781
|
+
* by a file path included. The hook adds
|
|
1782
|
+
* a reporter when the resolved `outputFile` names `progress`, from `--outputFile.progress` or from
|
|
1783
|
+
* the configuration's `outputFile`, and adds none otherwise, because `ProgressReporter` refuses to
|
|
1784
|
+
* initialize without that file.
|
|
1785
|
+
*
|
|
1786
|
+
* @example
|
|
1787
|
+
* ```ts
|
|
1788
|
+
* import { defineConfig } from 'vitest/config'
|
|
1789
|
+
* import { createProgressPlugin } from '@orkestrel/test/server'
|
|
1790
|
+
*
|
|
1791
|
+
* export default defineConfig({
|
|
1792
|
+
* plugins: [createProgressPlugin()],
|
|
1793
|
+
* test: { projects: [() => ({ test: { name: 'unit' } })] },
|
|
1794
|
+
* })
|
|
1795
|
+
* // npx vitest run --reporter=dot --outputFile.progress=tmp/runs/progress.jsonl
|
|
1796
|
+
* ```
|
|
1797
|
+
*/
|
|
1798
|
+
function createProgressPlugin() {
|
|
1799
|
+
return {
|
|
1800
|
+
name: "orkestrel:progress",
|
|
1801
|
+
configureVitest({ vitest }) {
|
|
1802
|
+
const output = vitest.config.outputFile;
|
|
1803
|
+
if (typeof output !== "object" || output.progress === void 0) return;
|
|
1804
|
+
if (vitest.config.reporters.some((entry) => matchesProgressReporter(entry))) return;
|
|
1805
|
+
vitest.config.reporters.push(new ProgressReporter());
|
|
1806
|
+
}
|
|
1807
|
+
};
|
|
1808
|
+
}
|
|
1809
|
+
export { PROGRESS_BRAND, PROGRESS_LABELS, PROGRESS_MESSAGE_LIMIT, PROGRESS_VERSION, ProgressReporter, REMOVE_TREE_MAX_ATTEMPTS, REMOVE_TREE_RETRYABLE_CODES, REMOVE_TREE_RETRY_DELAY_MS, alignLoopClock, chooseFiles, computeProgress, computeProgressRun, createCookieJar, createLink, createLoopback, createProgressPlugin, createScratch, destroyScratch, extractProgressError, extractProgressEvents, filterProgressEvents, hasScratchPath, isExcluded, isProgressError, isProgressEvent, isRunning, matchesIdentity, matchesPlannedCase, matchesProgressReporter, normalizeProgressPath, readCapture, readErrorCode, readFileSnapshot, readIdentity, readInventory, readLoopClock, readProgress, removeTree, renderDuration, renderProgress, requestUpgrade, requireContained, resolveContained, supportsBytes, supportsCase, supportsDirectoryLinks, supportsFileLinks, supportsMode, waitForSocketClose };
|
|
1720
1810
|
|
|
1721
1811
|
//# sourceMappingURL=index.js.map
|