Fix defenitions generation error (#2707)

* fix LocatorOrString definitions generation

* chore: fix formating

* refactor: make definitions.js more unerstandable, fix lint errors

* fix: turn on doc generation for defenitions

Author: elukoyanov

docs/helpers/Appium.md

@@ -1481,7 +1481,7 @@ I.seeTextEquals('text', 'h1');
 #### Parameters
 
 -   `text` **[string][4]** element value to check.
--   `context` **([string][4] \| [object][6]?)** element located by CSS|XPath|strict locator. (optional, default `null`)
+-   `context` **([string][4] \| [object][6])?** element located by CSS|XPath|strict locator. (optional, default `null`)
 
 ### seeElementInDOM
 

docs/helpers/Playwright.md

@@ -1454,7 +1454,7 @@ I.seeTextEquals('text', 'h1');
 #### Parameters
 
 -   `text` **[string][7]** element value to check.
--   `context` **([string][7] | [object][5]?)** element located by CSS|XPath|strict locator. 
+-   `context` **([string][7] | [object][5])?** element located by CSS|XPath|strict locator. 
 
 ### seeTitleEquals
 

docs/helpers/Protractor.md

@@ -1261,7 +1261,7 @@ I.seeTextEquals('text', 'h1');
 #### Parameters
 
 -   `text` **[string][9]** element value to check.
--   `context` **([string][9] | [object][10]?)** element located by CSS|XPath|strict locator. 
+-   `context` **([string][9] | [object][10])?** element located by CSS|XPath|strict locator. 
 
 ### seeTitleEquals
 

docs/helpers/Puppeteer.md

@@ -1586,7 +1586,7 @@ I.seeTextEquals('text', 'h1');
 #### Parameters
 
 -   `text` **[string][8]** element value to check.
--   `context` **([string][8] | [object][6]?)** element located by CSS|XPath|strict locator. 
+-   `context` **([string][8] | [object][6])?** element located by CSS|XPath|strict locator. 
 
 ### seeTitleEquals
 

docs/helpers/WebDriver.md

@@ -1768,7 +1768,7 @@ I.seeTextEquals('text', 'h1');
 #### Parameters
 
 -   `text` **[string][19]** element value to check.
--   `context` **([string][19] | [object][18]?)** element located by CSS|XPath|strict locator. 
+-   `context` **([string][19] | [object][18])?** element located by CSS|XPath|strict locator. 
 
 ### seeTitleEquals
 

lib/command/definitions.js

@@ -5,28 +5,112 @@ const { getConfig, getTestRoot } = require('./utils');
 const Codecept = require('../codecept');
 const container = require('../container');
 const output = require('../output');
-const actingHelpers = [...require('../../lib/plugin/standardActingHelpers'), 'REST'];
+const actingHelpers = [...require('../plugin/standardActingHelpers'), 'REST'];
 
-const template = ({
-  helperNames, supportObject, importPaths, translations, hasCustomStepsFile, hasCustomHelper, customHelpers,
-}) => `/// <reference types='codeceptjs' />
-${importPaths.join('\n')}
+/**
+ * Prepare data and generate content of definitions file
+ * @private
+ *
+ * @param {Object} params
+ * @param {boolean} params.hasCustomStepsFile
+ * @param {boolean} params.hasCustomHelper
+ * @param {Map} params.supportObject
+ * @param {Array<string>} params.helperNames
+ * @param {Array<string>} params.importPaths
+ * @param {Array<string>} params.customHelpers
+ * @param params.translations
+ *
+ * @returns {string}
+ */
+const getDefinitionsFileContent = ({
+  hasCustomHelper,
+  hasCustomStepsFile,
+  helperNames,
+  supportObject,
+  importPaths,
+  translations,
+  customHelpers,
+}) => {
+  const getHelperListFragment = ({
+    hasCustomHelper,
+    hasCustomStepsFile,
+    customHelpers,
+  }) => {
+    if (hasCustomHelper && hasCustomStepsFile) {
+      return `${['ReturnType<steps_file>', ...customHelpers].join(', ')}`;
+    }
+
+    if (hasCustomStepsFile) {
+      return 'ReturnType<steps_file>';
+    }
+
+    return 'WithTranslation<Methods>';
+  };
+
+  const helpersListFragment = getHelperListFragment({
+    hasCustomHelper,
+    hasCustomStepsFile,
+    customHelpers,
+  });
+
+  const importPathsFragment = importPaths.join('\n');
+  const supportObjectsTypeFragment = convertMapToType(supportObject);
+  const methodsTypeFragment = helperNames.length > 0
+    ? `interface Methods extends ${helperNames.join(', ')} {}`
+    : '';
+  const translatedActionsFragment = JSON.stringify(translations.vocabulary.actions, null, 2);
+
+  return generateDefinitionsContent({
+    helpersListFragment,
+    importPathsFragment,
+    supportObjectsTypeFragment,
+    methodsTypeFragment,
+    translatedActionsFragment,
+  });
+};
+
+/**
+ * Generate content for definitions file from fragments
+ * @private
+ *
+ * @param {Object} fragments - parts for template
+ * @param {string} fragments.importPathsFragment
+ * @param {string} fragments.supportObjectsTypeFragment
+ * @param {string} fragments.methodsTypeFragment
+ * @param {string} fragments.helpersListFragment
+ * @param {string} fragments.translatedActionsFragment
+ *
+ * @returns {string}
+ */
+const generateDefinitionsContent = ({
+  importPathsFragment,
+  supportObjectsTypeFragment,
+  methodsTypeFragment,
+  helpersListFragment,
+  translatedActionsFragment,
+}) => {
+  return `/// <reference types='codeceptjs' />
+${importPathsFragment}
 
 declare namespace CodeceptJS {
-  interface SupportObject ${convertMapToType(supportObject)}
-  ${helperNames.length > 0 ? `interface Methods extends ${helperNames.join(', ')} {}` : ''}
-  interface I extends ${hasCustomStepsFile && hasCustomStepsFile ? `${['ReturnType<steps_file>', ...customHelpers].join(', ')}` : hasCustomStepsFile ? 'ReturnType<steps_file>' : 'WithTranslation<Methods>'} {}
+  interface SupportObject ${supportObjectsTypeFragment}
+  ${methodsTypeFragment}
+  interface I extends ${helpersListFragment} {}
   namespace Translation {
-    interface Actions ${JSON.stringify(translations.vocabulary.actions, null, 2)}
+    interface Actions ${translatedActionsFragment}
   }
 }
 `;
+};
 
+/** @type {Array<string>} */
 const helperNames = [];
+/** @type {Array<string>} */
 const customHelpers = [];
 
 module.exports = function (genPath, options) {
   const configFile = options.config || genPath;
+  /** @type {string} */
   const testsPath = getTestRoot(configFile);
   const config = getConfig(configFile);
   if (!config) return;
@@ -35,9 +119,12 @@ module.exports = function (genPath, options) {
   const helperPaths = {};
   /** @type {Object<string, string>} */
   const supportPaths = {};
+  /** @type {boolean} */
   let hasCustomStepsFile = false;
-  let hasCustomerHelper = false;
+  /** @type {boolean} */
+  let hasCustomHelper = false;
 
+  /** @type {string} */
   const targetFolderPath = options.output && getTestRoot(options.output) || testsPath;
 
   const codecept = new Codecept(config, {});
@@ -46,13 +133,13 @@ module.exports = function (genPath, options) {
   const helpers = container.helpers();
   const translations = container.translation();
   for (const name in helpers) {
-      const require = codecept.config.helpers[name].require;
-      if (require) {
-        helperPaths[name] = require;
-        helperNames.push(name);
-      } else {
-        helperNames.push(name);
-      }
+    const require = codecept.config.helpers[name].require;
+    if (require) {
+      helperPaths[name] = require;
+      helperNames.push(name);
+    } else {
+      helperNames.push(name);
+    }
 
     if (!actingHelpers.includes(name)) {
       customHelpers.push(`WithTranslation<${name}>`);
@@ -64,7 +151,7 @@ module.exports = function (genPath, options) {
   supportObject.set('current', 'any');
 
   if (customHelpers.length > 0) {
-    hasCustomerHelper = true;
+    hasCustomHelper = true;
   }
 
   for (const name in codecept.config.include) {
@@ -78,26 +165,26 @@ module.exports = function (genPath, options) {
     supportObject.set(name, name);
   }
 
-  const definitionsTemplate = template({
+  const definitionsFileContent = getDefinitionsFileContent({
     helperNames,
     supportObject,
     importPaths: getImportString(testsPath, targetFolderPath, supportPaths, helperPaths),
     translations,
     hasCustomStepsFile,
-    hasCustomerHelper,
-    customHelpers
+    hasCustomHelper,
+    customHelpers,
   });
 
-  fs.writeFileSync(path.join(targetFolderPath, 'steps.d.ts'), definitionsTemplate);
+  fs.writeFileSync(path.join(targetFolderPath, 'steps.d.ts'), definitionsFileContent);
   output.print('TypeScript Definitions provide autocompletion in Visual Studio Code and other IDEs');
   output.print('Definitions were generated in steps.d.ts');
 };
 
 /**
  * Returns the relative path from the  to the targeted folder.
  * @param {string} originalPath
- * @param { string} targetFolderPath
- * @param { string} testsPath
+ * @param {string} targetFolderPath
+ * @param {string} testsPath
  */
 function getPath(originalPath, targetFolderPath, testsPath) {
   const parsedPath = path.parse(originalPath);
@@ -119,7 +206,8 @@ function getPath(originalPath, targetFolderPath, testsPath) {
  * @param {string} targetFolderPath
  * @param {Object<string, string>} pathsToType
  * @param {Object<string, string>} pathsToValue
- * @returns
+ *
+ * @returns {Array<string>}
  */
 function getImportString(testsPath, targetFolderPath, pathsToType, pathsToValue) {
   const importStrings = [];
@@ -139,6 +227,8 @@ function getImportString(testsPath, targetFolderPath, pathsToType, pathsToValue)
 
 /**
  * @param {Map} map
+ *
+ * @returns {string}
  */
 function convertMapToType(map) {
   return `{ ${Array.from(map).map(([key, value]) => `${key}: ${value}`).join(', ')} }`;

runok.js

@@ -23,7 +23,7 @@ module.exports = {
 
   async def() {
     await Promise.all([
-      // this.buildLibWithDocs(true),
+      this.buildLibWithDocs(true),
       this.docsPlugins(),
       this.docsExternalHelpers(),
     ]);
@@ -156,6 +156,8 @@ Our community prepared some valuable recipes for setting up CI systems with Code
           cfg.replace(placeholders[i], templates[i]);
         }
         if (!forTypings) {
+          cfg.replace(/CodeceptJS.LocatorOrString\?/g, '(string | object)?');
+          cfg.replace(/LocatorOrString\?/g, '(string | object)?');
           cfg.replace(/CodeceptJS.LocatorOrString/g, 'string | object');
           cfg.replace(/LocatorOrString/g, 'string | object');
         }
@@ -190,6 +192,8 @@ Our community prepared some valuable recipes for setting up CI systems with Code
         for (const i in placeholders) {
           cfg.replace(placeholders[i], templates[i]);
         }
+        cfg.replace(/CodeceptJS.LocatorOrString\?/g, '(string | object)?');
+        cfg.replace(/LocatorOrString\?/g, '(string | object)?');
         cfg.replace(/CodeceptJS.LocatorOrString/g, 'string | object');
         cfg.replace(/LocatorOrString/g, 'string | object');
       });