UNPKG

29.8 kBTypeScriptView Raw
1// Type definitions for QUnit v2.11.3
2// Project: http://qunitjs.com/
3// Definitions by: James Bracy <https://github.com/waratuman>
4// Mike North <https://github.com/mike-north>
5// Stefan Sechelmann <https://github.com/sechel>
6// Chris Krycho <https://github.com/chriskrycho>
7// Dan Freeman <https://github.com/dfreeman>
8// James C. Davis <https://github.com/jamescdavis>
9// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
10
11declare global {
12 interface Assert {
13 /**
14 * Instruct QUnit to wait for an asynchronous operation.
15 *
16 * The callback returned from `assert.async()` will throw an Error if it is
17 * invoked more than once (or more often than the accepted call count, if
18 * provided).
19 *
20 * This replaces functionality previously provided by `QUnit.stop()` and
21 * `QUnit.start()`.
22 *
23 * @param {number} [acceptCallCount=1] Number of expected callbacks before the test is done.
24 */
25 async(acceptCallCount?: number): () => void;
26
27 /**
28 * A deep recursive comparison, working on primitive types, arrays, objects,
29 * regular expressions, dates and functions.
30 *
31 * The `deepEqual()` assertion can be used just like `equal()` when comparing
32 * the value of objects, such that `{ key: value }` is equal to
33 * `{ key: value }`. For non-scalar values, identity will be disregarded by
34 * deepEqual.
35 *
36 * `notDeepEqual()` can be used to explicitly test deep, strict inequality.
37 *
38 * @param actual Object or Expression being tested
39 * @param expected Known comparision value
40 * @param {string} [message] A short description of the assertion
41 */
42 deepEqual<T>(actual: T, expected: T, message?: string): void;
43
44 /**
45 * A non-strict comparison, roughly equivalent to JUnit's assertEquals.
46 *
47 * The `equal` assertion uses the simple comparison operator (`==`) to
48 * compare the actual and expected arguments. When they are equal, the
49 * assertion passes; otherwise, it fails. When it fails, both actual and
50 * expected values are displayed in the test result, in addition to a given
51 * message.
52 *
53 * `notEqual()` can be used to explicitly test inequality.
54 *
55 * `strictEqual()` can be used to test strict equality.
56 *
57 * @param actual Expression being tested
58 * @param expected Known comparison value
59 * @param {string} [message] A short description of the assertion
60 */
61 equal(actual: any, expected: any, message?: string): void;
62
63 /**
64 * Specify how many assertions are expected to run within a test.
65 *
66 * To ensure that an explicit number of assertions are run within any test,
67 * use `assert.expect( number )` to register an expected count. If the
68 * number of assertions run does not match the expected count, the test will
69 * fail.
70 *
71 * @param {number} amount Number of assertions in this test.
72 */
73 expect(amount: number): void;
74
75 /**
76 * A strict comparison that passes if the first argument is boolean `false`.
77 *
78 * `false()` requires just one argument.
79 * If the first argument evaluates to false, the assertion passes; otherwise, it fails.
80 * If a second message argument is provided, it will be displayed in place of the result.
81 *
82 * @param state Expression being tested
83 * @param {string} message A short description of the assertion
84 */
85 false(state: any, message?: string): void;
86
87 /**
88 * An inverted deep recursive comparison, working on primitive types,
89 * arrays, objects, regular expressions, dates and functions.
90 *
91 * @param actual Object or Expression being tested
92 * @param expected Known comparison value
93 * @param {string} [message] A short description of the assertion
94 */
95 notDeepEqual(actual: any, expected: any, message?: string): void;
96
97 /**
98 * A non-strict comparison, checking for inequality.
99 *
100 * The `notEqual` assertion uses the simple inverted comparison operator
101 * (`!=`) to compare the actual and expected arguments. When they aren't
102 * equal, the assertion passes; otherwise, it fails. When it fails, both
103 * actual and expected values are displayed in the test result, in addition
104 * to a given message.
105 *
106 * `equal()` can be used to test equality.
107 *
108 * `notStrictEqual()` can be used to test strict inequality.
109 *
110 * @param actual Object or Expression being tested
111 * @param expected Known comparison value
112 * @param {string} [message] A short description of the assertion
113 */
114 notEqual(actual: any, expected: any, message?: string): void;
115
116 /**
117 * A boolean check, inverse of `ok()` and CommonJS's `assert.ok()`, and
118 * equivalent to JUnit's `assertFalse()`. Passes if the first argument is
119 * falsy.
120 *
121 * `notOk()` requires just one argument. If the argument evaluates to false,
122 * the assertion passes; otherwise, it fails. If a second message argument
123 * is provided, it will be displayed in place of the result.
124 *
125 * @param state Expression being tested
126 * @param {string} [message] A short description of the assertion
127 */
128 notOk(state: any, message?: string): void;
129
130 /**
131 * A strict comparison of an object's own properties, checking for inequality.
132 *
133 * The `notPropEqual` assertion uses the strict inverted comparison operator
134 * (`!==`) to compare the actual and expected arguments as Objects regarding
135 * only their properties but not their constructors.
136 *
137 * When they aren't equal, the assertion passes; otherwise, it fails. When
138 * it fails, both actual and expected values are displayed in the test
139 * result, in addition to a given message.
140 *
141 * `equal()` can be used to test equality.
142 *
143 * `propEqual()` can be used to test strict equality of an Object properties.
144 *
145 * @param actual Object or Expression being tested
146 * @param expected Known comparison value
147 * @param {string} [message] A short description of the assertion
148 */
149 notPropEqual(actual: any, expected: any, message?: string): void;
150
151 /**
152 * A strict comparison, checking for inequality.
153 *
154 * The `notStrictEqual` assertion uses the strict inverted comparison
155 * operator (`!==`) to compare the actual and expected arguments. When they
156 * aren't equal, the assertion passes; otherwise, it fails. When it fails,
157 * both actual and expected values are displayed in the test result, in
158 * addition to a given message.
159 *
160 * `equal()` can be used to test equality.
161 *
162 * `strictEqual()` can be used to test strict equality.
163 *
164 * @param actual Object or Expression being tested
165 * @param expected Known comparison value
166 * @param {string} [message] A short description of the assertion
167 */
168 notStrictEqual(actual: any, expected: any, message?: string): void;
169
170 /**
171 * A boolean check, equivalent to CommonJS's assert.ok() and JUnit's
172 * assertTrue(). Passes if the first argument is truthy.
173 *
174 * The most basic assertion in QUnit, ok() requires just one argument. If
175 * the argument evaluates to true, the assertion passes; otherwise, it
176 * fails. If a second message argument is provided, it will be displayed in
177 * place of the result.
178 *
179 * @param state Expression being tested
180 * @param {string} message A short description of the assertion
181 */
182 ok(state: any, message?: string): void;
183
184 /**
185 * A strict type and value comparison of an object's own properties.
186 *
187 * The `propEqual()` assertion provides strictly (`===`) comparison of
188 * Object properties. Unlike `deepEqual()`, this assertion can be used to
189 * compare two objects made with different constructors and prototype.
190 *
191 * `strictEqual()` can be used to test strict equality.
192 *
193 * `notPropEqual()` can be used to explicitly test strict inequality of
194 * Object properties.
195 *
196 * @param actual Object or Expression being tested
197 * @param expected Known comparison value
198 * @param {string} [message] A short description of the assertion
199 */
200 propEqual(actual: any, expected: any, message?: string): void;
201
202 /**
203 * Report the result of a custom assertion
204 *
205 * Some test suites may need to express an expectation that is not defined
206 * by any of QUnit's built-in assertions. This need may be met by
207 * encapsulating the expectation in a JavaScript function which returns a
208 * `Boolean` value representing the result; this value can then be passed
209 * into QUnit's `ok` assertion.
210 *
211 * A more readable solution would involve defining a custom assertion. If
212 * the expectation function invokes `pushResult`, QUnit will be notified of
213 * the result and report it accordingly.
214 *
215 * @param assertionResult The assertion result
216 */
217 pushResult(assertResult: { result: boolean; actual: any; expected: any; message: string }): void;
218
219 /**
220 * A strict type and value comparison.
221 *
222 * The `strictEqual()` assertion provides the most rigid comparison of type
223 * and value with the strict equality operator (`===`).
224 *
225 * `equal()` can be used to test non-strict equality.
226 *
227 * `notStrictEqual()` can be used to explicitly test strict inequality.
228 *
229 * @param actual Object or Expression being tested
230 * @param expected Known comparison value
231 * @param {string} [message] A short description of the assertion
232 */
233 strictEqual<T>(actual: T, expected: T, message?: string): void;
234
235 /**
236 * A strict comparison that passes if the first argument is boolean `true`.
237 *
238 * `true()` requires just one argument.
239 * If the first argument evaluates to true, the assertion passes; otherwise, it fails.
240 * If a second message argument is provided, it will be displayed in place of the result.
241 *
242 * @param state Expression being tested
243 * @param {string} message A short description of the assertion
244 */
245 true(state: any, message?: string): void;
246
247 /**
248 * Test if a callback throws an exception, and optionally compare the thrown
249 * error.
250 *
251 * When testing code that is expected to throw an exception based on a
252 * specific set of circumstances, use assert.throws() to catch the error
253 * object for testing and comparison.
254 *
255 * In very few environments, like Closure Compiler, throws is considered a
256 * reserved word and will cause an error. For that case, an alias is bundled
257 * called `raises`. It has the same signature and behaviour, just a
258 * different name.
259 */
260 throws(block: () => void, expected?: any, message?: any): void;
261 raises(block: () => void, expected?: any, message?: any): void;
262
263 /**
264 * Test if the provided promise rejects, and optionally compare the
265 * rejection value.
266 *
267 * When testing code that is expected to return a rejected promise based on
268 * a specific set of circumstances, use assert.rejects() for testing and
269 * comparison.
270 *
271 * The expectedMatcher argument can be:
272 * A function that returns true when the assertion should be considered passing.
273 * An Error object
274 * A base constructor to use ala rejectionValue instanceof expectedMatcher
275 * A RegExp that matches (or partially matches) rejectionValue.toString()
276 *
277 * Note: in order to avoid confusion between the message and the expectedMatcher,
278 * the expectedMatcher can not be a string.
279 *
280 * @param promise promise to test for rejection
281 * @param expectedMatcher Rejection value matcher
282 * @param message A short description of the assertion
283 */
284 rejects(promise: Promise<any>, message?: string): Promise<void>;
285 rejects(promise: Promise<any>, expectedMatcher?: any, message?: string): Promise<void>;
286
287 /**
288 * A marker for progress in a given test.
289 *
290 * The `step()` assertion registers a passing assertion with a provided message. This makes
291 * it easy to check that specific portions of code are being executed, especially in
292 * asynchronous test cases and when used with `verifySteps()`.
293 *
294 * Together with the `verifySteps()` method, `step()` assertions give you an easy way
295 * to verify both the count and order of code execution.
296 *
297 * @param message Message to display for the step
298 */
299 step(message: string): void;
300
301 /**
302 * A helper assertion to verify the order and number of steps in a test.
303 *
304 * The assert.verifySteps() assertion compares a given array of string values (representing steps)
305 * with the order and values of previous step() calls. This assertion is helpful for verifying
306 * the order and count of portions of code paths, especially asynchronous ones.
307 *
308 * @param steps Array of strings representing steps to verify
309 * @param message A short description of the assertion
310 */
311 verifySteps(steps: string[], message?: string): void;
312 }
313
314 interface Config {
315 altertitle: boolean;
316 autostart: boolean;
317 collapse: boolean;
318 current: any;
319 filter: string | RegExp;
320 fixture: string;
321 hidepassed: boolean;
322 maxDepth: number;
323 module: string;
324 moduleId: string[];
325 notrycatch: boolean;
326 noglobals: boolean;
327 seed: string;
328 reorder: boolean;
329 requireExpects: boolean;
330 testId: string[];
331 testTimeout: number;
332 scrolltop: boolean;
333 urlConfig: {
334 id?: string | undefined;
335 label?: string | undefined;
336 tooltip?: string | undefined;
337 value?: string | string[] | { [key: string]: string } | undefined;
338 }[];
339 }
340
341 interface Hooks {
342 /**
343 * Runs after the last test. If additional tests are defined after the
344 * module's queue has emptied, it will not run this hook again.
345 */
346 after?: ((assert: Assert) => void | Promise<void>) | undefined;
347
348 /**
349 * Runs after each test.
350 */
351 afterEach?: ((assert: Assert) => void | Promise<void>) | undefined;
352
353 /**
354 * Runs before the first test.
355 */
356 before?: ((assert: Assert) => void | Promise<void>) | undefined;
357
358 /**
359 * Runs before each test.
360 */
361 beforeEach?: ((assert: Assert) => void | Promise<void>) | undefined;
362 }
363
364 interface NestedHooks {
365 /**
366 * Runs after the last test. If additional tests are defined after the
367 * module's queue has emptied, it will not run this hook again.
368 */
369 after(fn: (assert: Assert) => void | Promise<void>): void;
370
371 /**
372 * Runs after each test.
373 */
374 afterEach(fn: (assert: Assert) => void | Promise<void>): void;
375
376 /**
377 * Runs before the first test.
378 */
379 before(fn: (assert: Assert) => void | Promise<void>): void;
380
381 /**
382 * Runs before each test.
383 */
384 beforeEach(fn: (assert: Assert) => void | Promise<void>): void;
385 }
386
387 type moduleFunc1 = (name: string, hooks?: Hooks, nested?: (hooks: NestedHooks) => void) => void;
388 type moduleFunc2 = (name: string, nested?: (hooks: NestedHooks) => void) => void;
389 type ModuleOnly = { only: moduleFunc1 & moduleFunc2 };
390 type ModuleSkip = { skip: moduleFunc1 & moduleFunc2 };
391 type ModuleTodo = { todo: moduleFunc1 & moduleFunc2 };
392
393 namespace QUnit {
394 interface BeginDetails {
395 totalTests: number;
396 }
397 interface DoneDetails {
398 failed: number;
399 passed: number;
400 total: number;
401 runtime: number;
402 }
403 interface LogDetails {
404 result: boolean;
405 actual: any;
406 expected: any;
407 message: string;
408 source: string;
409 module: string;
410 name: string;
411 runtime: number;
412 }
413 interface ModuleDoneDetails {
414 name: string;
415 failed: number;
416 passed: number;
417 total: number;
418 runtime: number;
419 }
420 interface ModuleStartDetails {
421 name: string;
422 }
423 interface TestDoneDetails {
424 name: string;
425 module: string;
426 failed: number;
427 passed: number;
428 total: number;
429 runtime: number;
430 }
431 interface TestStartDetails {
432 name: string;
433 module: string;
434 }
435 }
436
437 interface QUnit {
438 /**
439 * Namespace for QUnit assertions
440 *
441 * QUnit's built-in assertions are defined on the `QUnit.assert` object. An
442 * instance of this object is passed as the only argument to the `QUnit.test`
443 * function callback.
444 *
445 * This object has properties for each of QUnit's built-in assertion methods.
446 */
447 assert: Assert;
448
449 /**
450 * Register a callback to fire whenever the test suite begins.
451 *
452 * `QUnit.begin()` is called once before running any tests.
453 *
454 * @callback callback Callback to execute.
455 */
456 begin(callback: (details: QUnit.BeginDetails) => void | Promise<void>): void;
457
458 /**
459 * Configuration for QUnit
460 *
461 * QUnit has a bunch of internal configuration defaults, some of which are
462 * useful to override. Check the description for each option for details.
463 */
464 config: Config;
465
466 /**
467 * Register a callback to fire whenever the test suite ends.
468 *
469 * @param callback Callback to execute
470 */
471 done(callback: (details: QUnit.DoneDetails) => void | Promise<void>): void;
472
473 /**
474 * Advanced and extensible data dumping for JavaScript.
475 *
476 * This method does string serialization by parsing data structures and
477 * objects. It parses DOM elements to a string representation of their outer
478 * HTML. By default, nested structures will be displayed up to five levels
479 * deep. Anything beyond that is replaced by `[object Object]` and
480 * `[object Array]` placeholders.
481 *
482 * If you need more or less output, change the value of `QUnit.dump.maxDepth`,
483 * representing how deep the elements should be parsed.
484 *
485 * Note: This method used to be in QUnit.jsDump, which was changed to
486 * QUnit.dump. The old property will be removed in QUnit 3.0.
487 */
488 dump: {
489 maxDepth: number;
490 parse(data: any): string;
491 };
492
493 /**
494 * Copy the properties defined by the `mixin` object into the `target` object.
495 *
496 * This method will modify the `target` object to contain the "own" properties
497 * defined by the `mixin`. If the `mixin` object specifies the value of any
498 * attribute as undefined, this property will instead be removed from the
499 * `target` object.
500 *
501 * @param target An object whose properties are to be modified
502 * @param mixin An object describing which properties should be modified
503 */
504 extend(target: any, mixin: any): void;
505
506 /**
507 * Register a callback to fire whenever an assertion completes.
508 *
509 * This is one of several callbacks QUnit provides. Its intended for
510 * integration scenarios like PhantomJS or Jenkins. The properties of the
511 * details argument are listed below as options.
512 *
513 * @param callback Callback to execute
514 */
515 log(callback: (details: QUnit.LogDetails) => void): void;
516
517 /**
518 * Group related tests under a single label.
519 *
520 * You can use the module name to organize, select, and filter tests to run.
521 *
522 * All tests inside a module callback function will be grouped into that
523 * module. The test names will all be preceded by the module name in the
524 * test results. Other modules can be nested inside this callback function,
525 * where their tests' names will be labeled by their names recursively
526 * prefixed by their parent modules.
527 *
528 * If `QUnit.module` is defined without a `nested` callback argument, all
529 * subsequently defined tests will be grouped into the module until another
530 * module is defined.
531 *
532 * Modules with test group functions allow you to define nested modules, and
533 * QUnit will run tests on the parent module before going deep on the nested
534 * ones, even if they're declared first. Additionally, any hook callbacks on
535 * a parent module will wrap the hooks on a nested module. In other words,
536 * `before` and `beforeEach` callbacks will form a queue while the
537 * `afterEach` and `after` callbacks will form a stack.
538 *
539 * You can specify code to run before and after tests using the hooks
540 * argument, and also to create properties that will be shared on the
541 * testing context. Any additional properties on the `hooks` object will be
542 * added to that context. The `hooks` argument is still optional if you call
543 * `QUnit.module` with a callback argument.
544 *
545 * The module's callback is invoked with the test environment as its `this`
546 * context, with the environment's properties copied to the module's tests,
547 * hooks, and nested modules. Note that changes on tests' `this` are not
548 * preserved between sibling tests, where `this` will be reset to the initial
549 * value for each test.
550 *
551 * @param {string} name Label for this group of tests
552 * @param hookds Callbacks to run during test execution
553 * @param nested A callback with grouped tests and nested modules to run under the current module label
554 */
555 module: moduleFunc1 & moduleFunc2 & ModuleOnly & ModuleSkip & ModuleTodo;
556
557 /**
558 * Register a callback to fire whenever a module ends.
559 *
560 * @param callback Callback to execute
561 */
562 moduleDone(callback: (details: QUnit.ModuleDoneDetails) => void | Promise<void>): void;
563
564 /**
565 * Register a callback to fire whenever a module begins.
566 *
567 * @param callback Callback to execute
568 */
569 moduleStart(callback: (details: QUnit.ModuleStartDetails) => void | Promise<void>): void;
570
571 /**
572 * Adds a test to exclusively run, preventing all other tests from running.
573 *
574 * Use this method to focus your test suite on a specific test. QUnit.only
575 * will cause any other tests in your suite to be ignored.
576 *
577 * Note, that if more than one QUnit.only is present only the first instance
578 * will run.
579 *
580 * This is an alternative to filtering tests to run in the HTML reporter. It
581 * is especially useful when you use a console reporter or in a codebase
582 * with a large set of long running tests.
583 *
584 * @param {string} name Title of unit being tested
585 * @param callback Function to close over assertions
586 */
587 only(name: string, callback: (assert: Assert) => void | Promise<void>): void;
588
589 /**
590 * DEPRECATED: Report the result of a custom assertion.
591 *
592 * This method is deprecated and it's recommended to use pushResult on its
593 * direct reference in the assertion context.
594 *
595 * QUnit.push reflects to the current running test, and it may leak
596 * assertions in asynchronous mode. Checkout assert.pushResult() to set a
597 * proper custom assertion.
598 *
599 * Invoking QUnit.push allows to create a readable expectation that is not
600 * defined by any of QUnit's built-in assertions.
601 *
602 * @deprecated
603 */
604 push(result: boolean, actual: any, expected: any, message: string): void;
605
606 /**
607 * Adds a test like object to be skipped.
608 *
609 * Use this method to replace QUnit.test() instead of commenting out entire
610 * tests.
611 *
612 * This test's prototype will be listed on the suite as a skipped test,
613 * ignoring the callback argument and the respective global and module's
614 * hooks.
615 *
616 * @param {string} Title of unit being tested
617 */
618 skip(name: string, callback?: (assert: Assert) => void | Promise<void>): void;
619
620 /**
621 * Returns a single line string representing the stacktrace (call stack).
622 *
623 * This method returns a single line string representing the stacktrace from
624 * where it was called. According to its offset argument, `QUnit.stack()` will
625 * return the correspondent line from the call stack.
626 *
627 * The default `offset` is `0` and will return the current location where it
628 * was called.
629 *
630 * Not all browsers support retrieving stracktraces. In those, `QUnit.stack()`
631 * will return undefined.
632 *
633 * @param {number} offset Set the stacktrace line offset.
634 */
635 stack(offset?: number): string;
636
637 /**
638 * `QUnit.start()` must be used to start a test run that has
639 * `QUnit.config.autostart` set to `false`.
640 *
641 * This method was previously used to control async tests on text contexts
642 * along with QUnit.stop. For asynchronous tests, use assert.async instead.
643 *
644 * When your async test has multiple exit points, call `QUnit.start()` for the
645 * corresponding number of `QUnit.stop()` increments.
646 */
647 start(): void;
648
649 /**
650 * Add a test to run.
651 *
652 * Add a test to run using `QUnit.test()`.
653 *
654 * The `assert` argument to the callback contains all of QUnit's assertion
655 * methods. Use this argument to call your test assertions.
656 *
657 * `QUnit.test()` can automatically handle the asynchronous resolution of a
658 * Promise on your behalf if you return a thenable Promise as the result of
659 * your callback function.
660 *
661 * @param {string} Title of unit being tested
662 * @param callback Function to close over assertions
663 */
664 test(name: string, callback: (assert: Assert) => void | Promise<void>): void;
665
666 /**
667 * Register a callback to fire whenever a test ends.
668 *
669 * @param callback Callback to execute
670 */
671 testDone(
672 callback: (details: {
673 name: string;
674 module: string;
675 failed: number;
676 passed: number;
677 total: number;
678 runtime: number;
679 }) => void | Promise<void>,
680 ): void;
681
682 /**
683 * Register a callback to fire whenever a test begins.
684 *
685 * @param callback Callback to execute
686 */
687 testStart(callback: (details: QUnit.TestStartDetails) => void | Promise<void>): void;
688
689 /**
690 * Adds a test which expects at least one failing assertion during its run.
691 *
692 * Use this method to test a unit of code which is still under development
693 * (in a “todo” state). The test will pass as long as one failing assertion
694 * is present.
695 *
696 * If all assertions pass, then the test will fail signaling that QUnit.todo
697 * should be replaced by QUnit.test.
698 *
699 * @param {string} Title of unit being tested
700 * @param callback Function to close over assertions
701 */
702 todo(name: string, callback?: (assert: Assert) => void | Promise<void>): void;
703
704 /**
705 * Compares two values. Returns true if they are equivalent.
706 *
707 * @param a The first value
708 * @param b The second value
709 */
710 equiv<T>(a: T, b: T): boolean;
711
712 /**
713 * Are the test running from the server or not.
714 */
715 isLocal: boolean;
716
717 /**
718 * QUnit version
719 */
720 version: string;
721 }
722
723 /* QUnit */
724 const QUnit: QUnit;
725}
726
727export = QUnit;