Skip to content

armgit / mocha

Public Imported from GitHub
0

☕️ Classic, reliable, trusted test framework for Node.js and the browser

feat: expose globalThis.mocha with runner name and version (#6396)

Ravia9fc52968316
diff --git a/lib/context.js b/lib/context.js
index a5f0b76a..da2ad3ed 100644
--- a/lib/context.js
+++ b/lib/context.js
@@ -1,3 +1,31 @@
+import debugModule from "debug";
+import packageJson from "../package.json" with { type: "json" };
+
+const debug = debugModule("mocha:context");
+
+/**
+ * Defines `globalThis.mocha` so external tooling can statically identify
+ * Mocha as the active test runner. Writable/configurable so the browser
+ * bundle can overwrite it with the real Mocha instance without throwing.
+ * Guarded because sandboxed runtimes (SES/Endo, ShadowRealm) can disallow
+ * globalThis mutation, in those environments the marker is simply absent.
+ *
+ * @example
+ * globalThis.mocha; // { name: "mocha", version: "X.Y.Z" }
+ */
+try {
+ Object.defineProperty(globalThis, "mocha", {
+ value: {
+ name: packageJson.name,
+ version: packageJson.version,
+ },
+ writable: true,
+ configurable: true,
+ });
+} catch (err) {
+ debug("unable to define globalThis.mocha", err);
+}
+
/**
* @typedef {import('./runnable.js')} Runnable
*/
diff --git a/test/integration/fixtures/global-variable-occupied.fixture.js b/test/integration/fixtures/global-variable-occupied.fixture.js
new file mode 100644
index 00000000..cba8c965
--- /dev/null
+++ b/test/integration/fixtures/global-variable-occupied.fixture.js
@@ -0,0 +1,7 @@
+"use strict";
+
+Object.defineProperty(globalThis, "mocha", {
+ value: "occupied-by-another-tool",
+ configurable: false,
+ writable: false,
+});
diff --git a/test/integration/global-variable.spec.cjs b/test/integration/global-variable.spec.cjs
new file mode 100644
index 00000000..f4d3c713
--- /dev/null
+++ b/test/integration/global-variable.spec.cjs
@@ -0,0 +1,39 @@
+"use strict";
+
+const mochaPackageJson = require("../../package.json");
+const {
+ runMochaAsync,
+ resolveFixturePath,
+ DEFAULT_FIXTURE,
+} = require("./helpers.cjs");
+
+describe('global "mocha" object', function () {
+ it("exposes the runner name and version", function () {
+ expect(globalThis.mocha, "to be an object");
+ expect(globalThis.mocha.name, "to equal", mochaPackageJson.name);
+ expect(globalThis.mocha.version, "to equal", mochaPackageJson.version);
+ });
+
+ it("is writable and configurable so other code can overwrite it", function () {
+ const original = globalThis.mocha;
+ globalThis.mocha = { instance: true };
+ expect(globalThis.mocha, "to equal", { instance: true });
+ globalThis.mocha = original;
+ });
+
+ it("logs via debug instead of throwing when globalThis.mocha is already non-configurable", async function () {
+ const preloadPath = resolveFixturePath(
+ "global-variable-occupied.fixture.js",
+ );
+ const result = await runMochaAsync(DEFAULT_FIXTURE, [], {
+ stdio: "pipe",
+ env: {
+ ...process.env,
+ DEBUG: "mocha:context",
+ NODE_OPTIONS: `--require ${preloadPath}`,
+ },
+ });
+ expect(result.code, "to be", 0);
+ expect(result.output, "to contain", "unable to define globalThis.mocha");
+ });
+});