Debian Codegraph @

addons/web/static/lib/hoot/core/runner.js

raw
1 /** @odoo-module */
2
3 import { on, setFrameRate } from "@odoo/hoot-dom";
4 import { markRaw, reactive, toRaw } from "@odoo/owl";
5 import { cleanupDOM, defineRootNode } from "@web/../lib/hoot-dom/helpers/dom";
6 import { cleanupEvents, enableEventLogs } from "@web/../lib/hoot-dom/helpers/events";
7 import { cleanupTime, setupTime } from "@web/../lib/hoot-dom/helpers/time";
8 import { exposeHelpers, isInstanceOf, isIterable } from "@web/../lib/hoot-dom/hoot_dom_utils";
9 import {
10 CASE_EVENT_TYPES,
11 Callbacks,
12 HootError,
13 INCLUDE_LEVEL,
14 Markup,
15 STORAGE,
16 batch,
17 createReporting,
18 deepEqual,
19 ensureArray,
20 ensureError,
21 formatHumanReadable,
22 formatTechnical,
23 formatTime,
24 isLabel,
25 normalize,
26 parseQuery,
27 storageGet,
28 storageSet,
29 stringify,
30 } from "../hoot_utils";
31 import { cleanupAnimations } from "../mock/animation";
32 import { cleanupDate } from "../mock/date";
33 import { internalRandom } from "../mock/math";
34 import { cleanupNavigator } from "../mock/navigator";
35 import { cleanupNetwork, throttleNetwork } from "../mock/network";
36 import {
37 cleanupWindow,
38 getViewPortHeight,
39 getViewPortWidth,
40 mockTouch,
41 setupWindow,
42 } from "../mock/window";
43 import { DEFAULT_CONFIG, FILTER_KEYS } from "./config";
44 import { makeExpect } from "./expect";
45 import { destroy, makeFixtureManager } from "./fixture";
46 import { logger } from "./logger";
47 import { Suite, suiteError } from "./suite";
48 import { Tag, getTagSimilarities, getTags } from "./tag";
49 import { Test, testError } from "./test";
50 import { EXCLUDE_PREFIX, createUrlFromId, setParams } from "./url";
51
52 // Import all helpers for debug mode
53 import * as _hootDom from "@odoo/hoot-dom";
54 import * as _animation from "../mock/animation";
55 import * as _date from "../mock/date";
56 import * as _math from "../mock/math";
57 import * as _navigator from "../mock/navigator";
58 import * as _network from "../mock/network";
59 import * as _notification from "../mock/notification";
60 import * as _window from "../mock/window";
61
62 const { isPrevented, mockPreventDefault } = _window;
63
64 /**
65 * @typedef {{
66 * readonly config: (config: JobConfig) => CurrentConfigurators;
67 * readonly debug: () => CurrentConfigurators;
68 * readonly multi: (count: number) => CurrentConfigurators;
69 * readonly only: () => CurrentConfigurators;
70 * readonly skip: () => CurrentConfigurators;
71 * readonly tags: (...tags: string[]) => CurrentConfigurators;
72 * readonly timeout: (ms: number) => CurrentConfigurators;
73 * readonly todo: () => CurrentConfigurators;
74 * }} CurrentConfigurators
75 *
76 * @typedef {{
77 * count: number;
78 * message: string;
79 * name: string;
80 * }} GlobalIssueReport
81 *
82 * @typedef {Suite | Test} Job
83 *
84 * @typedef {import("./job").JobConfig} JobConfig
85 *
86 * @typedef {{
87 * icon?: string;
88 * label: string;
89 * platform?: import("../mock/navigator").Platform;
90 * size?: [number, number];
91 * tags?: string[];
92 * touch?: boolean;
93 * }} Preset
94 *
95 * @typedef {import("./config").SearchFilter} SearchFilter
96 */
97
98 /**
99 * @template T
100 * @typedef {(payload: T) => MaybePromise<any>} Callback
101 */
102
103 /**
104 * @template {unknown[]} T
105 * @typedef {import("../hoot_utils").DropFirst} DropFirst
106 */
107
108 /**
109 * @template T
110 * @typedef {T | PromiseLike<T>} MaybePromise
111 */
112
113 //-----------------------------------------------------------------------------
114 // Global
115 //-----------------------------------------------------------------------------
116
117 const {
118 clearTimeout,
119 console: { error: $error },
120 EventTarget,
121 Map,
122 Math: { abs: $abs, floor: $floor },
123 Number: { parseFloat: $parseFloat },
124 Object: {
125 assign: $assign,
126 defineProperty: $defineProperty,
127 entries: $entries,
128 freeze: $freeze,
129 fromEntries: $fromEntries,
130 keys: $keys,
131 values: $values,
132 },
133 performance,
134 Promise,
135 removeEventListener,
136 Set,
137 setTimeout,
138 window,
139 } = globalThis;
140 /** @type {Performance["now"]} */
141 const $now = performance.now.bind(performance);
142
143 //-----------------------------------------------------------------------------
144 // Internal
145 //-----------------------------------------------------------------------------
146
147 /**
148 * @param {Job[]} jobs
149 */
150 function filterReady(jobs) {
151 return jobs.filter((job) => {
152 if (job instanceof Suite) {
153 job.setCurrentJobs(filterReady(job.currentJobs));
154 return job.currentJobs.length;
155 }
156 return job.run;
157 });
158 }
159
160 /**
161 * @param {Record<string, number>} values
162 */
163 function formatIncludes(values) {
164 return $entries(values)
165 .filter(([, value]) => $abs(value) === INCLUDE_LEVEL.url)
166 .map(([id, value]) => (value >= 0 ? id : `${EXCLUDE_PREFIX}${id}`));
167 }
168
169 /**
170 * @param {import("./expect").Assertion[]} assertions
171 */
172 function formatAssertions(assertions) {
173 const lines = [];
174 for (const { additionalMessage, failedDetails, label, message, number } of assertions) {
175 const formattedMessage = message.map((part) => (isLabel(part) ? part[0] : String(part)));
176 if (additionalMessage) {
177 formattedMessage.push(`(${additionalMessage})`);
178 }
179 lines.push(`\n${number}. [${label}] ${formattedMessage.join(" ")}`);
180 if (failedDetails) {
181 for (const detail of failedDetails) {
182 if (Markup.isMarkup(detail, "group")) {
183 lines.push(
184 `${number}.${detail.groupIndex}. (${formatHumanReadable(detail.content)})`
185 );
186 continue;
187 }
188 let [key, value] = detail;
189 if (Markup.isMarkup(key)) {
190 key = key.content;
191 }
192 if (Markup.isMarkup(value)) {
193 if (value.type === "technical") {
194 continue;
195 }
196 value = value.content;
197 }
198 lines.push(`> ${key} ${formatTechnical(value)}`);
199 }
200 }
201 }
202 return lines;
203 }
204
205 /**
206 * @template T
207 * @param {T[]} array
208 */
209 function shuffle(array) {
210 const copy = [...array];
211 let randIndex;
212 for (let i = 0; i < copy.length; i++) {
213 randIndex = $floor(internalRandom() * copy.length);
214 [copy[i], copy[randIndex]] = [copy[randIndex], copy[i]];
215 }
216 return copy;
217 }
218
219 /**
220 * @param {Test} test
221 * @param {boolean} shouldSuppress
222 */
223 function handleConsoleIssues(test, shouldSuppress) {
224 if (shouldSuppress && test.config.todo) {
225 return logger.setIssueLevel("suppressed");
226 } else {
227 const cleanups = [];
228 if (isInstanceOf(globalThis.console, EventTarget)) {
229 cleanups.push(
230 on(globalThis.console, "error", () => test.logs.error++),
231 on(globalThis.console, "warn", () => test.logs.warn++)
232 );
233 }
234
235 return function offConsoleEvents() {
236 while (cleanups.length) {
237 cleanups.pop()();
238 }
239 };
240 }
241 }
242
243 /**
244 * @param {Event} ev
245 */
246 function warnUserEvent(ev) {
247 if (!ev.isTrusted) {
248 return;
249 }
250
251 logger.global.warn(
252 `User event detected: "${ev.type}"\n\n`,
253 `This kind of interaction can interfere with the current test and should be avoided.`
254 );
255
256 removeEventListener(ev.type, warnUserEvent);
257 }
258
259 const WARNINGS = {
260 viewport: "Viewport size does not match the expected size for the current preset",
261 tagNames:
262 "The following tag names are very similar to each other and may be confusing for other developers:",
263 };
264 const RESIZE_OBSERVER_MESSAGE = "ResizeObserver loop completed with undelivered notifications";
265 const handledErrors = new WeakSet();
266 /** @type {string | null} */
267 let lastPresetWarn = null;
268
269 //-----------------------------------------------------------------------------
270 // Exports
271 //-----------------------------------------------------------------------------
272
273 export class Runner {
274 static URL_SPEC = 1;
275 static TAG_SPEC = 2;
276 static PRESET_SPEC = 3;
277
278 // Properties
279 aborted = false;
280 /** @type {boolean | Test | Suite} */
281 debug = false;
282 dry = false;
283 /** @type {ReturnType<typeof makeExpect>[0]} */
284 expect;
285 /** @type {ReturnType<typeof makeExpect>[1]} */
286 expectHooks;
287 headless = false;
288 /** @type {Record<string, Preset>} */
289 presets = {
290 [""]: { label: "No preset" },
291 };
292 reporting = createReporting();
293 /** @type {Suite[]} */
294 rootSuites = [];
295 state = {
296 /** @type {Test | null} */
297 currentTest: null,
298 /**
299 * List of tests that have been run
300 * @type {Set<Test>}
301 */
302 done: new Set(),
303 /**
304 * List of IDs of tests that have failed (previously AND during this run).
305 */
306 failedIds: new Set(storageGet(STORAGE.failed)),
307 /**
308 * @type {Record<string, GlobalIssueReport>}
309 */
310 globalErrors: {},
311 /**
312 * @type {Record<string, GlobalIssueReport>}
313 */
314 globalWarnings: {},
315 /**
316 * Dictionnary containing whether a job is included or excluded from the
317 * current run. Values are numbers defining priority:
318 * - 0: inherits inclusion status from parent object
319 * - +1/-1: included/excluded by URL
320 * - +2/-2: included/excluded by explicit test tag (readonly)
321 * - +3/-3: included/excluded by preset (readonly)
322 * @type {Record<"id" | "tag", Record<string, number>>}
323 */
324 includeSpecs: {
325 id: {},
326 tag: {},
327 },
328 /** @type {"ready" | "running" | "done"} */
329 status: "ready",
330 /**
331 * List of suites that will be run (only available after {@link Runner.start})
332 * @type {Suite[]}
333 */
334 suites: [],
335 /**
336 * List of tests that will be run (only available after {@link Runner.start})
337 * @type {Test[]}
338 */
339 tests: [],
340 };
341 /** @type {Map<string, Suite>} */
342 suites = new Map();
343 /** @type {Suite[]} */
344 suiteStack = [];
345 /** @type {Map<string, Tag>} */
346 tags = new Map();
347 /** @type {Map<string, Test>} */
348 tests = new Map();
349 /** @type {import("../hoot_utils").QueryPart[]} */
350 queryExclude = [];
351 /** @type {import("../hoot_utils").QueryPart[]} */
352 queryInclude = [];
353 totalTime = "n/a";
354
355 /**
356 * @type {boolean}
357 */
358 get hasFilter() {
359 for (const includeValues of $values(this.state.includeSpecs)) {
360 if ($keys(includeValues).length > 0) {
361 return true;
362 }
363 }
364 return false;
365 }
366
367 /**
368 * @type {boolean}
369 */
370 get hasRemovableFilter() {
371 return this._removableFilterCount > 0;
372 }
373
374 // Private properties
375 _callbacks = new Callbacks();
376 /** @type {Job[]} */
377 _currentJobs = [];
378 _failed = 0;
379 _includeFilterCount = 0;
380 /** @type {(() => MaybePromise<void>)[]} */
381 _missedCallbacks = [];
382 _populateState = false;
383 _prepared = false;
384 /** @type {() => void} */
385 _pushPendingTest = () => {};
386 /** @type {(test: Test) => void} */
387 _pushTest = () => {};
388 _removableFilterCount = 0;
389 _started = false;
390 _startTime = 0;
391
392 /** @type {null | (value?: any) => any} */
393 _resolveCurrent = null;
394
395 /**
396 * @param {typeof DEFAULT_CONFIG} [config]
397 */
398 constructor(config) {
399 // Main test methods
400 this.describe = this._addConfigurators(this.addSuite, () => this.suiteStack.at(-1));
401 this.fixture = makeFixtureManager(this);
402 this.test = this._addConfigurators(this.addTest, false);
403
404 this.initialConfig = { ...DEFAULT_CONFIG, ...config };
405 // Headless cannot be configured while running since it retains much less
406 // information/state that cannot be retrieved after construction.
407 this.headless = this.initialConfig.headless;
408 if (this.headless) {
409 this.config = { ...this.initialConfig };
410 } else {
411 this.presets = reactive(this.presets);
412 this.state = reactive(this.state);
413 this.config = reactive({ ...this.initialConfig }, () => {
414 setParams(
415 $fromEntries(
416 $entries(this.config).map(([key, value]) => [
417 key,
418 deepEqual(value, DEFAULT_CONFIG[key]) ? null : value,
419 ])
420 )
421 );
422 });
423
424 [this._pushTest, this._pushPendingTest] = batch((test) => this.state.done.add(test));
425 }
426
427 [this.expect, this.expectHooks] = makeExpect({ headless: this.headless });
428
429 for (const key in this.config) {
430 this.config[key];
431 }
432
433 // Debug
434 this.debug = Boolean(this.config.debugTest);
435
436 // Text filter
437 if (this.config.filter) {
438 for (const queryPart of parseQuery(this.config.filter)) {
439 if (queryPart.exclude) {
440 this.queryExclude.push(queryPart);
441 } else {
442 this.queryInclude.push(queryPart);
443 }
444 }
445 this._filterCount += this.queryInclude.length;
446 this._includeFilterCount += this.queryInclude.length;
447 }
448
449 // Jobs (suites or tests)
450 if (this.config.id?.length) {
451 this._include(this.state.includeSpecs.id, this.config.id, INCLUDE_LEVEL.url);
452 }
453
454 // Tags
455 if (this.config.tag?.length) {
456 this._include(this.state.includeSpecs.tag, this.config.tag, INCLUDE_LEVEL.url);
457 }
458
459 if (this.config.networkDelay) {
460 const values = this.config.networkDelay.split("-").map((val) => $parseFloat(val) || 0);
461 throttleNetwork(...values);
462 }
463
464 // Random seed
465 if (this.config.random) {
466 internalRandom.seed = this.config.random;
467 }
468
469 on(window, "error", this._handleError.bind(this));
470 on(window, "unhandledrejection", this._handleError.bind(this));
471 }
472
473 /**
474 * @param {JobConfig} config
475 * @param {string | Iterable<string>} name
476 * @param {(() => void) | string} fn
477 */
478 addSuite(config, name, fn) {
479 if (!name) {
480 throw new HootError(`a suite name must not be empty, got ${name}`, {
481 level: "critical",
482 });
483 }
484 const names = ensureArray(name).flatMap((n) => normalize(n).split("/").filter(Boolean));
485 const [suiteName, ...otherNames] = names;
486 if (names.length > 1) {
487 let targetSuite;
488 this.addSuite([], suiteName, () => {
489 targetSuite = this.addSuite(config, otherNames, fn);
490 });
491 return targetSuite;
492 }
493 const parentSuite = this.suiteStack.at(-1);
494 if (typeof fn !== "function") {
495 throw suiteError(
496 { name: suiteName, parent: parentSuite },
497 `expected second argument to be a function and got ${String(fn)}`
498 );
499 }
500 if (this.state.status === "running") {
501 throw suiteError(
502 { name: suiteName, parent: parentSuite },
503 `cannot add a suite after the test runner started`
504 );
505 }
506 let suite = markRaw(new Suite(parentSuite, suiteName, config));
507 const originalSuite = this.suites.get(suite.id);
508 if (originalSuite) {
509 suite = originalSuite;
510 } else {
511 this.suites.set(suite.id, suite);
512 if (parentSuite) {
513 parentSuite.addJob(suite);
514 suite.reporting = createReporting(parentSuite.reporting);
515 } else {
516 this.rootSuites.push(suite);
517 suite.reporting = createReporting(this.reporting);
518 }
519 }
520 this.suiteStack.push(suite);
521
522 this._applyTagModifiers(suite);
523 if (suite.config.skip && this.headless) {
524 // Do not register skipped jobs in headless
525 return this._erase(suite, true);
526 }
527
528 let error, result;
529 if (!this._prepared || suite.currentJobs.length) {
530 try {
531 result = fn();
532 } catch (err) {
533 if (err instanceof HootError) {
534 throw err;
535 } else {
536 error = err;
537 }
538 }
539 }
540 this.suiteStack.pop();
541 if (error) {
542 throw suiteError(suite, error);
543 } else if (result !== undefined) {
544 throw suiteError(suite, `the suite function cannot return a value`);
545 }
546
547 return suite;
548 }
549
550 /**
551 * @param {JobConfig} config
552 * @param {string} name
553 * @param {() => void | PromiseLike<void>} fn
554 */
555 addTest(config, name, fn) {
556 if (!name) {
557 throw new HootError(`a test name must not be empty, got ${name}`, {
558 level: "critical",
559 });
560 }
561 const parentSuite = this.suiteStack.at(-1);
562 if (!parentSuite) {
563 throw testError({ name, parent: null }, `cannot register a test outside of a suite.`);
564 }
565 if (typeof fn !== "function") {
566 throw testError(
567 { name, parent: parentSuite },
568 `expected second argument to be a function and got ${String(fn)}`
569 );
570 }
571 if (this.state.status === "running") {
572 throw testError(
573 { name, parent: parentSuite },
574 `cannot add a test after the test runner started.`
575 );
576 }
577 const runFn = this.dry ? null : fn;
578 let test = markRaw(new Test(parentSuite, name, config));
579 const originalTest = this.tests.get(test.id);
580 if (originalTest && !originalTest.isMinimized) {
581 if (this.dry || originalTest.run) {
582 throw testError(
583 test,
584 `a test with that name already exists in the suite ${stringify(
585 parentSuite.name
586 )}`
587 );
588 }
589 test = originalTest;
590 } else {
591 if (!this.dry && this._prepared) {
592 return null;
593 }
594 parentSuite.addJob(test);
595 this.tests.set(test.id, test);
596 }
597
598 test.setRunFn(runFn);
599
600 this._applyTagModifiers(test);
601 if (test.config.skip && this.headless) {
602 // Do not register skipped jobs in headless
603 return this._erase(test, true);
604 }
605
606 return test;
607 }
608
609 /**
610 * Registers a callback that will be executed at the end of the current test
611 * entity:
612 *
613 * - inside of a test: executed at the end of the *current* test, after all
614 * assertions have been completed;
615 *
616 * - inside of a suite: executed at the end of the *current* suite, after all
617 * tests have been run. Note that neither "after" nor "before" callbacks will
618 * be called if the suite is empty (= no tests to run);
619 *
620 * - outside of a suite: executed at the end of *every* suite
621 *
622 * @param {...Callback<Job>} callbacks
623 */
624 after(...callbacks) {
625 const { suite, test } = this.getCurrent();
626 if (test) {
627 for (const callback of callbacks) {
628 suite.callbacks.add("after-test", callback, true);
629 }
630 } else {
631 const callbackRegistry = suite ? suite.callbacks : this._callbacks;
632 for (const callback of callbacks) {
633 callbackRegistry.add("after-suite", callback);
634 }
635 }
636 }
637
638 /**
639 * @param {...Callback<never>} callbacks
640 */
641 afterAll(...callbacks) {
642 for (const callback of callbacks) {
643 this._callbacks.add("after-all", callback);
644 }
645 }
646
647 /**
648 * Registers a callback that will be executed at the end of each test in the
649 * current test entity:
650 *
651 * - inside of a suite: executed for all tests in the *current* suite;
652 *
653 * - outside of a suite: executed for every single test accross *all* suites.
654 *
655 * @param {...Callback<Test>} callbacks
656 */
657 afterEach(...callbacks) {
658 const { suite, test } = this.getCurrent();
659 if (test) {
660 throw testError(test, `cannot call hook "afterEach" inside of a test`);
661 }
662 const callbackRegistry = suite ? suite.callbacks : this._callbacks;
663 for (const callback of callbacks) {
664 callbackRegistry.add("after-test", callback);
665 }
666 }
667
668 /**
669 * @param {...Callback<Test>} callbacks
670 */
671 afterPostTest(...callbacks) {
672 for (const callback of callbacks) {
673 this._callbacks.add("after-post-test", callback);
674 }
675 }
676
677 /**
678 * Registers a callback that will be executed at the start of the current test
679 * entity:
680 *
681 * - inside of a test: executed at the start of the *current* test, before any
682 * assertion have been completed;
683 *
684 * - inside of a suite: executed at the start of the *current* suite, before any
685 * test is run. Note that neither "before" nor "before" callbacks will be called
686 * if the suite is empty (= no tests to run);
687 *
688 * - outside of a suite: executed at the start of *every* suite
689 *
690 * @param {...Callback<Job>} callbacks
691 */
692 before(...callbacks) {
693 const { suite, test } = this.getCurrent();
694 if (test) {
695 for (const callback of callbacks) {
696 suite.callbacks.add("after-test", callback(test), true);
697 }
698 } else {
699 const callbackRegistry = suite ? suite.callbacks : this._callbacks;
700 for (const callback of callbacks) {
701 callbackRegistry.add("before-suite", callback);
702 }
703 }
704 }
705
706 /**
707 * @param {...Callback<never>} callbacks
708 */
709 beforeAll(...callbacks) {
710 for (const callback of callbacks) {
711 this._callbacks.add("before-all", callback);
712 }
713 }
714
715 /**
716 * Registers a callback that will be executed at the start of each test in the
717 * current test entity:
718 *
719 * - inside of a suite: executed for all tests in the *current* suite;
720 *
721 * - outside of a suite: executed for every single test accross *all* suites.
722 *
723 * @param {...Callback<Test>} callbacks
724 */
725 beforeEach(...callbacks) {
726 const { suite, test } = this.getCurrent();
727 if (test) {
728 throw testError(test, `cannot call hook "beforeEach" inside of a test`);
729 }
730 const callbackRegistry = suite ? suite.callbacks : this._callbacks;
731 for (const callback of callbacks) {
732 callbackRegistry.add("before-test", callback);
733 }
734 }
735
736 checkPresetForViewPort() {
737 const presetId = this.config.preset;
738 const preset = this.presets[presetId];
739 if (!preset.size) {
740 return true;
741 }
742 const innerWidth = getViewPortWidth();
743 const innerHeight = getViewPortHeight();
744 const [width, height] = preset.size;
745 if (width === innerWidth && height === innerHeight) {
746 lastPresetWarn = null;
747 delete this.state.globalWarnings[WARNINGS.viewport];
748 } else {
749 if (lastPresetWarn !== presetId) {
750 this._handleGlobalWarning(WARNINGS.viewport);
751 logger.global.warn(
752 WARNINGS.viewport,
753 `\n> expected:`,
754 width,
755 "x",
756 height,
757 `\n> current:`,
758 innerWidth,
759 "x",
760 innerHeight,
761 `\n\nHint: you can use the "device toolbar" in your devtools to manually set the size of your viewport`
762 );
763 }
764 lastPresetWarn = presetId;
765 return false;
766 }
767 return true;
768 }
769
770 /**
771 * @param {string} key
772 * @param {Preset} preset
773 */
774 definePreset(key, preset) {
775 this.presets[key] = preset;
776 }
777
778 /**
779 * @param {() => Promise<void>} callback
780 */
781 async dryRun(callback) {
782 if (this.state.status !== "ready") {
783 throw new HootError("cannot run a dry run after the test runner started", {
784 level: "global",
785 });
786 }
787 if (this._prepared) {
788 throw new HootError("cannot run a dry run: runner has already been prepared", {
789 level: "global",
790 });
791 }
792
793 this.dry = true;
794
795 await callback();
796
797 const result = this._prepareRunner();
798
799 this.dry = false;
800
801 return result;
802 }
803
804 /**
805 * @template {(...args: any[]) => any} T
806 * @param {T} fn
807 * @returns {T}
808 */
809 exportFn(fn) {
810 return fn.bind(this);
811 }
812
813 /**
814 * @returns {{
815 * suite: Suite | null;
816 * test: Test | null;
817 * }}
818 */
819 getCurrent() {
820 return {
821 suite: this.suiteStack.at(-1) || null,
822 test: this.state.currentTest,
823 };
824 }
825
826 /**
827 * @param {SearchFilter} type
828 * @param {string} id
829 * @param {number} value
830 */
831 include(type, id, value) {
832 this._include(this.state.includeSpecs[type], [id], value);
833 this._updateConfigFromSpecs();
834 }
835
836 manualStart() {
837 this._canStartDef ||= Promise.withResolvers();
838 this._canStartDef.resolve(true);
839 }
840
841 /**
842 * Registers callbacks that will be executed when an error occurs during the
843 * execution of the test runner.
844 *
845 * If called within a test, the given callbacks will only be called once.
846 *
847 * @param {...Callback<ErrorEvent | PromiseRejectionEvent>} callbacks
848 */
849 onError(...callbacks) {
850 const { suite, test } = this.getCurrent();
851 const callbackRegistry = suite ? suite.callbacks : this._callbacks;
852 for (const callback of callbacks) {
853 callbackRegistry.add("error", callback, Boolean(test));
854 }
855 }
856
857 /**
858 * @param {Partial<Record<SearchFilter, Iterable<string>>>} specs
859 */
860 simplifyUrlIds(specs) {
861 if (!specs) {
862 return {};
863 }
864 const ids = {};
865 let items = 0;
866 if (specs.id) {
867 for (const id of ensureArray(specs.id)) {
868 items++;
869 ids[id] = INCLUDE_LEVEL.url;
870 }
871 }
872 if (items > 1) {
873 this._simplifyIncludeSpecs(ids);
874 }
875 return {
876 ...specs,
877 id: $keys(ids),
878 };
879 }
880
881 /**
882 * Boot function starting all registered tests and suites.
883 *
884 * The returned promise is resolved after all tests (and teardowns) have been
885 * executed. Its value is an object containing the list of tests and suites
886 * that have been run.
887 *
888 * An optional "dry" option can be passed to the function to only prepare the
889 * list of tests and suites that will be run, without actually running them.
890 * It will then reset all tests' run functions to allow them to be registered
891 * again with the actual run functions.
892 *
893 * @param {...Job} jobs
894 */
895 async start(...jobs) {
896 jobs = jobs.filter(Boolean);
897 if (!this._started) {
898 this._started = true;
899 this._prepareRunner();
900 await this._setupStart();
901 } else if (!jobs.length) {
902 throw new HootError("cannot start test runner: runner has already started", {
903 level: "global",
904 });
905 }
906
907 if (this.state.status === "done") {
908 return false;
909 }
910
911 if (jobs.length) {
912 this._currentJobs = filterReady(jobs);
913 }
914
915 if (this._canStartDef) {
916 await this._canStartDef.promise;
917 }
918
919 this.state.status = "running";
920
921 /** @type {Runner["_handleError"]} */
922 const handleError = this._handleError.bind(this);
923
924 let job = this._nextJob(jobs);
925 while (job && this.state.status === "running") {
926 const callbackChain = this._getCallbackChain(job);
927 if (job instanceof Suite) {
928 // Case: suite
929 // -----------
930
931 /** @type {Suite} */
932 const suite = job;
933 if (!suite.config.skip && suite.currentJobs.length) {
934 if (suite.currentJobIndex <= 0) {
935 // before suite code
936 this.suiteStack.push(suite);
937
938 suite.before();
939 await this._callbacks.call("before-suite", suite, handleError);
940 await suite.callbacks.call("before-suite", suite, handleError);
941 }
942 if (suite.currentJobIndex >= suite.currentJobs.length) {
943 // after suite code
944 this.suiteStack.pop();
945
946 await this._execAfterCallback(async () => {
947 await suite.callbacks.call("after-suite", suite, handleError);
948 await this._callbacks.call("after-suite", suite, handleError);
949 });
950 suite.after();
951
952 logger.logSuite(suite);
953
954 suite.runCount++;
955 if (suite.willRunAgain()) {
956 suite.reset();
957 continue;
958 } else if (this.headless) {
959 this._erase(suite);
960 } else {
961 suite.cleanup();
962 }
963 }
964 } else if (this.headless) {
965 this._erase(suite);
966 } else {
967 suite.minimize();
968 }
969 job = this._nextJob(jobs, job);
970 continue;
971 }
972
973 // Case: test
974 // ----------
975
976 /** @type {Test} */
977 const test = job;
978 if (test.config.skip) {
979 // Skipped test
980 this._pushTest(test);
981 test.setRunFn(null);
982 test.parent.reporting.add({ skipped: +1, tests: +1 });
983 job = this._nextJob(jobs, job);
984 continue;
985 }
986
987 // Suppress console errors and warnings if test is in "todo" mode
988 // (and not in debug).
989 const restoreConsole = handleConsoleIssues(test, !this.debug);
990
991 // Before test
992 this.state.currentTest = test;
993 this.expectHooks.before(test);
994 test.before();
995 for (const callbackRegistry of [...callbackChain].reverse()) {
996 await callbackRegistry.call("before-test", test, handleError);
997 }
998
999 let timeoutId = 0;
1000
1001 // ! The following assignment should stay in the `start` function to
1002 // ! keep the smallest stack trace possible:
1003 // ! Runner.start() > Test.run() > Error
1004 const testPromise = Promise.resolve(test.run());
1005 const timeout = $floor(test.config.timeout || this.config.timeout);
1006 const timeoutPromise = new Promise((resolve, reject) => {
1007 // Set abort signal
1008 this._resolveCurrent = resolve;
1009
1010 if (timeout && !this.debug) {
1011 // Set timeout
1012 timeoutId = setTimeout(() => {
1013 const msg = `test ${stringify(
1014 test.name
1015 )} timed out after ${timeout} milliseconds`;
1016 reject(new HootError(msg, { level: "global" }));
1017 }, timeout);
1018 }
1019 }).then(() => {
1020 this.aborted = true;
1021 this.debug = false; // Remove debug mode to let the runner stop
1022 });
1023
1024 // Run test
1025 await Promise.race([testPromise, timeoutPromise])
1026 .catch((error) => {
1027 if (handleError) {
1028 return handleError(error);
1029 } else {
1030 throw error;
1031 }
1032 })
1033 .finally(() => {
1034 this._resolveCurrent = null;
1035
1036 if (timeoutId) {
1037 clearTimeout(timeoutId);
1038 }
1039 });
1040
1041 // After test
1042 const { lastResults } = test;
1043 await this._execAfterCallback(async () => {
1044 for (const callbackRegistry of callbackChain) {
1045 await callbackRegistry.call("after-test", test, handleError);
1046 }
1047 });
1048 test.after();
1049
1050 restoreConsole();
1051
1052 // Log test errors and increment counters
1053 this.expectHooks.after(this);
1054 if (lastResults.pass) {
1055 logger.logTest(test);
1056
1057 if (this.state.failedIds.has(test.id)) {
1058 this.state.failedIds.delete(test.id);
1059 storageSet(STORAGE.failed, [...this.state.failedIds]);
1060 }
1061 } else {
1062 this._failed++;
1063
1064 const failReasons = [];
1065 const failedAssertions = lastResults.events.filter(
1066 (event) => event.type & CASE_EVENT_TYPES.assertion.value && !event.pass
1067 );
1068 if (failedAssertions.length) {
1069 const s = failedAssertions.length === 1 ? "" : "s";
1070 failReasons.push(
1071 `\nFailed assertion${s}:`,
1072 ...formatAssertions(failedAssertions)
1073 );
1074 }
1075 if (lastResults.currentErrors.length) {
1076 const s = lastResults.currentErrors.length === 1 ? "" : "s";
1077 failReasons.push(
1078 `\nError${s} during test:`,
1079 ...lastResults.currentErrors.map((error) => `\n${error.message}`)
1080 );
1081 }
1082 logger.global.error(
1083 [`Test ${stringify(test.fullName)} failed:`, ...failReasons].join("\n")
1084 );
1085
1086 if (!this.aborted) {
1087 if (this._failed === 1) {
1088 // On first failed test: reset the "failed IDs" list
1089 this.state.failedIds.clear();
1090 }
1091 this.state.failedIds.add(test.id);
1092 storageSet(STORAGE.failed, [...this.state.failedIds]);
1093 }
1094 }
1095
1096 await this._callbacks.call("after-post-test", test, handleError);
1097
1098 this._pushTest(test);
1099 this.totalTime = formatTime($now() - this._startTime);
1100 test.runCount++;
1101
1102 if (this.debug) {
1103 return new Promise(() => {});
1104 }
1105 if (this.config.bail && this._failed >= this.config.bail) {
1106 return this.stop();
1107 }
1108
1109 if (test.willRunAgain()) {
1110 test.reset();
1111 } else if (this.headless) {
1112 this._erase(test);
1113 } else {
1114 test.cleanup();
1115 }
1116 if (test.runCount < (test.config.multi || 0)) {
1117 continue;
1118 }
1119
1120 job = this._nextJob(jobs, job);
1121 }
1122
1123 if (this.state.status === "done") {
1124 return false;
1125 }
1126
1127 this._pushPendingTest();
1128
1129 if (!this.debug) {
1130 if (jobs.length) {
1131 this.state.status = "ready";
1132 } else {
1133 await this.stop();
1134 }
1135 }
1136
1137 return true;
1138 }
1139
1140 async stop() {
1141 this._currentJobs = [];
1142 this.state.status = "done";
1143
1144 if (this._resolveCurrent) {
1145 this._resolveCurrent();
1146
1147 // `stop` will be called again after test has been resolved.
1148 return false;
1149 }
1150
1151 while (this._missedCallbacks.length) {
1152 await this._missedCallbacks.shift()();
1153 }
1154
1155 await this._callbacks.call("after-all", this, logger.error);
1156
1157 if (this.headless) {
1158 // Log root suite results in headless
1159 const restoreLogLevel = logger.setLogLevel("suites");
1160 for (const suite of this.suites.values()) {
1161 if (!suite.parent) {
1162 logger.logSuite(suite);
1163 }
1164 }
1165 restoreLogLevel();
1166 }
1167
1168 const { passed, failed, assertions } = this.reporting;
1169 if (failed > 0) {
1170 const errorMessage = ["Some tests failed: see above for details"];
1171 if (this.headless) {
1172 const ids = this.simplifyUrlIds({ id: this.state.failedIds });
1173 const link = createUrlFromId(ids, { debug: true });
1174 // Tweak parameters to make debugging easier
1175 link.searchParams.set("debug", "assets");
1176 link.searchParams.delete("headless");
1177 link.searchParams.delete("loglevel");
1178 link.searchParams.delete("timeout");
1179 errorMessage.push(`Failed tests link: ${link.toString()}`);
1180 }
1181 // Use console.dir for this log to appear on runbot sub-builds page
1182 logger.logGlobal(
1183 `Failed ${failed} tests (${passed} passed, total time: ${this.totalTime})`
1184 );
1185 // Do not use logger to not apply the [HOOT] prefix and allow the CI
1186 // to stop the test run browser.
1187 $error(errorMessage.join("\n"));
1188 } else {
1189 // Use console.dir for this log to appear on runbot sub-builds page
1190 logger.logGlobal(
1191 `Passed ${passed} tests (${assertions} assertions, total time: ${this.totalTime})`
1192 );
1193 // This statement acts as a success code for the server to know when
1194 // all suites have passed.
1195 logger.logRun("Test suite succeeded");
1196 }
1197
1198 logger.setIssueLevel("critical"); // Goes back to critical mode after a test run
1199
1200 return false;
1201 }
1202
1203 /**
1204 * Enriches the given function with test modifiers, which are:
1205 * - `debug`: only run in debug mode
1206 * - `only`: only run this test/suite
1207 * - `skip`: skip this test/suite
1208 * - `todo`: mark this test/suite as todo
1209 * - `tags`: add tags to this test/suite
1210 *
1211 * @template {(...args: any[]) => any} T
1212 * @template {false | () => Job} C
1213 * @param {T} fn
1214 * @param {C} getCurrent
1215 * @returns {typeof configurableFn}
1216 */
1217 _addConfigurators(fn, getCurrent) {
1218 /**
1219 * @typedef {((...args: DropFirst<Parameters<T>>) => Configurators) & Configurators} ConfigurableFunction
1220 *
1221 * @typedef {{
1222 * readonly debug: ConfigurableFunction;
1223 * readonly only: ConfigurableFunction;
1224 * readonly skip: ConfigurableFunction;
1225 * readonly todo: ConfigurableFunction;
1226 * readonly config: (...configs: JobConfig[]) => Configurators;
1227 * readonly current: C extends false ? never : Configurators;
1228 * readonly multi: (count: number) => Configurators;
1229 * readonly tags: (...tagNames: string[]) => Configurators;
1230 * readonly timeout: (ms: number) => Configurators;
1231 * }} Configurators
1232 */
1233
1234 // GETTER MODIFIERS
1235
1236 /** @type {Configurators["current"]} */
1237 const current = getCurrent && (() => this._createCurrentConfigurators(getCurrent));
1238
1239 /** @type {Configurators["debug"]} */
1240 function debug() {
1241 tags("debug");
1242 return configurableFn;
1243 }
1244
1245 /** @type {Configurators["only"]} */
1246 function only() {
1247 tags("only");
1248 return configurableFn;
1249 }
1250
1251 /** @type {Configurators["skip"]} */
1252 function skip() {
1253 tags("skip");
1254 return configurableFn;
1255 }
1256
1257 /** @type {Configurators["todo"]} */
1258 function todo() {
1259 tags("todo");
1260 return configurableFn;
1261 }
1262
1263 // FUNCTION MODIFIERS
1264
1265 /**
1266 * Modifies the current test/suite configuration.
1267 *
1268 * - `timeout`: sets the timeout for the current test/suite;
1269 * - `multi`: sets the number of times the current test/suite will be run.
1270 *
1271 * @type {Configurators["config"]}
1272 * @example
1273 * // Will timeout each of its tests after 10 seconds
1274 * describe.config({ timeout: 10_000 });
1275 * describe("Expensive tests", () => { ... });
1276 * @example
1277 * // Will be run 100 times
1278 * test.config({ multi: 100 });
1279 * test("non-deterministic test", async () => { ... });
1280 */
1281 function config(...configs) {
1282 $assign(currentConfig, ...configs);
1283 return configurators;
1284 }
1285
1286 /** @type {Configurators["multi"]} */
1287 function multi(count) {
1288 currentConfig.multi = count;
1289 return configurators;
1290 }
1291
1292 /**
1293 * Adds tags to the current test/suite.
1294 *
1295 * Tags can be a string, a list of strings, or a spread of strings.
1296 *
1297 * @type {Configurators["tags"]}
1298 * @example
1299 * // Will be tagged with "desktop" and "ui"
1300 * test.tags("desktop", "ui");
1301 * test("my test", () => { ... });
1302 * @example
1303 * test.tags("mobile");
1304 * test("my mobile test", () => { ... });
1305 */
1306 function tags(...tagNames) {
1307 currentConfig.tags.push(...getTags(tagNames));
1308 return configurators;
1309 }
1310
1311 /** @type {Configurators["timeout"]} */
1312 function timeout(ms) {
1313 currentConfig.timeout = ms;
1314 return configurators;
1315 }
1316
1317 /** @type {ConfigurableFunction} */
1318 function configurableFn(...args) {
1319 const jobConfig = { ...currentConfig };
1320 currentConfig = { tags: [] };
1321 return boundFn(jobConfig, ...args);
1322 }
1323
1324 const boundFn = fn.bind(this);
1325
1326 const configuratorGetters = { debug, only, skip, todo };
1327 const configuratorMethods = { config, multi, tags, timeout };
1328 if (current) {
1329 configuratorGetters.current = current;
1330 }
1331 /** @type {Configurators} */
1332 const configurators = { ...configuratorGetters, ...configuratorMethods };
1333
1334 for (const [key, getter] of $entries(configuratorGetters)) {
1335 $defineProperty(configurableFn, key, { get: getter });
1336 }
1337 for (const [key, getter] of $entries(configuratorMethods)) {
1338 $defineProperty(configurableFn, key, { value: getter });
1339 }
1340
1341 /** @type {{ tags: Tag[], [key: string]: any }} */
1342 let currentConfig = { tags: [] };
1343 return configurableFn;
1344 }
1345
1346 /**
1347 * @param {Job} job
1348 */
1349 _applyTagModifiers(job) {
1350 let shouldSkip = false;
1351 let [ignoreSkip] = this._getExplicitIncludeStatus(job);
1352 for (const tag of job.tags) {
1353 this.tags.set(tag.id, tag);
1354 switch (tag.name) {
1355 case Tag.DEBUG:
1356 if (typeof this.debug !== "boolean" && this.debug !== job) {
1357 throw new HootError(
1358 `cannot set multiple tests or suites as "debug" at the same time`,
1359 { level: "critical" }
1360 );
1361 }
1362 this.debug = job;
1363 // Falls through
1364 case Tag.ONLY:
1365 if (!this.dry) {
1366 logger.global.warn(
1367 `${stringify(job.fullName)} is marked as ${stringify(
1368 tag.name
1369 )}. This is not suitable for CI`
1370 );
1371 }
1372 this._include(this.state.includeSpecs.id, [job.id], INCLUDE_LEVEL.tag);
1373 ignoreSkip = true;
1374 break;
1375 case Tag.SKIP:
1376 shouldSkip = true;
1377 break;
1378 case Tag.TODO:
1379 job.config.todo = true;
1380 break;
1381 }
1382 }
1383
1384 if (shouldSkip) {
1385 if (ignoreSkip) {
1386 logger.global.warn(
1387 `${stringify(
1388 job.fullName
1389 )} is marked as skipped but explicitly included: "skip" modifier has been ignored`
1390 );
1391 } else {
1392 job.config.skip = true;
1393 }
1394 }
1395 }
1396
1397 /**
1398 * @param {() => Job} getCurrent
1399 */
1400 _createCurrentConfigurators(getCurrent) {
1401 /**
1402 * @param {JobConfig} config
1403 */
1404 function configureCurrent(config) {
1405 getCurrent().configure(config);
1406
1407 return currentConfigurators;
1408 }
1409
1410 /**
1411 * @param {...string} tagNames
1412 */
1413 const addTagsToCurrent = (...tagNames) => {
1414 const current = getCurrent();
1415 current.configure({ tags: getTags(tagNames) });
1416 this._applyTagModifiers(current);
1417
1418 return currentConfigurators;
1419 };
1420
1421 /** @type {CurrentConfigurators} */
1422 const currentConfigurators = $freeze({
1423 config: configureCurrent,
1424 debug: () => addTagsToCurrent("debug"),
1425 multi: (count) => configureCurrent({ multi: count }),
1426 only: () => addTagsToCurrent("only"),
1427 skip: () => addTagsToCurrent("skip"),
1428 tags: addTagsToCurrent,
1429 timeout: (ms) => configureCurrent({ timeout: ms }),
1430 todo: () => addTagsToCurrent("todo"),
1431 });
1432
1433 return currentConfigurators;
1434 }
1435
1436 /**
1437 * @param {Job} job
1438 * @param {boolean} [canEraseParent]
1439 */
1440 _erase(job, canEraseParent = false) {
1441 if (job instanceof Suite) {
1442 if (!job.reporting.failed) {
1443 this.suites.delete(job.id);
1444 }
1445 } else {
1446 if (job.results.every((result) => result.pass)) {
1447 this.tests.delete(job.id);
1448 }
1449 }
1450 job.minimize();
1451 if (canEraseParent && job.parent) {
1452 const jobIndex = job.parent.jobs.indexOf(job);
1453 if (jobIndex >= 0) {
1454 job.parent.jobs.splice(jobIndex, 1);
1455 }
1456 if (!job.parent.jobs.length) {
1457 this._erase(job.parent);
1458 }
1459 }
1460 return job;
1461 }
1462
1463 /**
1464 * Executes a given callback when not in debug mode.
1465 * @param {() => Promise<void>} callback
1466 */
1467 async _execAfterCallback(callback) {
1468 if (this.debug) {
1469 this._missedCallbacks.push(callback);
1470 } else {
1471 await callback();
1472 }
1473 }
1474
1475 /**
1476 * @param {Job} job
1477 * @returns {Callbacks[]}
1478 */
1479 _getCallbackChain(job) {
1480 const chain = [];
1481 while (job) {
1482 if (job instanceof Suite) {
1483 chain.push(job.callbacks);
1484 }
1485 job = job.parent;
1486 }
1487 chain.push(this._callbacks);
1488 return chain;
1489 }
1490
1491 /**
1492 * @param {Job} job
1493 */
1494 _getExplicitIncludeStatus(job) {
1495 const explicitInclude = this.state.includeSpecs.id[job.id] || 0;
1496 return [explicitInclude > 0, explicitInclude < 0];
1497 }
1498
1499 /**
1500 * @param {Record<string, number>} values
1501 * @param {Iterable<string>} ids
1502 * @param {number} includeLevel
1503 * @param {boolean} [noIncrement]
1504 */
1505 _include(values, ids, includeLevel, noIncrement = false) {
1506 const isRemovable = $abs(includeLevel) === INCLUDE_LEVEL.url;
1507 const shouldInclude = !!includeLevel;
1508 let applied = 0;
1509 for (const id of ids) {
1510 let idLevel = includeLevel;
1511 let nId = normalize(id.toLowerCase());
1512 if (nId.startsWith(EXCLUDE_PREFIX)) {
1513 nId = nId.slice(EXCLUDE_PREFIX.length);
1514 if (idLevel > 0) {
1515 idLevel *= -1;
1516 }
1517 }
1518 const previousValue = values[nId] || 0;
1519 const wasRemovable = $abs(previousValue) === INCLUDE_LEVEL.url;
1520 if (wasRemovable) {
1521 applied++;
1522 }
1523 if (shouldInclude) {
1524 if (previousValue === idLevel) {
1525 continue;
1526 }
1527 values[nId] = idLevel;
1528 if (noIncrement) {
1529 continue;
1530 }
1531 if (previousValue <= 0 && idLevel > 0) {
1532 this._includeFilterCount++;
1533 } else if (previousValue > 0 && idLevel <= 0) {
1534 this._includeFilterCount--;
1535 }
1536 if (!wasRemovable && isRemovable) {
1537 this._removableFilterCount++;
1538 } else if (wasRemovable && !isRemovable) {
1539 this._removableFilterCount--;
1540 }
1541 } else {
1542 delete values[nId];
1543 if (noIncrement) {
1544 continue;
1545 }
1546 if (previousValue > 0) {
1547 this._includeFilterCount--;
1548 }
1549 if (wasRemovable) {
1550 this._removableFilterCount--;
1551 }
1552 }
1553 }
1554 return applied;
1555 }
1556
1557 /**
1558 * @param {Job} job
1559 * @returns {boolean | null}
1560 */
1561 _isImplicitlyExcluded(job) {
1562 // By tag name
1563 for (const [tagName, status] of $entries(this.state.includeSpecs.tag)) {
1564 if (status < 0 && job.tags.some((tag) => tag.name === tagName)) {
1565 return true;
1566 }
1567 }
1568
1569 // By text filter
1570 if (this.queryExclude.length && this.queryExclude.some((qp) => qp.matchValue(job.key))) {
1571 return true;
1572 }
1573
1574 return false;
1575 }
1576
1577 /**
1578 * @param {Job} job
1579 * @returns {boolean | null}
1580 */
1581 _isImplicitlyIncluded(job) {
1582 // By tag name
1583 for (const [tagName, status] of $entries(this.state.includeSpecs.tag)) {
1584 if (status > 0 && job.tags.some((tag) => tag.name === tagName)) {
1585 return true;
1586 }
1587 }
1588
1589 // By text filter
1590 if (this.queryInclude.length && this.queryInclude.every((qp) => qp.matchValue(job.key))) {
1591 return true;
1592 }
1593
1594 return false;
1595 }
1596
1597 /**
1598 * @param {Job[]} jobs
1599 * @param {Job} [job]
1600 */
1601 _nextJob(jobs, job) {
1602 this.state.currentTest = null;
1603 if (job) {
1604 const sibling = job.currentJobs?.[job.currentJobIndex++];
1605 if (sibling) {
1606 return sibling;
1607 }
1608 const parent = job.parent;
1609 if (parent && (!jobs.length || jobs.some((j) => parent.path.includes(j)))) {
1610 return parent;
1611 }
1612 }
1613 const index = this._currentJobs.findIndex(Boolean);
1614 if (index >= 0) {
1615 return this._currentJobs.splice(index, 1)[0];
1616 }
1617 return null;
1618 }
1619
1620 /**
1621 * @param {Job[]} jobs
1622 * @param {boolean} [implicitInclude] fallback include value for sub-jobs
1623 * @returns {Job[]}
1624 */
1625 _prepareJobs(jobs, implicitInclude = !this._includeFilterCount) {
1626 if (typeof this.debug !== "boolean") {
1627 // Special case: test (or suite with 1 test) with "debug" tag
1628 let debugTest = this.debug;
1629 while (debugTest instanceof Suite) {
1630 if (debugTest.jobs.length > 1) {
1631 logger.global.warn(
1632 `debugging a suite with ${debugTest.jobs.length} jobs: only the first one will be run`
1633 );
1634 }
1635 debugTest = debugTest.jobs[0];
1636 }
1637
1638 if (this._populateState) {
1639 this.state.tests.push(debugTest);
1640 }
1641
1642 const jobs = debugTest.path;
1643 for (let i = 0; i < jobs.length - 1; i++) {
1644 const suite = jobs[i];
1645 suite.setCurrentJobs([jobs[i + 1]]);
1646 if (this._populateState) {
1647 this.state.suites.push(suite);
1648 }
1649 }
1650 return [jobs[0]];
1651 }
1652
1653 const filteredJobs = jobs.filter((job) => {
1654 // Priority 1: explicit include or exclude (URL or special tag)
1655 const [explicitInclude, explicitExclude] = this._getExplicitIncludeStatus(job);
1656 if (explicitExclude) {
1657 return false;
1658 }
1659
1660 // Priority 2: implicit exclude
1661 if (!explicitInclude && this._isImplicitlyExcluded(job)) {
1662 return false;
1663 }
1664
1665 // Priority 3: implicit include
1666 let included = explicitInclude || implicitInclude || this._isImplicitlyIncluded(job);
1667 if (job instanceof Suite) {
1668 // For suites: included if at least 1 included job
1669 job.setCurrentJobs(this._prepareJobs(job.jobs, included));
1670 included = Boolean(job.currentJobs.length);
1671
1672 if (included && this._populateState) {
1673 this.state.suites.push(job);
1674 }
1675 } else if (included && this._populateState) {
1676 this.state.tests.push(job);
1677 }
1678 return included;
1679 });
1680
1681 switch (this.config.order) {
1682 case "fifo": {
1683 return filteredJobs;
1684 }
1685 case "lifo": {
1686 return filteredJobs.reverse();
1687 }
1688 case "random": {
1689 return shuffle(filteredJobs);
1690 }
1691 }
1692 }
1693
1694 _prepareRunner() {
1695 if (this._prepared) {
1696 return {};
1697 }
1698 this._prepared = true;
1699
1700 if (this.config.preset) {
1701 const preset = this.presets[this.config.preset];
1702 if (!preset) {
1703 throw new HootError(`unknown preset: "${this.config.preset}"`, {
1704 level: "critical",
1705 });
1706 }
1707 if (preset.tags?.length) {
1708 this._include(this.state.includeSpecs.tag, preset.tags, INCLUDE_LEVEL.preset);
1709 }
1710 if (typeof preset.touch === "boolean") {
1711 this.beforeEach(() => mockTouch(preset.touch));
1712 }
1713 this.checkPresetForViewPort();
1714 }
1715
1716 // Cleanup invalid IDs and tags from URL
1717 const hasChanged = this._simplifyIncludeSpecs(this.state.includeSpecs.id);
1718 if (hasChanged) {
1719 this._updateConfigFromSpecs();
1720 }
1721
1722 // Cleanup invalid tests from storage
1723 const failedIds = [...this.state.failedIds];
1724 const existingFailed = failedIds.filter((id) => this.tests.has(id));
1725 if (existingFailed.length !== failedIds.length) {
1726 this.state.failedIds = new Set(existingFailed);
1727 storageSet(STORAGE.failed, existingFailed);
1728 }
1729
1730 // Check tags similarities
1731 const similarities = getTagSimilarities();
1732 if (similarities.length) {
1733 this._handleGlobalWarning(
1734 WARNINGS.tagNames + similarities.map((s) => `\n- ${s.map(stringify).join(" / ")}`)
1735 );
1736 logger.global.warn(WARNINGS.tagNames, similarities);
1737 }
1738
1739 this._populateState = true;
1740 this._currentJobs = this._prepareJobs(this.rootSuites);
1741 this._populateState = false;
1742
1743 if (!this.state.tests.length) {
1744 logger.logGlobal(`no tests to run`);
1745 }
1746
1747 // Reduce non-included suites & tests info to a miminum
1748 const includedSuites = new Set(this.state.suites);
1749 for (const suite of this.suites.values()) {
1750 if (!includedSuites.has(suite)) {
1751 if (this.headless) {
1752 this._erase(suite, true);
1753 } else {
1754 suite.minimize();
1755 }
1756 }
1757 }
1758 const includedTests = new Set(this.state.tests);
1759 for (const test of this.tests.values()) {
1760 if (!includedTests.has(test)) {
1761 if (this.headless) {
1762 this._erase(test, true);
1763 } else {
1764 test.minimize();
1765 }
1766 }
1767 }
1768
1769 if (this.headless) {
1770 this.rootSuites.length = 0;
1771 this.state.suites.length = 0;
1772 this.state.tests.length = 0;
1773 }
1774
1775 return {
1776 suites: [...includedSuites],
1777 tests: [...includedTests],
1778 };
1779 }
1780
1781 /**
1782 * @param {Error | ErrorEvent | PromiseRejectionEvent} ev
1783 */
1784 _handleError(ev) {
1785 if (this.config.notrycatch) {
1786 return;
1787 }
1788 const error = ensureError(ev);
1789 if (handledErrors.has(error)) {
1790 // Already handled
1791 return ev.preventDefault();
1792 }
1793 handledErrors.add(error);
1794
1795 if (!isInstanceOf(ev, Event)) {
1796 ev = new ErrorEvent("error", { error });
1797 }
1798
1799 mockPreventDefault(ev);
1800
1801 if (error.message.includes(RESIZE_OBSERVER_MESSAGE)) {
1802 // Stop event
1803 ev.stopImmediatePropagation();
1804 if (ev.bubbles) {
1805 ev.stopPropagation();
1806 }
1807 return ev.preventDefault();
1808 }
1809
1810 if (this.state.currentTest && !(error instanceof HootError)) {
1811 // Handle the error in the current test
1812 const handled = this._handleErrorInTest(ev, error);
1813 if (handled) {
1814 return ev.preventDefault();
1815 }
1816 } else {
1817 this._handleGlobalError(ev, error);
1818 }
1819
1820 // Prevent error event
1821 ev.preventDefault();
1822
1823 // Log error
1824 if (error.level) {
1825 const restoreLogger = logger.setIssueLevel(error.level);
1826 // Stringify global errors to avoid logging whole tracebacks on CI
1827 logger.error(error.level === "global" ? String(error) : error);
1828 restoreLogger();
1829 } else {
1830 logger.error(error);
1831 }
1832 }
1833
1834 /**
1835 * @param {ErrorEvent | PromiseRejectionEvent} ev
1836 * @param {Error} error
1837 */
1838 _handleErrorInTest(ev, error) {
1839 for (const callbackRegistry of this._getCallbackChain(this.state.currentTest)) {
1840 callbackRegistry.callSync("error", ev, logger.error);
1841 if (isPrevented(ev)) {
1842 // Prevented in tests
1843 return true;
1844 }
1845 }
1846
1847 return this.expectHooks.error(error);
1848 }
1849
1850 /**
1851 * @param {ErrorEvent | PromiseRejectionEvent} ev
1852 * @param {Error} error
1853 */
1854 _handleGlobalError(ev, error) {
1855 const { globalErrors } = this.state;
1856 const key = String(error);
1857 if (globalErrors[key]) {
1858 globalErrors[key].count++;
1859 } else {
1860 globalErrors[key] = {
1861 count: 1,
1862 message: error.message,
1863 name: error.constructor.name || error.name,
1864 };
1865 }
1866 return false;
1867 }
1868
1869 /**
1870 * @param {string} message
1871 */
1872 _handleGlobalWarning(message) {
1873 const { globalWarnings } = this.state;
1874 const key = message;
1875 if (globalWarnings[key]) {
1876 globalWarnings[key].count++;
1877 } else {
1878 globalWarnings[key] = {
1879 count: 1,
1880 message,
1881 name: this.config.fun ? "warming" : "warning",
1882 };
1883 }
1884 return false;
1885 }
1886
1887 async _setupStart() {
1888 this._startTime = $now();
1889 if (this.config.manual) {
1890 this._canStartDef ||= Promise.withResolvers();
1891 }
1892
1893 // Config log
1894 const table = { ...toRaw(this.config) };
1895 for (const key of FILTER_KEYS) {
1896 if (isIterable(table[key])) {
1897 table[key] = `[${[...table[key]].join(", ")}]`;
1898 }
1899 }
1900 logger.group("Configuration (click to expand)", () => {
1901 logger.table(table);
1902 });
1903 logger.logRun("Starting test suites");
1904 logger.setIssueLevel("trace");
1905
1906 // Adjust debug mode if more or less than 1 test will be run
1907 if (this.debug) {
1908 const activeSingleTests = this.state.tests.filter(
1909 (test) => !test.config.skip && !test.config.multi
1910 );
1911 if (activeSingleTests.length !== 1) {
1912 logger.global.warn(
1913 `Disabling debug mode: ${activeSingleTests.length} tests will be run`
1914 );
1915 this.config.debugTest = false;
1916 this.debug = false;
1917 } else {
1918 const nameSpace = exposeHelpers(
1919 _hootDom,
1920 _animation,
1921 _date,
1922 _math,
1923 _navigator,
1924 _network,
1925 _notification,
1926 _window,
1927 {
1928 __debug__: this,
1929 destroy,
1930 getFixture: this.fixture.get,
1931 }
1932 );
1933 logger.setLogLevel("debug");
1934 logger.logDebug(
1935 `Debug mode is active: Hoot helpers available from \`window.${nameSpace}\``
1936 );
1937 }
1938 }
1939
1940 // Register default hooks
1941 this.beforeAll(defineRootNode.bind(null, this.fixture.get));
1942 this.afterAll(
1943 // Warn user events
1944 !this.debug && on(window, "pointermove", warnUserEvent),
1945 !this.debug && on(window, "pointerdown", warnUserEvent),
1946 !this.debug && on(window, "keydown", warnUserEvent)
1947 );
1948 this.beforeEach(this.fixture.setup, setupWindow, setupTime);
1949 this.afterEach(
1950 this.fixture.cleanup,
1951 cleanupAnimations,
1952 cleanupWindow,
1953 cleanupNetwork,
1954 cleanupNavigator,
1955 cleanupEvents,
1956 cleanupDOM,
1957 cleanupDate,
1958 cleanupTime
1959 );
1960
1961 enableEventLogs(logger.canLog("debug"));
1962 setFrameRate(this.config.fps);
1963
1964 await this._callbacks.call("before-all", this, logger.error);
1965 }
1966
1967 /**
1968 * @param {Runner["state"]["includeSpecs"]["id"]} idSpecs
1969 */
1970 _simplifyIncludeSpecs(idSpecs) {
1971 let hasChanged = false;
1972 let remaining = $keys(idSpecs);
1973 while (remaining.length) {
1974 const id = remaining.shift();
1975 const value = idSpecs[id];
1976 if ($abs(value) !== INCLUDE_LEVEL.url) {
1977 continue;
1978 }
1979 const item = this.suites.get(id) || this.tests.get(id);
1980 if (!item) {
1981 const couldRemove = this._include(idSpecs, [id], 0);
1982 if (value > 0) {
1983 // Only log warning for not-found *included* jobs
1984 if (couldRemove) {
1985 logger.warn(
1986 `Test runner did not find job with ID "${id}": it has been removed from the URL`
1987 );
1988 } else {
1989 logger.warn(
1990 `Test runner did not find job with ID "${id}": it has been ignored from the current run`
1991 );
1992 }
1993 }
1994 hasChanged = true;
1995 }
1996 if (!item?.parent || item.parent.jobs.length < 1) {
1997 // No parent or no need to simplify
1998 continue;
1999 }
2000 const siblingIds = item.parent.jobs.map((job) => job.id);
2001 if (siblingIds.every((siblingId) => idSpecs[siblingId] === INCLUDE_LEVEL.url)) {
2002 remaining = remaining.filter((id) => !siblingIds.includes(id));
2003 this._include(idSpecs, [item.parent.id], INCLUDE_LEVEL.url, true);
2004 this._include(idSpecs, siblingIds, 0, true);
2005 hasChanged = true;
2006 }
2007 }
2008 return hasChanged;
2009 }
2010
2011 _updateConfigFromSpecs() {
2012 for (const type of FILTER_KEYS) {
2013 if (type === "filter") {
2014 continue;
2015 }
2016 this.config[type] = formatIncludes(this.state.includeSpecs[type]);
2017 }
2018 }
2019 }