1 | import { Logger } from "@lbu/insight";
|
2 |
|
3 | /**
|
4 | * Top level test function for registering tests
|
5 | */
|
6 | export function test(name: string, callback: TestCallback): void;
|
7 |
|
8 | /**
|
9 | * Run the registered tests
|
10 | */
|
11 | export function mainTestFn(meta: ImportMeta): void;
|
12 |
|
13 | /**
|
14 | * Available assertions and the option of doing nested tests
|
15 | */
|
16 | interface TestRunner {
|
17 | /**
|
18 | * Available test logger
|
19 | */
|
20 | log: Logger;
|
21 |
|
22 | /**
|
23 | * Configurable timeout used for sub tests
|
24 | */
|
25 | timeout?: number;
|
26 |
|
27 | /**
|
28 | * Expect value to be truthy
|
29 | */
|
30 | ok(value: any, message?: string): void;
|
31 |
|
32 | /**
|
33 | * Expect value to be falsey
|
34 | */
|
35 | notOk(value: any, message?: string): void;
|
36 |
|
37 | /**
|
38 | * Expect actual to triple equal expected
|
39 | */
|
40 | equal(actual?: any, expected?: any, message?: string): void;
|
41 |
|
42 | /**
|
43 | * Expect actual to not triple equal expected
|
44 | */
|
45 | notEqual(actual?: any, expected?: any, message?: string): void;
|
46 |
|
47 | /**
|
48 | * Expect actual to deep equal expected
|
49 | * Uses assert.deepStrictEqual under the hood
|
50 | * See
|
51 | * https://nodejs.org/api/assert.html#assert_assert_deepstrictequal_actual_expected_message
|
52 | */
|
53 | deepEqual(actual?: any, expected?: any, message?: string): void;
|
54 |
|
55 | /**
|
56 | * Instantly fail a test
|
57 | * Useful when testing if a function needs to throw.
|
58 | *
|
59 | * @example
|
60 | * ```js
|
61 | * try {
|
62 | * shouldThrow();
|
63 | * t.fail("Function should have thrown an error!");
|
64 | * } catch (e) {
|
65 | * t.pass("Do other assertions here");
|
66 | * }
|
67 | * ```
|
68 | */
|
69 | fail(message?: string): void;
|
70 |
|
71 | /**
|
72 | * Pass a test
|
73 | * Useful if empty code blocks are not allowed
|
74 | */
|
75 | pass(message?: string): void;
|
76 |
|
77 | /**
|
78 | * Create a nested test runner
|
79 | * Note that these are executed after the parent is done executing.
|
80 | */
|
81 | test(name: string, callback: TestCallback): void;
|
82 | }
|
83 |
|
84 | /**
|
85 | * Callback of a test function
|
86 | */
|
87 | type TestCallback = (t: TestRunner) => void | any | Promise<any>;
|
88 |
|
89 | /**
|
90 | * @private
|
91 | */
|
92 | interface TestState {
|
93 | parent?: TestState;
|
94 | hasFailure: boolean;
|
95 | name: string;
|
96 | callback?: TestCallback;
|
97 | assertions: TestAssertion[];
|
98 | children: TestState[];
|
99 | caughtException?: Error;
|
100 | }
|
101 |
|
102 | /**
|
103 | * @private
|
104 | */
|
105 | interface TestAssertion {
|
106 | type:
|
107 | | "timeout"
|
108 | | "ok"
|
109 | | "notOk"
|
110 | | "equal"
|
111 | | "notEqual"
|
112 | | "deepEqual"
|
113 | | "fail"
|
114 | | "pass";
|
115 | passed: boolean;
|
116 | meta:
|
117 | | {
|
118 | actual: boolean;
|
119 | }
|
120 | | {
|
121 | actual?: any;
|
122 | expected?: any;
|
123 | message?: string;
|
124 | }
|
125 | | undefined;
|
126 | message?: string;
|
127 | }
|
128 |
|
129 | /**
|
130 | * Run the registered benchmarks
|
131 | */
|
132 | export function mainBenchFn(meta: ImportMeta): void;
|
133 |
|
134 | /**
|
135 | * Top level bench mark registering function
|
136 | */
|
137 | export function bench(name: string, callback: BenchCallback): void;
|
138 |
|
139 | /**
|
140 | * Argument to bench mark functions
|
141 | */
|
142 | export interface BenchRunner {
|
143 | /**
|
144 | * Amount of iterations this call should do
|
145 | */
|
146 | N: number;
|
147 |
|
148 | /**
|
149 | * Reset the start time
|
150 | * This can be used if a benchmark needs some setup
|
151 | */
|
152 | resetTime(): void;
|
153 | }
|
154 |
|
155 | /**
|
156 | * Callback function executed while benchmarking
|
157 | */
|
158 | export type BenchCallback = (b: BenchRunner) => void | Promise<void>;
|
159 |
|
160 | /**
|
161 | * @private
|
162 | */
|
163 | interface BenchState {
|
164 | name: string;
|
165 | N: number;
|
166 | operationTimeNs: string;
|
167 | callback: BenchCallback;
|
168 | caughtException?: Error;
|
169 | }
|
170 |
|
171 | /**
|
172 | * Represents either a file in the `scripts` directory or a script from the package.json
|
173 | * Depending on the type contains either script or path
|
174 | */
|
175 | export interface CollectedScript {
|
176 | type: "user" | "package";
|
177 | name: string;
|
178 | path?: string;
|
179 | script?: string;
|
180 | }
|
181 |
|
182 | export interface ScriptCollection {
|
183 | [k: string]: CollectedScript;
|
184 | }
|
185 |
|
186 | /**
|
187 | * Return collection of available named scripts
|
188 | * - type user: User defined scripts from process.cwd/scripts/*.js
|
189 | * - type package: User defined scripts in package.json. These override 'user' scripts
|
190 | */
|
191 | export function collectScripts(): ScriptCollection;
|
192 |
|
193 | /**
|
194 | * Scripts can export this to control if and how they will be watched
|
195 | *
|
196 | * @example
|
197 | * ```js
|
198 | * // @type {CliWatchOptions}
|
199 | * export const cliWatchOptions = {
|
200 | * disable: false,
|
201 | * extensions: ["js"],
|
202 | * ignoredPatterns: ["docs"]
|
203 | * };
|
204 | * ```
|
205 | */
|
206 | export interface CliWatchOptions {
|
207 | /**
|
208 | * Disable watch mode
|
209 | */
|
210 | disable?: boolean;
|
211 |
|
212 | /**
|
213 | * Array of extensions to watch
|
214 | * Defaults to ["js", "json", "mjs", "cjs"]
|
215 | */
|
216 | extensions?: string[];
|
217 |
|
218 | /**
|
219 | * Ignore specific patterns
|
220 | * Can be strings or RegExp instances
|
221 | * Always ignores node_modules and `.dotfiles`
|
222 | */
|
223 | ignoredPatterns?: (string | RegExp)[];
|
224 | }
|