fix: add hint for missing `document` global in terminal error (#26218)

This came up on Discord as a question so I thought it's worth adding a
hint for this as it might be a common pitfall.

---------

Signed-off-by: Bartek Iwańczuk <biwanczuk@gmail.com>
Co-authored-by: David Sherret <dsherret@users.noreply.github.com>

11 files changed, 67 insertions, 1 deletions

diff --git a/Cargo.lock b/Cargo.lock
index 6e4712388..8cffe6eb4 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1997,6 +1997,7 @@ dependencies = [
 name = "deno_runtime"
 version = "0.180.0"
 dependencies = [
+ "color-print",
  "deno_ast",
  "deno_broadcast_channel",
  "deno_cache",
diff --git a/Cargo.toml b/Cargo.toml
index e83d4239e..25842134a 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -106,6 +106,7 @@ cbc = { version = "=0.1.2", features = ["alloc"] }
 # Note: Do not use the "clock" feature of chrono, as it links us to CoreFoundation on macOS.
 #       Instead use util::time::utc_now()
 chrono = { version = "0.4", default-features = false, features = ["std", "serde"] }
+color-print = "0.3.5"
 console_static_text = "=0.8.1"
 dashmap = "5.5.3"
 data-encoding = "2.3.3"
diff --git a/cli/Cargo.toml b/cli/Cargo.toml
index 8d1d1d124..f1a8ca0a2 100644
--- a/cli/Cargo.toml
+++ b/cli/Cargo.toml
@@ -94,7 +94,7 @@ chrono = { workspace = true, features = ["now"] }
 clap = { version = "=4.5.16", features = ["env", "string", "wrap_help", "error-context"] }
 clap_complete = "=4.5.24"
 clap_complete_fig = "=4.5.2"
-color-print = "0.3.5"
+color-print.workspace = true
 console_static_text.workspace = true
 dashmap.workspace = true
 data-encoding.workspace = true
diff --git a/runtime/Cargo.toml b/runtime/Cargo.toml
index ba9dc6243..6cb00a97e 100644
--- a/runtime/Cargo.toml
+++ b/runtime/Cargo.toml
@@ -100,6 +100,7 @@ deno_websocket.workspace = true
 deno_webstorage.workspace = true
 node_resolver = { workspace = true, features = ["sync"] }
 
+color-print.workspace = true
 dlopen2.workspace = true
 encoding_rs.workspace = true
 fastwebsockets.workspace = true
diff --git a/runtime/fmt_errors.rs b/runtime/fmt_errors.rs
index 0d4274e8a..2d9d09a29 100644
--- a/runtime/fmt_errors.rs
+++ b/runtime/fmt_errors.rs
@@ -1,5 +1,6 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 //! This mod provides DenoError to unify errors across Deno.
+use color_print::cstr;
 use deno_core::error::format_frame;
 use deno_core::error::JsError;
 use deno_terminal::colors::cyan;
@@ -367,6 +368,16 @@ fn get_suggestions_for_terminal_errors(e: &JsError) -> Vec<FixSuggestion> {
           ]
         )
       ];
+    } else if msg.contains("document is not defined") {
+      return vec![
+        FixSuggestion::info(cstr!(
+          "<u>document</> global is not available in Deno."
+        )),
+        FixSuggestion::hint_multiline(&[
+          cstr!("Use a library like <u>happy-dom</>, <u>deno_dom</>, <u>linkedom</> or <u>JSDom</>"),
+          cstr!("and setup the <u>document</> global according to the library documentation."),
+        ]),
+      ];
     }
   }
 
diff --git a/tests/specs/run/document/__test__.jsonc b/tests/specs/run/document/__test__.jsonc
new file mode 100644
index 000000000..cf20f9e1b
--- /dev/null
+++ b/tests/specs/run/document/__test__.jsonc
@@ -0,0 +1,9 @@
+{
+  "tests": {
+    "document": {
+      "args": "run document.js",
+      "exitCode": 1,
+      "output": "document.out"
+    }
+  }
+}
diff --git a/tests/specs/run/document/document.js b/tests/specs/run/document/document.js
new file mode 100644
index 000000000..63e43b72f
--- /dev/null
+++ b/tests/specs/run/document/document.js
@@ -0,0 +1 @@
+document.querySelector("div");
diff --git a/tests/specs/run/document/document.out b/tests/specs/run/document/document.out
new file mode 100644
index 000000000..eefedb8f2
--- /dev/null
+++ b/tests/specs/run/document/document.out
@@ -0,0 +1,8 @@
+error: Uncaught (in promise) ReferenceError: document is not defined
+document.querySelector("div");
+^
+    at [WILDCARD]document.js:1:1
+
+    info: document global is not available in Deno.
+    hint: Use a library like happy-dom, deno_dom, linkedom or JSDom
+          and setup the document global according to the library documentation.
diff --git a/tests/specs/test/document/__test__.jsonc b/tests/specs/test/document/__test__.jsonc
new file mode 100644
index 000000000..cf73b4bab
--- /dev/null
+++ b/tests/specs/test/document/__test__.jsonc
@@ -0,0 +1,9 @@
+{
+  "tests": {
+    "document": {
+      "args": "test document_test.js",
+      "exitCode": 1,
+      "output": "document_test.out"
+    }
+  }
+}
diff --git a/tests/specs/test/document/document_test.js b/tests/specs/test/document/document_test.js
new file mode 100644
index 000000000..d60d6893c
--- /dev/null
+++ b/tests/specs/test/document/document_test.js
@@ -0,0 +1,3 @@
+Deno.test("document query selector", () => {
+  document.querySelector("div");
+});
diff --git a/tests/specs/test/document/document_test.out b/tests/specs/test/document/document_test.out
new file mode 100644
index 000000000..342cee0e4
--- /dev/null
+++ b/tests/specs/test/document/document_test.out
@@ -0,0 +1,22 @@
+running 1 test from ./document_test.js
+document query selector ... FAILED [WILDCARD]
+
+ ERRORS 
+
+document query selector => ./document_test.js:1:6
+error: ReferenceError: document is not defined
+  document.querySelector("div");
+  ^
+    at [WILDCARD]document_test.js:2:3
+
+    info: document global is not available in Deno.
+    hint: Use a library like happy-dom, deno_dom, linkedom or JSDom
+          and setup the document global according to the library documentation.
+
+ FAILURES 
+
+document query selector => ./document_test.js:1:6
+
+FAILED | 0 passed | 1 failed ([WILDCARD])
+
+error: Test failed