improved loading esm/cjs style modules

Author: DavertMik

lib/container.js

@@ -1,7 +1,8 @@
 const glob = require('glob');
 const path = require('path');
+const { isPromise } = require('util/types');
 const { MetaStep } = require('./step');
-const { fileExists, isFunction, isAsyncFunction } = require('./utils');
+const { fileExists, isFunction, isAsyncFunction, installedLocally } = require('./utils');
 const Translation = require('./translation');
 const MochaFactory = require('./mochaFactory');
 const recorder = require('./recorder');
@@ -155,45 +156,42 @@ module.exports = Container;
 
 function createHelpers(config) {
   const helpers = {};
-  let moduleName;
-  for (const helperName in config) {
+  for (let helperName in config) {
     try {
-      if (config[helperName].require) {
-        if (config[helperName].require.startsWith('.')) {
-          moduleName = path.resolve(global.codecept_dir, config[helperName].require); // custom helper
-        } else {
-          moduleName = config[helperName].require; // plugin helper
-        }
-      } else {
-        moduleName = `./helper/${helperName}`; // built-in helper
+      let HelperClass;
+
+      // ESM import
+      if (helperName?.constructor === Function && helperName.prototype) {
+        HelperClass = helperName;
+        helperName = HelperClass.constructor.name;
       }
 
-      // @ts-ignore
-      let HelperClass;
-      // check if the helper is the built-in, use the require() syntax.
-      if (moduleName.startsWith('./helper/')) {
-        HelperClass = require(moduleName);
-      } else {
-        // check if the new syntax export default HelperName is used and loads the Helper, otherwise loads the module that used old syntax export = HelperName.
-        HelperClass = require(moduleName).default || require(moduleName);
+      // classical require
+      if (!HelperClass) {
+        HelperClass = requireHelperFromModule(helperName, config);
       }
 
-      if (HelperClass._checkRequirements) {
-        const requirements = HelperClass._checkRequirements();
-        if (requirements) {
-          let install;
-          if (require('./utils').installedLocally()) {
-            install = `npm install --save-dev ${requirements.join(' ')}`;
-          } else {
-            console.log('WARNING: CodeceptJS is not installed locally. It is recommended to switch to local installation');
-            install = `[sudo] npm install -g ${requirements.join(' ')}`;
+      // handle async CJS modules that use dynamic import
+      if (isPromise(HelperClass) && typeof HelperClass.then === 'function') {
+        HelperClass = HelperClass.then(ResolvedHelperClass => {
+          // Check if ResolvedHelperClass is a constructor function
+          if (typeof ResolvedHelperClass !== 'function' || !ResolvedHelperClass.prototype) {
+            throw new Error(`Helper class from module '${helperName}' is not a constructor. Use CJS async module syntax.`);
           }
-          throw new Error(`Required modules are not installed.\n\nRUN: ${install}`);
-        }
+          try {
+            helpers[helperName] = new ResolvedHelperClass(config[helperName]);
+          } catch (err) {
+            throw new Error(`Could not load helper ${helperName} as async module (${err.message})`);
+          }
+        });
+        continue;
       }
+
+      checkHelperRequirements(HelperClass);
+
       helpers[helperName] = new HelperClass(config[helperName]);
     } catch (err) {
-      throw new Error(`Could not load helper ${helperName} from module '${moduleName}':\n${err.message}\n${err.stack}`);
+      throw new Error(`Could not load helper ${helperName} (${err.message})`);
     }
   }
 
@@ -203,6 +201,44 @@ function createHelpers(config) {
   return helpers;
 }
 
+function checkHelperRequirements(HelperClass) {
+  if (HelperClass._checkRequirements) {
+    const requirements = HelperClass._checkRequirements();
+    if (requirements) {
+      let install;
+      if (installedLocally()) {
+        install = `npm install --save-dev ${requirements.join(' ')}`;
+      } else {
+        console.log('WARNING: CodeceptJS is not installed locally. It is recommended to switch to local installation');
+        install = `[sudo] npm install -g ${requirements.join(' ')}`;
+      }
+      throw new Error(`Required modules are not installed.\n\nRUN: ${install}`);
+    }
+  }
+}
+
+function requireHelperFromModule(helperName, config, HelperClass) {
+  const moduleName = getHelperModuleName(helperName, config);
+  if (moduleName.startsWith('./helper/')) {
+    HelperClass = require(moduleName);
+  } else {
+    // check if the new syntax export default HelperName is used and loads the Helper, otherwise loads the module that used old syntax export = HelperName.
+    try {
+      const mod = require(moduleName);
+      if (!mod && !mod.default) {
+        throw new Error(`Helper module '${moduleName}' was not found. Make sure you have installed the package correctly.`);
+      }
+      HelperClass = mod.default || mod;
+    } catch (err) {
+      if (err.code === 'MODULE_NOT_FOUND') {
+        throw new Error(`Helper module '${moduleName}' was not found. Make sure you have installed the package correctly.`);
+      }
+      throw err;
+    }
+  }
+  return HelperClass;
+}
+
 function createSupportObjects(config) {
   const objects = {};
 
@@ -440,3 +476,21 @@ function loadTranslation(locale, vocabularies) {
 
   return translation;
 }
+
+function getHelperModuleName(helperName, config) {
+  // classical require
+  if (config[helperName].require) {
+    if (config[helperName].require.startsWith('.')) {
+      return path.resolve(global.codecept_dir, config[helperName].require); // custom helper
+    }
+    return config[helperName].require; // plugin helper
+  }
+
+  // built-in helpers
+  if (helperName.startsWith('@codeceptjs/')) {
+    return helperName;
+  }
+
+  // built-in helpers
+  return `./helper/${helperName}`;
+}

test/acceptance/codecept.Playwright.js

@@ -23,9 +23,7 @@ module.exports.config = {
       require: '../support/ScreenshotSessionHelper.js',
       outputPath: 'test/acceptance/output',
     },
-    Expect: {
-      require: '@codeceptjs/expect-helper',
-    },
+    '@codeceptjs/expect-helper': {},
   },
   include: {},
   bootstrap: false,