1 | /// <reference types="node" />
|
2 |
|
3 | /**
|
4 | * Creates a test script.
|
5 | *
|
6 | * @param options - script creation options.
|
7 | *
|
8 | * @returns a script interface.
|
9 | */
|
10 | export function script(options?: script.Options): script.Script;
|
11 |
|
12 | declare namespace script {
|
13 |
|
14 | interface Options {
|
15 |
|
16 | /**
|
17 | * Determines if execution of tests should be delayed until the CLI runs them explicitly.
|
18 | *
|
19 | * @default true
|
20 | */
|
21 | schedule?: boolean;
|
22 |
|
23 | /**
|
24 | *
|
25 | */
|
26 | cli?: Cli;
|
27 | }
|
28 |
|
29 | interface Cli {
|
30 |
|
31 | /**
|
32 | * Specifies an assertion library module path to require and make available under Lab.assertions as well as use for enhanced reporting.
|
33 | */
|
34 | readonly assert?: string;
|
35 |
|
36 | /**
|
37 | * Forces the process to exist with a non zero exit code on the first test failure.
|
38 | *
|
39 | * @default false
|
40 | */
|
41 | readonly bail?: boolean;
|
42 |
|
43 | /**
|
44 | * Enables color output.
|
45 | *
|
46 | * @default terminal capabilities.
|
47 | */
|
48 | readonly colors?: boolean;
|
49 |
|
50 | /**
|
51 | * Sets a timeout value for before, after, beforeEach, afterEach in milliseconds.
|
52 | *
|
53 | * @default 0
|
54 | */
|
55 | readonly 'context-timeout'?: number;
|
56 |
|
57 | /**
|
58 | * Enable code coverage analysis
|
59 | *
|
60 | * @default false
|
61 | */
|
62 | readonly coverage?: boolean;
|
63 |
|
64 | /**
|
65 | * Includes all files in coveragePath in report.
|
66 | *
|
67 | * @default false
|
68 | */
|
69 | readonly 'coverage-all'?: boolean;
|
70 |
|
71 | /**
|
72 | * Set code coverage excludes (an array of path strings).
|
73 | */
|
74 | readonly 'coverage-exclude'?: string[];
|
75 |
|
76 | /**
|
77 | * Prevents recursive inclusion of all files in coveragePath in report.
|
78 | *
|
79 | * @default false
|
80 | */
|
81 | readonly 'coverage-flat'?: boolean;
|
82 |
|
83 | /**
|
84 | * Enables coverage on external modules.
|
85 | */
|
86 | readonly 'coverage-module'?: string[];
|
87 |
|
88 | /**
|
89 | * Sets code coverage path.
|
90 | */
|
91 | readonly 'coverage-path'?: string;
|
92 |
|
93 | /**
|
94 | * File pattern to use for locating files for coverage.
|
95 | */
|
96 | readonly coveragePattern?: RegExp;
|
97 |
|
98 | /**
|
99 | * Minimum plan threshold to apply to all tests that don't define any plan.
|
100 | */
|
101 | readonly 'default-plan-threshold'?: number;
|
102 |
|
103 | /**
|
104 | * Skip all tests (dry run).
|
105 | *
|
106 | * @default: false
|
107 | */
|
108 | readonly dry?: boolean;
|
109 |
|
110 | /**
|
111 | * Value to set NODE_ENV before tests.
|
112 | *
|
113 | * @default: 'test'
|
114 | */
|
115 | readonly environment?: string;
|
116 |
|
117 | /**
|
118 | * Number of times to retry failing tests (marked explicitly for retry).
|
119 | *
|
120 | * @default 5
|
121 | */
|
122 | readonly retries?: number;
|
123 |
|
124 | /**
|
125 | * Prevent recursive collection of tests within the provided path.
|
126 | *
|
127 | * @default false
|
128 | */
|
129 | readonly flat?: boolean;
|
130 |
|
131 | /**
|
132 | * Sets a list of globals to ignore for the leak detection (comma separated).
|
133 | */
|
134 | readonly globals?: string[];
|
135 |
|
136 | /**
|
137 | * Only run tests matching the given pattern which is internally compiled to a RegExp.
|
138 | */
|
139 | readonly grep?: string;
|
140 |
|
141 | /**
|
142 | * Range of test ids to execute.
|
143 | */
|
144 | readonly id?: number[];
|
145 |
|
146 | /**
|
147 | * Sets lab to start with the node.js native debugger.
|
148 | *
|
149 | * @default false
|
150 | */
|
151 | readonly inspect?: boolean;
|
152 |
|
153 | /**
|
154 | * Sets global variable leaks detection.
|
155 | *
|
156 | * @default true
|
157 | */
|
158 | readonly leaks?: boolean;
|
159 |
|
160 | /**
|
161 | * Enables code lint.
|
162 | *
|
163 | * @default false
|
164 | */
|
165 | readonly lint?: boolean;
|
166 |
|
167 | /**
|
168 | * Linter path.
|
169 | *
|
170 | * @default 'eslint'
|
171 | */
|
172 | readonly linter?: string;
|
173 |
|
174 | /**
|
175 | * Apply any fixes from the linter.
|
176 | *
|
177 | * @default false
|
178 | */
|
179 | readonly 'lint-fix'?: boolean;
|
180 |
|
181 | /**
|
182 | * Options to pass to linting program. It must be a string that is JSON.parse(able).
|
183 | */
|
184 | readonly 'lint-options'?: string;
|
185 |
|
186 | /**
|
187 | * Linter errors threshold in absolute value.
|
188 | *
|
189 | * @default 0
|
190 | */
|
191 | readonly 'lint-errors-threshold': number;
|
192 |
|
193 | /**
|
194 | * Linter warnings threshold in absolute value.
|
195 | *
|
196 | * @default 0
|
197 | */
|
198 | readonly 'lint-warnings-threshold': number;
|
199 |
|
200 | /**
|
201 | * File path to write test results. When set to an array, the array size must match the reporter option array.
|
202 | *
|
203 | * @default stdout
|
204 | */
|
205 | readonly output?: string | string[];
|
206 |
|
207 | /**
|
208 | * File paths to load tests from.
|
209 | *
|
210 | * @default ['test']
|
211 | */
|
212 | readonly path?: string[];
|
213 |
|
214 | /**
|
215 | * File pattern to use for locating tests (must include file extensions).
|
216 | */
|
217 | readonly pattern?: RegExp;
|
218 |
|
219 | /**
|
220 | * Reporter type. One of: 'console', 'html', 'json', 'tap', 'lcov', 'clover', 'junit'.
|
221 | *
|
222 | * @default 'console'
|
223 | */
|
224 | readonly reporter?: string | string[];
|
225 |
|
226 | /**
|
227 | * Random number seed when shuffle is enabled.
|
228 | */
|
229 | readonly seed?: string;
|
230 |
|
231 | /**
|
232 | * Shuffle script execution order.
|
233 | *
|
234 | * @default false
|
235 | */
|
236 | readonly shuffle: boolean;
|
237 |
|
238 | /**
|
239 | * Silence skipped tests.
|
240 | *
|
241 | * @default false
|
242 | */
|
243 | readonly 'silent-skips'?: boolean;
|
244 |
|
245 | /**
|
246 | * Enable support for sourcemaps.
|
247 | *
|
248 | * @default false
|
249 | */
|
250 | readonly sourcemaps?: boolean;
|
251 |
|
252 | /**
|
253 | * Code coverage threshold percentage.
|
254 | */
|
255 | readonly threshold?: number;
|
256 |
|
257 | /**
|
258 | * Timeout for each test in milliseconds.
|
259 | *
|
260 | * @default 2000
|
261 | */
|
262 | readonly timeout?: number;
|
263 |
|
264 | /**
|
265 | * Transformers for non-js file types.
|
266 | */
|
267 | readonly transform?: Transformer[];
|
268 |
|
269 | /**
|
270 | * Test types definitions.
|
271 | *
|
272 | * @default false
|
273 | */
|
274 | readonly types?: boolean;
|
275 |
|
276 | /**
|
277 | * Location of types definitions test file.
|
278 | */
|
279 | readonly 'types-test'?: string;
|
280 |
|
281 | /**
|
282 | * Sets output verbosity (0: none, 1: normal, 2: verbose).
|
283 | *
|
284 | * @default 1
|
285 | */
|
286 | readonly progress?: number;
|
287 | }
|
288 |
|
289 | interface Transformer {
|
290 |
|
291 | readonly ext: string;
|
292 |
|
293 | transform(content: string, filename: string): string;
|
294 | }
|
295 |
|
296 | interface Script {
|
297 | after: Setup;
|
298 | afterEach: Setup;
|
299 | before: Setup;
|
300 | beforeEach: Setup;
|
301 |
|
302 | describe: Experiment;
|
303 | experiment: Experiment;
|
304 | suite: Experiment;
|
305 |
|
306 | it: Test;
|
307 | test: Test;
|
308 | }
|
309 |
|
310 | interface Setup {
|
311 |
|
312 | (action: Action): void;
|
313 | (options: TestOptions, action: Action): void;
|
314 | }
|
315 |
|
316 | interface Experiment {
|
317 |
|
318 | (title: string, content: () => void): void;
|
319 | (title: string, options: Omit<TestOptions, 'plan'>, content: () => void): void;
|
320 |
|
321 | only(title: string, content: () => void): void;
|
322 | only(title: string, options: Omit<TestOptions, 'plan'>, content: () => void): void;
|
323 |
|
324 | skip(title: string, content: () => void): void;
|
325 | skip(title: string, options: Omit<TestOptions, 'plan'>, content: () => void): void;
|
326 | }
|
327 |
|
328 | interface Test {
|
329 |
|
330 | (title: string, test: Action): void;
|
331 | (title: string, options: TestOptions, test: Action): void;
|
332 |
|
333 | only(title: string, test: Action): void;
|
334 | only(title: string, options: TestOptions, test: Action): void;
|
335 |
|
336 | skip(title: string, test: Action): void;
|
337 | skip(title: string, options: TestOptions, test: Action): void;
|
338 | }
|
339 |
|
340 | interface Action {
|
341 |
|
342 | <T>(flags: Flags): Promise<T> | void;
|
343 | (flags: Flags): void;
|
344 | }
|
345 |
|
346 | interface TestOptions {
|
347 |
|
348 | /**
|
349 | * Sets the entire experiment content to be skipped during execution.
|
350 | *
|
351 | * @default false
|
352 | */
|
353 | readonly skip?: boolean;
|
354 |
|
355 | /**
|
356 | * Sets all other experiments to skip.
|
357 | *
|
358 | * @default false
|
359 | */
|
360 | readonly only?: boolean;
|
361 |
|
362 | /**
|
363 | * Overrides the default test timeout for tests and other timed operations in milliseconds.
|
364 | *
|
365 | * @default 2000
|
366 | */
|
367 | readonly timeout?: number;
|
368 |
|
369 | /**
|
370 | * The expected number of assertions the test must execute.
|
371 | */
|
372 | readonly plan?: number;
|
373 |
|
374 | /**
|
375 | * Set the test to be retried a few times when it fails. Can be set to true to used the default number of retries or an exact number of maximum retries.
|
376 | *
|
377 | * @default false
|
378 | */
|
379 | readonly retry?: number | boolean;
|
380 | }
|
381 |
|
382 | interface Flags {
|
383 |
|
384 | /**
|
385 | * An object that is passed to `before` and `after` functions in addition to tests themselves.
|
386 | */
|
387 | readonly context: Record<string, any>;
|
388 |
|
389 | /**
|
390 | * Sets a requirement that a function must be called a certain number of times.
|
391 | *
|
392 | * @param func - the function to be called.
|
393 | * @param count - the number of required invocations.
|
394 | *
|
395 | * @returns a wrapped function.
|
396 | */
|
397 | mustCall<T extends (...args: any[]) => any>(func: T, count: number): T;
|
398 |
|
399 | /**
|
400 | * Adds notes to the test log.
|
401 | *
|
402 | * @param note - a string to be included in the console reporter at the end of the output.
|
403 | */
|
404 | note(note: string): void;
|
405 |
|
406 | /**
|
407 | * A property that can be assigned a cleanup function registered at runtime to be executed after the test completes.
|
408 | */
|
409 | onCleanup?: Action;
|
410 |
|
411 | /**
|
412 | * A property that can be assigned an override for global exception handling.
|
413 | */
|
414 | onUncaughtException?: ErrorHandler;
|
415 |
|
416 | /**
|
417 | * A property that can be assigned an override function for global rejection handling.
|
418 | */
|
419 | onUnhandledRejection?: ErrorHandler;
|
420 | }
|
421 |
|
422 | interface ErrorHandler {
|
423 |
|
424 | (err: Error): void;
|
425 | }
|
426 | }
|
427 |
|
428 |
|
429 | export const types: types.Types;
|
430 |
|
431 | declare namespace types {
|
432 |
|
433 | interface Types {
|
434 | expect: Expect;
|
435 | }
|
436 |
|
437 | interface Expect {
|
438 |
|
439 | /**
|
440 | * Assert the type of the value expected
|
441 | *
|
442 | * @param value - the value being asserted.
|
443 | */
|
444 | type<T>(value: T): void;
|
445 |
|
446 | /**
|
447 | * Assert the value to throw an argument error
|
448 | *
|
449 | * @param value - the value being asserted.
|
450 | */
|
451 | error<T = any>(value: T): void;
|
452 | }
|
453 | }
|