fix(cds-plugin-ui5): disable plugin for JEST test execution

As dynamic imports are only supported in JEST with Node.js 21
and the experimental flag: NODE_OPTIONS=--experimental-vm-modules
we by default disable the cds-plugin-ui5 to avoid issues. It
can be forcefully activated by CDS_PLUGIN_UI5_ACTIVE=true when
testing in the environment as described above.

Fixes #901

packages/cds-plugin-ui5/README.md

@@ -146,6 +146,14 @@ module.exports = async ({ log, resources, options }) => {
 
 The returned app pages will be added to the welcome page within the respective mount path.
 
+## Hints
+
+This section includes hints for the usage of the `cds-plugin-ui5` with other tools.
+
+### JEST
+
+The `cds-plugin-ui5` doesn't work with JEST out of the box as it internally is using dynamic imports to load helpers from the UI5 tooling. JEST fails with a `segmentation fault` error and therefore, the `cds-plugin-ui5` is disabled when running in context of JEST. It can be forcefully enabled by setting the environment variable `CDS_PLUGIN_UI5_ACTIVE=true`. But in this case you need to at least use Node.js 21 (https://github.com/nodejs/node/issues/35889) and you need to enable the experimental support for ES modules (https://jestjs.io/docs/ecmascript-modules). This enables the `cds-plugin-ui5` to run in context of JEST.
+
 ## Support
 
 Please use the GitHub bug tracking system to post questions, bug reports or to create pull requests.

packages/cds-plugin-ui5/cds-plugin.js

@@ -1,7 +1,32 @@
+const log = require("./lib/log");
+
+// >> IMPORTANT <<
+//
+// JEST has issues with dynamic imports and will fail when they are used,
+// e.g. in the findUI5Modules the UI5 tooling is used which is implemented
+// using ES modules. To avoid issues when running JEST tests, the plugin
+// will be disabled by default but it can be enforced with CDS_PLUGIN_UI5_ACTIVE=true
+// since JEST supports ES modules when using Node.js 21 and the experimental
+// support for VM modules via:
+//
+//   > NODE_OPTIONS=--experimental-vm-modules jest
+//
+// Details can be found in the following issue:
+//   - https://github.com/ui5-community/ui5-ecosystem-showcase/issues/901
+//
+// To disable JEST we rely on env variables (see https://jestjs.io/docs/environment-variables)
+if (process.env.NODE_ENV === "test" && process.env.JEST_WORKER_ID && process.env.CDS_PLUGIN_UI5_ACTIVE !== "true") {
+	log.info("Skip execution of plugin because JEST is running tests! To force the execution of the plugin set env var CDS_PLUGIN_UI5_ACTIVE=true...");
+	return;
+}
+if (process.env.CDS_PLUGIN_UI5_ACTIVE === "false") {
+	log.info("Skip execution of plugin because it has been disabled by env var CDS_PLUGIN_UI5_ACTIVE!");
+	return;
+}
+
 // @sap/cds/lib/index.js#138: global.cds = cds // REVISIT: using global.cds seems wrong
 const cds = global.cds || require("@sap/cds"); // reuse already loaded cds!
 
-const log = require("./lib/log");
 const findUI5Modules = require("./lib/findUI5Modules");
 const createPatchedRouter = require("./lib/createPatchedRouter");
 const applyUI5Middleware = require("./lib/applyUI5Middleware");