|
| 1 | +--- |
| 2 | +layout: post |
| 3 | +title: "Early error reporting" |
| 4 | +author: krinkle |
| 5 | +excerpt: Early errors. |
| 6 | +tags: |
| 7 | +- feature |
| 8 | +--- |
| 9 | + |
| 10 | +## What is an "early" error? |
| 11 | + |
| 12 | +Early errors are errors when loading source code or test files, outside and before the first test. |
| 13 | + |
| 14 | +For example, a syntax error in a source file. Or an uncaught error while defining exports from your source files. Or an early error from a test file, such as if you misspell an import, or call an undefined function in top-level code outside your [`QUnit.test()`]({% link api/QUnit/test.md %}) cases. |
| 15 | + |
| 16 | +## Status quo |
| 17 | + |
| 18 | +In both QUnit 1.x and 2.x, "early" errors are reporter to the browser console, but not displayed in the UI of the HTML Reporter. |
| 19 | + |
| 20 | +Until now, the HTML Reporter initialized the UI during the [`QUnit.begin()`]({% link api/callbacks/QUnit.begin.md %}) event. This fires after your source and test files are loaded, before the first test begins. This approach is **simple** and **robust**. |
| 21 | + |
| 22 | +We generally recommend loading styles from the HTML head, and scripts from the end of the body: |
| 23 | + |
| 24 | +```html |
| 25 | +<!DOCTYPE html> |
| 26 | +<html> |
| 27 | +<head> |
| 28 | + <meta charset="utf-8"> |
| 29 | + <title>QUnit</title> |
| 30 | + <link rel="stylesheet" href="lib/qunit/qunit.css"> |
| 31 | +</head> |
| 32 | +<body> |
| 33 | + <div id="qunit"></div> |
| 34 | + |
| 35 | + <script src="lib/qunit/qunit.js"></script> |
| 36 | + <!-- <script src="src/my_project.js"></script> --> |
| 37 | + <!-- <script src="test/my_project.test.js"></script> --> |
| 38 | +</body> |
| 39 | +</html> |
| 40 | +``` |
| 41 | + |
| 42 | +But, QUnit works regardless of HTML order. Older projects often load scripts from the HTML `<head>`, before the `<div id="qunit">` element. Like so: |
| 43 | + |
| 44 | +```html |
| 45 | +<!DOCTYPE html> |
| 46 | +<html> |
| 47 | +<head> |
| 48 | + <meta charset="utf-8"> |
| 49 | + <title>QUnit</title> |
| 50 | + <link rel="stylesheet" href="lib/qunit/qunit.css"> |
| 51 | + <script src="lib/qunit/qunit.js"></script> |
| 52 | + <!-- <script src="src/my_project.js"></script> --> |
| 53 | + <!-- <script src="test/my_project.test.js"></script> --> |
| 54 | +</head> |
| 55 | +<body> |
| 56 | + <div id="qunit"></div> |
| 57 | +</body> |
| 58 | +</html> |
| 59 | +``` |
| 60 | + |
| 61 | +Initializing the UI from a `QUnit.begin()` event, is akin to waiting for the DOM-ready or `window.onload` event, and means we simply look for the `<div id="qunit">` element and either safely append the UI, or decide definitively that we're running headless with the UI [turned off]({% link api/reporters/html.md %}). |
| 62 | + |
| 63 | +However, this also meant that if we receive an early `error` event, the page remains blank. |
| 64 | + |
| 65 | + |
| 66 | +[`error` event]({% link api/callbacks/QUnit.on.md %}#the-error-event) |
| 67 | + |
| 68 | + |
| 69 | + |
| 70 | +## Instant rendering |
| 71 | + |
| 72 | + |
| 73 | + |
| 74 | +## See also |
| 75 | + |
| 76 | +* [QUnit 2.24.1 Released: Add memory to the "error" event]({% post_url 2025-01-25-qunit-2-24-1 %}) |
| 77 | +* [Add support for displaying early errors · Pull Request #1786](https://github.com/qunitjs/qunit/pull/1786) |
0 commit comments