UNPKG

5.33 kBTypeScriptView Raw
1import type { VerbosityLevel } from '../configuration/VerbosityLevel.js';
2import type { ExecutionTree } from './ExecutionTree.js';
3import type { Parameters } from '../configuration/Parameters.js';
4/**
5 * Post-run details produced by {@link check}
6 *
7 * A failing property can easily detected by checking the `failed` flag of this structure
8 *
9 * @remarks Since 0.0.7
10 * @public
11 */
12export type RunDetails<Ts> = RunDetailsFailureProperty<Ts> | RunDetailsFailureTooManySkips<Ts> | RunDetailsFailureInterrupted<Ts> | RunDetailsSuccess<Ts>;
13/**
14 * Run reported as failed because
15 * the property failed
16 *
17 * Refer to {@link RunDetailsCommon} for more details
18 *
19 * @remarks Since 1.25.0
20 * @public
21 */
22export interface RunDetailsFailureProperty<Ts> extends RunDetailsCommon<Ts> {
23 failed: true;
24 interrupted: boolean;
25 counterexample: Ts;
26 counterexamplePath: string;
27 error: string;
28 errorInstance: unknown;
29}
30/**
31 * Run reported as failed because
32 * too many retries have been attempted to generate valid values
33 *
34 * Refer to {@link RunDetailsCommon} for more details
35 *
36 * @remarks Since 1.25.0
37 * @public
38 */
39export interface RunDetailsFailureTooManySkips<Ts> extends RunDetailsCommon<Ts> {
40 failed: true;
41 interrupted: false;
42 counterexample: null;
43 counterexamplePath: null;
44 error: null;
45 errorInstance: null;
46}
47/**
48 * Run reported as failed because
49 * it took too long and thus has been interrupted
50 *
51 * Refer to {@link RunDetailsCommon} for more details
52 *
53 * @remarks Since 1.25.0
54 * @public
55 */
56export interface RunDetailsFailureInterrupted<Ts> extends RunDetailsCommon<Ts> {
57 failed: true;
58 interrupted: true;
59 counterexample: null;
60 counterexamplePath: null;
61 error: null;
62 errorInstance: null;
63}
64/**
65 * Run reported as success
66 *
67 * Refer to {@link RunDetailsCommon} for more details
68 *
69 * @remarks Since 1.25.0
70 * @public
71 */
72export interface RunDetailsSuccess<Ts> extends RunDetailsCommon<Ts> {
73 failed: false;
74 interrupted: boolean;
75 counterexample: null;
76 counterexamplePath: null;
77 error: null;
78 errorInstance: null;
79}
80/**
81 * Shared part between variants of RunDetails
82 * @remarks Since 2.2.0
83 * @public
84 */
85export interface RunDetailsCommon<Ts> {
86 /**
87 * Does the property failed during the execution of {@link check}?
88 * @remarks Since 0.0.7
89 */
90 failed: boolean;
91 /**
92 * Was the execution interrupted?
93 * @remarks Since 1.19.0
94 */
95 interrupted: boolean;
96 /**
97 * Number of runs
98 *
99 * - In case of failed property: Number of runs up to the first failure (including the failure run)
100 * - Otherwise: Number of successful executions
101 *
102 * @remarks Since 1.0.0
103 */
104 numRuns: number;
105 /**
106 * Number of skipped entries due to failed pre-condition
107 *
108 * As `numRuns` it only takes into account the skipped values that occured before the first failure.
109 * Refer to {@link pre} to add such pre-conditions.
110 *
111 * @remarks Since 1.3.0
112 */
113 numSkips: number;
114 /**
115 * Number of shrinks required to get to the minimal failing case (aka counterexample)
116 * @remarks Since 1.0.0
117 */
118 numShrinks: number;
119 /**
120 * Seed that have been used by the run
121 *
122 * It can be forced in {@link assert}, {@link check}, {@link sample} and {@link statistics} using `Parameters`
123 * @remarks Since 0.0.7
124 */
125 seed: number;
126 /**
127 * In case of failure: the counterexample contains the minimal failing case (first failure after shrinking)
128 * @remarks Since 0.0.7
129 */
130 counterexample: Ts | null;
131 /**
132 * In case of failure: it contains the reason of the failure
133 * @remarks Since 0.0.7
134 */
135 error: string | null;
136 /**
137 * In case of failure: it contains the error that has been thrown if any
138 * @remarks Since 3.0.0
139 */
140 errorInstance: unknown | null;
141 /**
142 * In case of failure: path to the counterexample
143 *
144 * For replay purposes, it can be forced in {@link assert}, {@link check}, {@link sample} and {@link statistics} using `Parameters`
145 *
146 * @remarks Since 1.0.0
147 */
148 counterexamplePath: string | null;
149 /**
150 * List all failures that have occurred during the run
151 *
152 * You must enable verbose with at least `Verbosity.Verbose` in `Parameters`
153 * in order to have values in it
154 *
155 * @remarks Since 1.1.0
156 */
157 failures: Ts[];
158 /**
159 * Execution summary of the run
160 *
161 * Traces the origin of each value encountered during the test and its execution status.
162 * Can help to diagnose shrinking issues.
163 *
164 * You must enable verbose with at least `Verbosity.Verbose` in `Parameters`
165 * in order to have values in it:
166 * - Verbose: Only failures
167 * - VeryVerbose: Failures, Successes and Skipped
168 *
169 * @remarks Since 1.9.0
170 */
171 executionSummary: ExecutionTree<Ts>[];
172 /**
173 * Verbosity level required by the user
174 * @remarks Since 1.9.0
175 */
176 verbose: VerbosityLevel;
177 /**
178 * Configuration of the run
179 *
180 * It includes both local parameters set on {@link check} or {@link assert}
181 * and global ones specified using {@link configureGlobal}
182 *
183 * @remarks Since 1.25.0
184 */
185 runConfiguration: Parameters<Ts>;
186}