codeceptjs 3.6.10 → 3.7.0-beta.10

package/lib/container.js

@@ -1,26 +1,34 @@
-const glob = require('glob');
-const path = require('path');
-const { MetaStep } = require('./step');
-const { fileExists, isFunction, isAsyncFunction } = require('./utils');
-const Translation = require('./translation');
-const MochaFactory = require('./mochaFactory');
-const recorder = require('./recorder');
-const event = require('./event');
-const WorkerStorage = require('./workerStorage');
-const store = require('./store');
-const ai = require('./ai');
+const glob = require('glob')
+const path = require('path')
+const debug = require('debug')('codeceptjs:container')
+const { MetaStep } = require('./step')
+const { methodsOfObject, fileExists, isFunction, isAsyncFunction, installedLocally } = require('./utils')
+const Translation = require('./translation')
+const MochaFactory = require('./mocha/factory')
+const recorder = require('./recorder')
+const event = require('./event')
+const WorkerStorage = require('./workerStorage')
+const store = require('./store')
+const Result = require('./result')
+const ai = require('./ai')
+
+let asyncHelperPromise
 
 let container = {
   helpers: {},
   support: {},
+  proxySupport: {},
   plugins: {},
+  actor: null,
   /**
    * @type {Mocha | {}}
    * @ignore
    */
   mocha: {},
   translation: {},
-};
+  /** @type {Result | null} */
+  result: null,
+}
 
 /**
  * Dependency Injection Container
@@ -34,21 +42,32 @@ class Container {
    * @param {*} opts
    */
   static create(config, opts) {
-    const mochaConfig = config.mocha || {};
-    if (config.grep && !opts.grep) {
-      mochaConfig.grep = config.grep;
-    }
-    this.createMocha = () => {
-      container.mocha = MochaFactory.create(mochaConfig, opts || {});
-    };
-    this.createMocha();
-    container.helpers = createHelpers(config.helpers || {});
-    container.translation = loadTranslation(config.translation || null, config.vocabularies || []);
-    container.support = createSupportObjects(config.include || {});
-    container.plugins = createPlugins(config.plugins || {}, opts);
-    if (opts && opts.ai) ai.enable(config.ai); // enable AI Assistant
-    if (config.gherkin) loadGherkinSteps(config.gherkin.steps || []);
-    if (opts && typeof opts.timeouts === 'boolean') store.timeouts = opts.timeouts;
+    debug('creating container')
+    asyncHelperPromise = Promise.resolve()
+
+    // dynamically create mocha instance
+    const mochaConfig = config.mocha || {}
+    if (config.grep && !opts.grep) mochaConfig.grep = config.grep
+    this.createMocha = () => (container.mocha = MochaFactory.create(mochaConfig, opts || {}))
+    this.createMocha()
+
+    // create support objects
+    container.support = {}
+    container.helpers = createHelpers(config.helpers || {})
+    container.translation = loadTranslation(config.translation || null, config.vocabularies || [])
+    container.proxySupport = createSupportObjects(config.include || {})
+    container.plugins = createPlugins(config.plugins || {}, opts)
+    container.result = new Result()
+
+    createActor(config.include?.I)
+
+    if (opts && opts.ai) ai.enable(config.ai) // enable AI Assistant
+    if (config.gherkin) loadGherkinSteps(config.gherkin.steps || [])
+    if (opts && typeof opts.timeouts === 'boolean') store.timeouts = opts.timeouts
+  }
+
+  static actor() {
+    return container.support.I
   }
 
   /**
@@ -60,9 +79,9 @@ class Container {
    */
   static plugins(name) {
     if (!name) {
-      return container.plugins;
+      return container.plugins
     }
-    return container.plugins[name];
+    return container.plugins[name]
   }
 
   /**
@@ -74,9 +93,9 @@ class Container {
    */
   static support(name) {
     if (!name) {
-      return container.support;
+      return container.proxySupport
     }
-    return container.support[name];
+    return container.support[name] || container.proxySupport[name]
   }
 
   /**
@@ -88,9 +107,9 @@ class Container {
    */
   static helpers(name) {
     if (!name) {
-      return container.helpers;
+      return container.helpers
     }
-    return container.helpers[name];
+    return container.helpers[name]
   }
 
   /**
@@ -99,7 +118,7 @@ class Container {
    * @api
    */
   static translation() {
-    return container.translation;
+    return container.translation
   }
 
   /**
@@ -109,7 +128,19 @@ class Container {
    * @returns { * }
    */
   static mocha() {
-    return container.mocha;
+    return container.mocha
+  }
+
+  /**
+   * Get result
+   *
+   * @returns {Result}
+   */
+  static result() {
+    if (!container.result) {
+      container.result = new Result()
+    }
+    return container.result
   }
 
   /**
@@ -119,8 +150,9 @@ class Container {
    * @param {Object<string, *>} newContainer
    */
   static append(newContainer) {
-    const deepMerge = require('./utils').deepMerge;
-    container = deepMerge(container, newContainer);
+    const deepMerge = require('./utils').deepMerge
+    container = deepMerge(container, newContainer)
+    debug('appended', JSON.stringify(newContainer).slice(0, 300))
   }
 
   /**
@@ -131,10 +163,24 @@ class Container {
    * @param {Object<string, *>} newPlugins
    */
   static clear(newHelpers, newSupport, newPlugins) {
-    container.helpers = newHelpers || {};
-    container.support = newSupport || {};
-    container.plugins = newPlugins || {};
-    container.translation = loadTranslation();
+    container.helpers = newHelpers || {}
+    container.translation = loadTranslation()
+    container.proxySupport = createSupportObjects(newSupport || {})
+    container.plugins = newPlugins || {}
+    asyncHelperPromise = Promise.resolve()
+    store.actor = null
+    debug('container cleared')
+  }
+
+  /**
+   * @param {Function} fn
+   * @returns {Promise<void>}
+   */
+  static async started(fn = null) {
+    if (fn) {
+      asyncHelperPromise = asyncHelperPromise.then(fn)
+    }
+    return asyncHelperPromise
   }
 
   /**
@@ -144,299 +190,370 @@ class Container {
    * @param {Object} options - set {local: true} to not share among workers
    */
   static share(data, options = {}) {
-    Container.append({ support: data });
+    Container.append({ support: data })
     if (!options.local) {
-      WorkerStorage.share(data);
+      WorkerStorage.share(data)
+    }
+  }
+
+  static createMocha(config = {}, opts = {}) {
+    const mochaConfig = config?.mocha || {}
+    if (config?.grep && !opts?.grep) {
+      mochaConfig.grep = config.grep
     }
+    container.mocha = MochaFactory.create(mochaConfig, opts || {})
   }
 }
 
-module.exports = Container;
+Container.STANDARD_ACTING_HELPERS = ['Playwright', 'WebDriver', 'Puppeteer', 'Appium', 'TestCafe']
+
+module.exports = Container
 
 function createHelpers(config) {
-  const helpers = {};
-  let moduleName;
-  for (const helperName in config) {
+  const helpers = {}
+  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(' ')}`;
-          }
-          throw new Error(`Required modules are not installed.\n\nRUN: ${install}`);
-        }
+      // handle async CJS modules that use dynamic import
+      if (isAsyncFunction(HelperClass)) {
+        helpers[helperName] = {}
+
+        asyncHelperPromise = asyncHelperPromise
+          .then(() => HelperClass())
+          .then(ResolvedHelperClass => {
+            // Check if ResolvedHelperClass is a constructor function
+            if (typeof ResolvedHelperClass?.constructor !== 'function') {
+              throw new Error(`Helper class from module '${helperName}' is not a class. Use CJS async module syntax.`)
+            }
+
+            debug(`helper ${helperName} async initialized`)
+
+            helpers[helperName] = new ResolvedHelperClass(config[helperName])
+          })
+
+        continue
       }
-      helpers[helperName] = new HelperClass(config[helperName]);
+
+      checkHelperRequirements(HelperClass)
+
+      helpers[helperName] = new HelperClass(config[helperName])
+      debug(`helper ${helperName} initialized`)
     } 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})`)
     }
   }
 
   for (const name in helpers) {
-    if (helpers[name]._init) helpers[name]._init();
+    if (helpers[name]._init) helpers[name]._init()
   }
-  return helpers;
+  return helpers
 }
 
-function createSupportObjects(config) {
-  const objects = {};
-
-  for (const name in config) {
-    objects[name] = {}; // placeholders
-  }
-
-  if (!config.I) {
-    objects.I = require('./actor')();
-
-    if (container.translation.I !== 'I') {
-      objects[container.translation.I] = objects.I;
+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}`)
     }
   }
+}
 
-  container.support = objects;
-
-  function lazyLoad(name) {
-    let newObj = getSupportObject(config, name);
+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 {
-      if (typeof newObj === 'function') {
-        newObj = newObj();
-      } else if (newObj._init) {
-        newObj._init();
+      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) {
-      throw new Error(`Initialization failed for ${name}: ${newObj}\n${err.message}\n${err.stack}`);
+      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 newObj;
   }
+  return HelperClass
+}
 
+function createSupportObjects(config) {
   const asyncWrapper = function (f) {
     return function () {
-      return f.apply(this, arguments).catch((e) => {
-        recorder.saveFirstAsyncError(e);
-        throw e;
-      });
-    };
-  };
-
-  Object.keys(objects).forEach((object) => {
-    const currentObject = objects[object];
-    Object.keys(currentObject).forEach((method) => {
-      const currentMethod = currentObject[method];
-      if (currentMethod && currentMethod[Symbol.toStringTag] === 'AsyncFunction') {
-        objects[object][method] = asyncWrapper(currentMethod);
-      }
-    });
-  });
+      return f.apply(this, arguments).catch(e => {
+        recorder.saveFirstAsyncError(e)
+        throw e
+      })
+    }
+  }
 
-  return new Proxy({}, {
-    has(target, key) {
-      return key in config;
-    },
-    ownKeys() {
-      return Reflect.ownKeys(config);
-    },
-    get(target, key) {
-      // configured but not in support object, yet: load the module
-      if (key in objects && !(key in target)) {
-        // load default I
-        if (key in objects && !(key in config)) {
-          return target[key] = objects[key];
-        }
+  function lazyLoad(name) {
+    return new Proxy(
+      {},
+      {
+        get(target, prop) {
+          // behavr like array or
+          if (prop === 'length') return Object.keys(config).length
+          if (prop === Symbol.iterator) {
+            return function* () {
+              for (let i = 0; i < Object.keys(config).length; i++) {
+                yield target[i]
+              }
+            }
+          }
+
+          // load actual name from vocabulary
+          if (container.translation.name) {
+            name = container.translation.name
+          }
+
+          if (name === 'I') {
+            const actor = createActor(config.I)
+            methodsOfObject(actor)
+            return actor[prop]
+          }
+
+          if (!container.support[name] && typeof config[name] === 'object') {
+            container.support[name] = config[name]
+          }
 
-        // load new object
-        const object = lazyLoad(key);
-        // check that object is a real object and not an array
-        if (Object.prototype.toString.call(object) === '[object Object]') {
-          return target[key] = Object.assign(objects[key], object);
+          if (!container.support[name]) {
+            // Load object on first access
+            const supportObject = loadSupportObject(config[name])
+            container.support[name] = supportObject
+            try {
+              if (container.support[name]._init) {
+                container.support[name]._init()
+              }
+              debug(`support object ${name} initialized`)
+            } catch (err) {
+              throw new Error(`Initialization failed for ${name}: ${container.support[name]}\n${err.message}\n${err.stack}`)
+            }
+          }
+
+          const currentObject = container.support[name]
+          let currentValue = currentObject[prop]
+
+          if (isFunction(currentValue) || isAsyncFunction(currentValue)) {
+            const ms = new MetaStep(name, prop)
+            ms.setContext(currentObject)
+            if (isAsyncFunction(currentValue)) currentValue = asyncWrapper(currentValue)
+            debug(`metastep is created for ${name}.${prop.toString()}()`)
+            return ms.run.bind(ms, currentValue)
+          }
+
+          return currentValue
+        },
+        has(target, prop) {
+          container.support[name] = container.support[name] || loadSupportObject(config[name])
+          return prop in container.support[name]
+        },
+        getOwnPropertyDescriptor(target, prop) {
+          container.support[name] = container.support[name] || loadSupportObject(config[name])
+          return {
+            enumerable: true,
+            configurable: true,
+            value: this.get(target, prop),
+          }
+        },
+        ownKeys() {
+          container.support[name] = container.support[name] || loadSupportObject(config[name])
+          return Reflect.ownKeys(container.support[name])
+        },
+      },
+    )
+  }
+
+  const keys = Reflect.ownKeys(config)
+  return new Proxy(
+    {},
+    {
+      has(target, key) {
+        return keys.includes(key)
+      },
+      ownKeys() {
+        return keys
+      },
+      getOwnPropertyDescriptor(target, prop) {
+        return {
+          enumerable: true,
+          configurable: true,
+          value: this.get(target, prop),
         }
-        target[key] = object;
-      }
-      return target[key];
+      },
+      get(target, key) {
+        return lazyLoad(key)
+      },
     },
-  });
+  )
+}
+
+function createActor(actorPath) {
+  if (container.support.I) return container.support.I
+
+  if (actorPath) {
+    container.support.I = loadSupportObject(actorPath)
+  } else {
+    const actor = require('./actor')
+    container.support.I = actor()
+  }
+
+  return container.support.I
 }
 
 function createPlugins(config, options = {}) {
-  const plugins = {};
+  const plugins = {}
 
-  const enabledPluginsByOptions = (options.plugins || '').split(',');
+  const enabledPluginsByOptions = (options.plugins || '').split(',')
   for (const pluginName in config) {
-    if (!config[pluginName]) config[pluginName] = {};
-    if (!config[pluginName].enabled && (enabledPluginsByOptions.indexOf(pluginName) < 0)) {
-      continue; // plugin is disabled
+    if (!config[pluginName]) config[pluginName] = {}
+    if (!config[pluginName].enabled && enabledPluginsByOptions.indexOf(pluginName) < 0) {
+      continue // plugin is disabled
     }
-    let module;
+    let module
     try {
       if (config[pluginName].require) {
-        module = config[pluginName].require;
-        if (module.startsWith('.')) { // local
-          module = path.resolve(global.codecept_dir, module); // custom plugin
+        module = config[pluginName].require
+        if (module.startsWith('.')) {
+          // local
+          module = path.resolve(global.codecept_dir, module) // custom plugin
         }
       } else {
-        module = `./plugin/${pluginName}`;
+        module = `./plugin/${pluginName}`
       }
-      plugins[pluginName] = require(module)(config[pluginName]);
+      plugins[pluginName] = require(module)(config[pluginName])
     } catch (err) {
-      throw new Error(`Could not load plugin ${pluginName} from module '${module}':\n${err.message}\n${err.stack}`);
+      throw new Error(`Could not load plugin ${pluginName} from module '${module}':\n${err.message}\n${err.stack}`)
     }
   }
-  return plugins;
-}
-
-function getSupportObject(config, name) {
-  const module = config[name];
-  if (typeof module === 'string') {
-    return loadSupportObject(module, name);
-  }
-  return module;
+  return plugins
 }
 
 function loadGherkinSteps(paths) {
-  global.Before = fn => event.dispatcher.on(event.test.started, fn);
-  global.After = fn => event.dispatcher.on(event.test.finished, fn);
-  global.Fail = fn => event.dispatcher.on(event.test.failed, fn);
+  global.Before = fn => event.dispatcher.on(event.test.started, fn)
+  global.After = fn => event.dispatcher.on(event.test.finished, fn)
+  global.Fail = fn => event.dispatcher.on(event.test.failed, fn)
 
   // If gherkin.steps is string, then this will iterate through that folder and send all step def js files to loadSupportObject
   // If gherkin.steps is Array, it will go the old way
   // This is done so that we need not enter all Step Definition files under config.gherkin.steps
   if (Array.isArray(paths)) {
     for (const path of paths) {
-      loadSupportObject(path, `Step Definition from ${path}`);
+      loadSupportObject(path, `Step Definition from ${path}`)
     }
   } else {
-    const folderPath = paths.startsWith('.') ? path.join(global.codecept_dir, paths) : '';
+    const folderPath = paths.startsWith('.') ? path.join(global.codecept_dir, paths) : ''
     if (folderPath !== '') {
-      glob.sync(folderPath).forEach((file) => {
-        loadSupportObject(file, `Step Definition from ${file}`);
-      });
+      glob.sync(folderPath).forEach(file => {
+        loadSupportObject(file, `Step Definition from ${file}`)
+      })
     }
   }
 
-  delete global.Before;
-  delete global.After;
-  delete global.Fail;
+  delete global.Before
+  delete global.After
+  delete global.Fail
 }
 
 function loadSupportObject(modulePath, supportObjectName) {
+  if (!modulePath) {
+    throw new Error(`Support object "${supportObjectName}" is not defined`)
+  }
   if (modulePath.charAt(0) === '.') {
-    modulePath = path.join(global.codecept_dir, modulePath);
+    modulePath = path.join(global.codecept_dir, modulePath)
   }
   try {
-    const obj = require(modulePath);
+    const obj = require(modulePath)
 
+    // Handle different types of imports
     if (typeof obj === 'function') {
-      const fobj = obj();
-
-      if (fobj.constructor.name === 'Actor') {
-        const methods = getObjectMethods(fobj);
-        Object.keys(methods)
-          .forEach(key => {
-            fobj[key] = methods[key];
-          });
-
-        return methods;
+      // If it's a class (constructor function)
+      if (obj.prototype && obj.prototype.constructor === obj) {
+        const ClassName = obj
+        return new ClassName()
       }
+      // If it's a regular function
+      return obj()
     }
-    if (typeof obj !== 'function'
-      && Object.getPrototypeOf(obj) !== Object.prototype
-      && !Array.isArray(obj)
-    ) {
-      const methods = getObjectMethods(obj);
-      Object.keys(methods)
-        .filter(key => !key.startsWith('_'))
-        .forEach(key => {
-          const currentMethod = methods[key];
-          if (isFunction(currentMethod) || isAsyncFunction(currentMethod)) {
-            const ms = new MetaStep(supportObjectName, key);
-            ms.setContext(methods);
-            methods[key] = ms.run.bind(ms, currentMethod);
-          }
-        });
-      return methods;
+
+    if (obj && Array.isArray(obj)) {
+      return obj
     }
-    if (!Array.isArray(obj)) {
-      Object.keys(obj)
-        .filter(key => !key.startsWith('_'))
-        .forEach(key => {
-          const currentMethod = obj[key];
-          if (isFunction(currentMethod) || isAsyncFunction(currentMethod)) {
-            const ms = new MetaStep(supportObjectName, key);
-            ms.setContext(obj);
-            obj[key] = ms.run.bind(ms, currentMethod);
-          }
-        });
+
+    // If it's a plain object
+    if (obj && typeof obj === 'object') {
+      return obj
     }
 
-    return obj;
+    throw new Error(`Support object "${supportObjectName}" should be an object, class, or function, but got ${typeof obj}`)
   } catch (err) {
-    throw new Error(`Could not include object ${supportObjectName} from module '${modulePath}'\n${err.message}\n${err.stack}`);
+    throw new Error(`Could not include object ${supportObjectName} from module '${modulePath}'\n${err.message}\n${err.stack}`)
   }
 }
 
 /**
  * Method collect own property and prototype
  */
-function getObjectMethods(obj) {
-  const methodsSet = new Set();
-  let protoObj = Reflect.getPrototypeOf(obj);
-  do {
-    if (protoObj.constructor.prototype !== Object.prototype) {
-      const keys = Reflect.ownKeys(protoObj);
-      keys.forEach(k => methodsSet.add(k));
-    }
-  } while (protoObj = Reflect.getPrototypeOf(protoObj));
-  Reflect.ownKeys(obj).forEach(k => methodsSet.add(k));
-  const methods = {};
-  for (const key of methodsSet.keys()) {
-    if (key !== 'constructor') methods[key] = obj[key];
-  }
-  return methods;
-}
 
 function loadTranslation(locale, vocabularies) {
   if (!locale) {
-    return Translation.createEmpty();
+    return Translation.createEmpty()
   }
 
-  let translation;
+  let translation
 
   // check if it is a known translation
   if (Translation.langs[locale]) {
-    translation = new Translation(Translation.langs[locale]);
+    translation = new Translation(Translation.langs[locale])
   } else if (fileExists(path.join(global.codecept_dir, locale))) {
     // get from a provided file instead
-    translation = Translation.createDefault();
-    translation.loadVocabulary(locale);
+    translation = Translation.createDefault()
+    translation.loadVocabulary(locale)
   } else {
-    translation = Translation.createDefault();
+    translation = Translation.createDefault()
   }
 
-  vocabularies.forEach(v => translation.loadVocabulary(v));
+  vocabularies.forEach(v => translation.loadVocabulary(v))
+
+  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
+  }
 
-  return translation;
+  // built-in helpers
+  return `./helper/${helperName}`
 }