codeceptjs 3.5.0 → 3.5.2

package/docs/plugins.md

@@ -612,7 +612,7 @@ Self-healing tests with OpenAI.
 
 This plugin is experimental and requires OpenAI API key.
 
-To use it you need to set OPENAI_API_KEY env variable and enable plugin inside condig.
+To use it you need to set OPENAI_API_KEY env variable and enable plugin inside the config.
 
 ```js
 plugins: {

package/docs/webapi/blur.mustache

@@ -0,0 +1,17 @@
+Remove focus from a text input, button, etc.
+Calls [blur](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
+
+Examples:
+
+```js
+I.blur('.text-area')
+```
+```js
+//element `#product-tile` is focused
+I.see('#add-to-cart-btn');
+I.blur('#product-tile')
+I.dontSee('#add-to-cart-btn');
+```
+
+@param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
+@param {any} [options] Playwright only: [Additional options](https://playwright.dev/docs/api/class-locator#locator-blur) for available options object as 2nd argument.

package/docs/webapi/focus.mustache

@@ -0,0 +1,12 @@
+Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the matching element.
+
+Examples:
+
+```js
+I.dontSee('#add-to-cart-btn');
+I.focus('#product-tile')
+I.see('#add-to-cart-bnt');
+```
+
+@param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
+@param {any} [options] Playwright only: [Additional options](https://playwright.dev/docs/api/class-locator#locator-focus) for available options object as 2nd argument.

package/lib/cli.js

@@ -81,6 +81,11 @@ class Cli extends Base {
       if (!codeceptjsEventDispatchersRegistered) {
         codeceptjsEventDispatchersRegistered = true;
 
+        event.dispatcher.on(event.bddStep.started, (step) => {
+          output.stepShift = 2;
+          output.step(step);
+        });
+
         event.dispatcher.on(event.step.started, (step) => {
           let processingStep = step;
           const metaSteps = [];
@@ -93,7 +98,10 @@ class Cli extends Base {
           for (let i = 0; i < Math.max(currentMetaStep.length, metaSteps.length); i++) {
             if (currentMetaStep[i] !== metaSteps[i]) {
               output.stepShift = 3 + 2 * i;
-              if (metaSteps[i]) output.step(metaSteps[i]);
+              if (!metaSteps[i]) continue;
+              // bdd steps are handled by bddStep.started
+              if (metaSteps[i].isBDD()) continue;
+              output.step(metaSteps[i]);
             }
           }
           currentMetaStep = metaSteps;

package/lib/command/init.js

@@ -317,6 +317,16 @@ module.exports = function (initPath) {
 
     print('Configure helpers...');
     inquirer.prompt(helperConfigs).then((helperResult) => {
+      if (helperResult.Playwright_browser === 'electron') {
+        delete helperResult.Playwright_url;
+        delete helperResult.Playwright_show;
+
+        helperResult.Playwright_electron = {
+          executablePath: '// require("electron") or require("electron-forge")',
+          args: ['path/to/your/main.js'],
+        };
+      }
+
       Object.keys(helperResult).forEach((key) => {
         const parts = key.split('_');
         const helperName = parts[0];

package/lib/event.js

@@ -91,6 +91,8 @@ module.exports = {
   bddStep: {
     before: 'bddStep.before',
     after: 'bddStep.after',
+    started: 'bddStep.started',
+    finished: 'bddStep.finished',
   },
   /**
    * @type {object}

package/lib/helper/OpenAI.js

@@ -25,7 +25,9 @@ class OpenAI extends Helper {
       chunkSize: 80000,
     };
     this.options = { ...this.options, ...config };
+  }
 
+  _beforeSuite() {
     const helpers = Container.helpers();
 
     for (const helperName of standardActingHelpers) {
@@ -37,16 +39,16 @@ class OpenAI extends Helper {
   }
 
   /**
- * Asks the OpenAI GPT language model a question based on the provided prompt within the context of the current page's HTML.
- *
- * ```js
- * I.askGptOnPage('what does this page do?');
- * ```
- *
- * @async
- * @param {string} prompt - The question or prompt to ask the GPT model.
- * @returns {Promise<string>} - A Promise that resolves to the generated responses from the GPT model, joined by newlines.
- */
+   * Asks the OpenAI GPT language model a question based on the provided prompt within the context of the current page's HTML.
+   *
+   * ```js
+   * I.askGptOnPage('what does this page do?');
+   * ```
+   *
+   * @async
+   * @param {string} prompt - The question or prompt to ask the GPT model.
+   * @returns {Promise<string>} - A Promise that resolves to the generated responses from the GPT model, joined by newlines.
+   */
   async askGptOnPage(prompt) {
     const html = await this.helper.grabSource();
 
@@ -120,3 +122,5 @@ class OpenAI extends Helper {
     return response;
   }
 }
+
+module.exports = OpenAI;

package/lib/helper/Playwright.js

@@ -52,13 +52,13 @@ const pathSeparator = path.sep;
 /**
  * ## Configuration
  *
- * This helper should be configured in codecept.conf.js
+ * This helper should be configured in codecept.conf.(js|ts)
  *
  * @typedef PlaywrightConfig
  * @type {object}
- * @prop {string} url - base url of website to be tested
+ * @prop {string} [url] - base url of website to be tested
  * @prop {'chromium' | 'firefox'| 'webkit' | 'electron'} [browser='chromium'] - a browser to test on, either: `chromium`, `firefox`, `webkit`, `electron`. Default: chromium.
- * @prop {boolean} [show=false] - show browser window.
+ * @prop {boolean} [show=true] - show browser window.
  * @prop {string|boolean} [restart=false] - restart strategy between tests. Possible values:
  *   * 'context' or **false** - restarts [browser context](https://playwright.dev/docs/api/class-browsercontext) but keeps running browser. Recommended by Playwright team to keep tests isolated.
  *   * 'browser' or **true** - closes browser and opens it again between tests.
@@ -260,6 +260,22 @@ const config = {};
  * }
  * ```
  *
+ * * #### Example #9: Launch electron test
+ *
+ * ```js
+ * {
+ *  helpers: {
+ *     Playwright: {
+ *       browser: 'electron',
+ *       electron: {
+ *         executablePath: require("electron"),
+ *         args: [path.join('../', "main.js")],
+ *       },
+ *     }
+ *   },
+ * }
+ * ```
+ *
  * Note: When connecting to remote browser `show` and specific `chrome` options (e.g. `headless` or `devtools`) are ignored.
  *
  * ## Access From Helpers
@@ -373,15 +389,24 @@ class Playwright extends Helper {
 
   static _config() {
     return [
-      { name: 'url', message: 'Base url of site to be tested', default: 'http://localhost' },
-      {
-        name: 'show', message: 'Show browser window', default: true, type: 'confirm',
-      },
       {
         name: 'browser',
         message: 'Browser in which testing will be performed. Possible options: chromium, firefox, webkit or electron',
         default: 'chromium',
       },
+      {
+        name: 'url',
+        message: 'Base url of site to be tested',
+        default: 'http://localhost',
+        when: (answers) => answers.Playwright_browser !== 'electron',
+      },
+      {
+        name: 'show',
+        message: 'Show browser window',
+        default: true,
+        type: 'confirm',
+        when: (answers) => answers.Playwright_browser !== 'electron',
+      },
     ];
   }
 
@@ -908,17 +933,7 @@ class Playwright extends Helper {
   }
 
   /**
-   * Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the matching element.
-   * @param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
-   * @param {any} [options] [Additional options](https://playwright.dev/docs/api/class-locator#locator-focus) for available options object as 2nd argument.
-   *
-   * Examples:
-   *
-   * ```js
-   * I.dontSee('#add-to-cart-btn');
-   * I.focus('#product-tile')
-   * I.see('#add-to-cart-bnt');
-   * ```
+   * {{> focus }}
    *
    */
   async focus(locator, options = {}) {
@@ -931,22 +946,7 @@ class Playwright extends Helper {
   }
 
   /**
-   * Remove focus from a text input, button, etc
-   * Calls [blur](https://playwright.dev/docs/api/class-locator#locator-blur) on the element.
-   * @param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
-   * @param {any} [options] [Additional options](https://playwright.dev/docs/api/class-locator#locator-blur) for available options object as 2nd argument.
-   *
-   * Examples:
-   *
-   * ```js
-   * I.blur('.text-area')
-   * ```
-   * ```js
-   * //element `#product-tile` is focused
-   * I.see('#add-to-cart-btn');
-   * I.blur('#product-tile')
-   * I.dontSee('#add-to-cart-btn');
-   * ```
+   * {{> blur }}
    *
    */
   async blur(locator, options = {}) {
@@ -1542,22 +1542,25 @@ class Playwright extends Helper {
   }
 
   /**
-   * Clear the <input>, <textarea> or [contenteditable] .
+   * Clears the text input element: `<input>`, `<textarea>` or `[contenteditable]` .
+   *
+  *
+  * Examples:
+  *
+  * ```js
+  * I.clearField('.text-area')
+  *
+  * // if this doesn't work use force option
+  * I.clearField('#submit', { force: true })
+  * ```
+  * Use `force` to bypass the [actionability](https://playwright.dev/docs/actionability) checks.
+  *
    * @param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
    * @param {any} [options] [Additional options](https://playwright.dev/docs/api/class-locator#locator-clear) for available options object as 2nd argument.
-   *
-   * Examples:
-   *
-   * ```js
-   * I.clearField('.text-area')
-   * ```
-   * ```js
-   * I.clearField('#submit', { force: true }) // force to bypass the [actionability](https://playwright.dev/docs/actionability) checks.
-   * ```
    */
   async clearField(locator, options = {}) {
     let result;
-    const isNewClearMethodPresent = typeof this.page.locator().clear === 'function';
+    const isNewClearMethodPresent = false; // not works, disabled for now. Prev: typeof this.page.locator().clear === 'function';
 
     if (isNewClearMethodPresent) {
       const els = await findFields.call(this, locator);

package/lib/helper/Puppeteer.js

@@ -35,6 +35,8 @@ const Popup = require('./extras/Popup');
 const Console = require('./extras/Console');
 const findReact = require('./extras/React');
 const { highlightElement } = require('./scripts/highlightElement');
+const { blurElement } = require('./scripts/blurElement');
+const { focusElement } = require('./scripts/focusElement');
 
 let puppeteer;
 let perfTiming;
@@ -707,6 +709,31 @@ class Puppeteer extends Helper {
     return this._waitForAction();
   }
 
+  /**
+   * {{> focus }}
+   *
+   */
+  async focus(locator) {
+    const els = await this._locate(locator);
+    assertElementExists(els, locator, 'Element to focus');
+    const el = els[0];
+
+    await focusElement(el, this.page);
+    return this._waitForAction();
+  }
+
+  /**
+   * {{> blur }}
+   *
+   */
+  async blur(locator) {
+    const els = await this._locate(locator);
+    assertElementExists(els, locator, 'Element to blur');
+
+    await blurElement(els[0], this.page);
+    return this._waitForAction();
+  }
+
   /**
    * {{> dragAndDrop }}
    */

package/lib/helper/TestCafe.js

@@ -346,6 +346,34 @@ class TestCafe extends Helper {
     return this.t.resizeWindow(width, height).catch(mapError);
   }
 
+  /**
+   * {{> focus }}
+   *
+   */
+  async focus(locator) {
+    const els = await this._locate(locator);
+    await assertElementExists(els, locator, 'Element to focus');
+    const element = await els.nth(0);
+
+    const focusElement = ClientFunction(() => element().focus(), { boundTestRun: this.t, dependencies: { element } });
+
+    return focusElement();
+  }
+
+  /**
+   * {{> blur }}
+   *
+   */
+  async blur(locator) {
+    const els = await this._locate(locator);
+    await assertElementExists(els, locator, 'Element to blur');
+    const element = await els.nth(0);
+
+    const blurElement = ClientFunction(() => element().blur(), { boundTestRun: this.t, dependencies: { element } });
+
+    return blurElement();
+  }
+
   /**
    * {{> click }}
    *
@@ -792,7 +820,7 @@ class TestCafe extends Helper {
   /**
    * {{> executeScript }}
    *
-   * If a function returns a Promise It will wait for it resolution.
+   * If a function returns a Promise It will wait for its resolution.
    */
   async executeScript(fn, ...args) {
     const browserFn = createClientFunction(fn, args).with({ boundTestRun: this.t });

package/lib/helper/WebDriver.js

@@ -30,6 +30,8 @@ const ConnectionRefused = require('./errors/ConnectionRefused');
 const Locator = require('../locator');
 const { highlightElement } = require('./scripts/highlightElement');
 const store = require('../store');
+const { focusElement } = require('./scripts/focusElement');
+const { blurElement } = require('./scripts/blurElement');
 
 const SHADOW = 'shadow';
 const webRoot = 'body';
@@ -1934,6 +1936,30 @@ class WebDriver extends Helper {
     }
   }
 
+  /**
+   * {{> focus }}
+   *
+   */
+  async focus(locator) {
+    const els = await this._locate(locator);
+    assertElementExists(els, locator, 'Element to focus');
+    const el = usingFirstElement(els);
+
+    await focusElement(el, this.browser);
+  }
+
+  /**
+   * {{> blur }}
+   *
+   */
+  async blur(locator) {
+    const els = await this._locate(locator);
+    assertElementExists(els, locator, 'Element to blur');
+    const el = usingFirstElement(els);
+
+    await blurElement(el, this.browser);
+  }
+
   /**
    * {{> dragAndDrop }}
    * Appium: not tested

package/lib/helper/scripts/blurElement.js

@@ -0,0 +1,17 @@
+module.exports.blurElement = (element, context) => {
+  const clientSideBlurFn = el => {
+    el.blur();
+  };
+
+  try {
+    // Puppeteer
+    context.evaluate(clientSideBlurFn, element);
+  } catch (e) {
+    // WebDriver
+    try {
+      context.execute(clientSideBlurFn, element);
+    } catch (err) {
+      // ignore
+    }
+  }
+};

package/lib/helper/scripts/focusElement.js

@@ -0,0 +1,17 @@
+module.exports.focusElement = (element, context) => {
+  const clientSideFn = el => {
+    el.focus();
+  };
+
+  try {
+    // Puppeteer
+    context.evaluate(clientSideFn, element);
+  } catch (e) {
+    // WebDriver
+    try {
+      context.execute(clientSideFn, element);
+    } catch (err) {
+      // ignore
+    }
+  }
+};

package/lib/interfaces/gherkin.js

@@ -1,6 +1,7 @@
 const Gherkin = require('@cucumber/gherkin');
 const Messages = require('@cucumber/messages');
 const { Context, Suite, Test } = require('mocha');
+const debug = require('debug')('codeceptjs:bdd');
 
 const { matchStep } = require('./bdd');
 const event = require('../event');
@@ -39,7 +40,9 @@ module.exports = (text, file) => {
     for (const step of steps) {
       const metaStep = new Step.MetaStep(null, step.text);
       metaStep.actor = step.keyword.trim();
+      let helperStep;
       const setMetaStep = (step) => {
+        helperStep = step;
         if (step.metaStep) {
           if (step.metaStep === metaStep) {
             return;
@@ -67,11 +70,15 @@ module.exports = (text, file) => {
       step.startTime = Date.now();
       step.match = fn.line;
       event.emit(event.bddStep.before, step);
+      event.emit(event.bddStep.started, metaStep);
       event.dispatcher.prependListener(event.step.before, setMetaStep);
       try {
+        debug(`Step '${step.text}' started...`);
         await fn(...fn.params);
+        debug('Step passed');
         step.status = 'passed';
       } catch (err) {
+        debug(`Step failed: ${err?.message}`);
         step.status = 'failed';
         step.err = err;
         throw err;
@@ -79,6 +86,7 @@ module.exports = (text, file) => {
         step.endTime = Date.now();
         event.dispatcher.removeListener(event.step.before, setMetaStep);
       }
+      event.emit(event.bddStep.finished, metaStep);
       event.emit(event.bddStep.after, step);
     }
   };

package/lib/plugin/heal.js

@@ -26,7 +26,7 @@ const defaultConfig = {
  *
  * This plugin is experimental and requires OpenAI API key.
  *
- * To use it you need to set OPENAI_API_KEY env variable and enable plugin inside condig.
+ * To use it you need to set OPENAI_API_KEY env variable and enable plugin inside the config.
  *
  * ```js
  * plugins: {
@@ -82,7 +82,7 @@ module.exports = function (config = {}) {
       const test = currentTest;
 
       if (healedSteps >= config.healLimit) {
-        output.print(colors.bold.red(`Can't heal more than ${config.healLimit} steps in a test`));
+        output.print(colors.bold.red(`Can't heal more than ${config.healLimit} step(s) in a test`));
         output.print('Entire flow can be broken, please check it manually');
         output.print('or increase healing limit in heal plugin config');
 
@@ -126,7 +126,7 @@ module.exports = function (config = {}) {
     print('===================');
     print(colors.bold.green('Self-Healing Report:'));
 
-    print(`${colors.bold(healSuggestions.length)} steps were healed by AI`);
+    print(`${colors.bold(healSuggestions.length)} step(s) were healed by AI`);
 
     let i = 1;
     print('');
@@ -145,15 +145,13 @@ module.exports = function (config = {}) {
   });
 
   async function tryToHeal(failedStep, err) {
-    output.debug(`Running OpenAPI to heal ${failedStep.toCode()} step`);
-
-    const I = Container.support('I');
+    output.debug(`Running OpenAI to heal ${failedStep.toCode()} step`);
 
     const codeSnippets = await aiAssistant.healFailedStep(
       failedStep, err, currentTest,
     );
 
-    output.debug(`Received ${codeSnippets.length} proposals from OpenAI`);
+    output.debug(`Received ${codeSnippets.length} suggestions from OpenAI`);
 
     for (const codeSnippet of codeSnippets) {
       try {

package/lib/recorder.js

@@ -1,6 +1,6 @@
 const debug = require('debug')('codeceptjs:recorder');
 const promiseRetry = require('promise-retry');
-
+const { printObjectProperties } = require('./utils');
 const { log } = require('./output');
 
 const MAX_TASKS = 100;
@@ -41,6 +41,7 @@ module.exports = {
    * @inner
    */
   start() {
+    debug('Starting recording promises');
     running = true;
     asyncErr = null;
     errFn = null;
@@ -175,7 +176,7 @@ module.exports = {
       return;
     }
     tasks.push(taskName);
-    if (process.env.DEBUG) debug(`${currentQueue()}Queued | ${taskName}`);
+    debug(`${currentQueue()}Queued | ${taskName}`);
 
     return promise = Promise.resolve(promise).then((res) => {
       // prefer options for non-conditional retries
@@ -224,10 +225,11 @@ module.exports = {
    * @inner
    */
   catch(customErrFn) {
+    debug(`${currentQueue()}Queued | catch with error handler`);
     return promise = promise.catch((err) => {
       log(`${currentQueue()}Error | ${err}`);
       if (!(err instanceof Error)) { // strange things may happen
-        err = new Error(`[Wrapped Error] ${JSON.stringify(err)}`); // we should be prepared for them
+        err = new Error(`[Wrapped Error] ${printObjectProperties(err)}`); // we should be prepared for them
       }
       if (customErrFn) {
         customErrFn(err);
@@ -264,8 +266,9 @@ module.exports = {
    * @param {*} err
    * @inner
    */
+
   throw(err) {
-    return this.add(`throw error ${err}`, () => {
+    return this.add(`throw error: ${err.message}`, () => {
       throw err;
     });
   },

package/lib/utils.js

@@ -459,3 +459,16 @@ module.exports.isNotSet = function (obj) {
 module.exports.emptyFolder = async (directoryPath) => {
   require('child_process').execSync(`rm -rf ${directoryPath}/*`);
 };
+
+module.exports.printObjectProperties = (obj) => {
+  if (typeof obj !== 'object' || obj === null) {
+    return obj;
+  }
+
+  let result = '';
+  for (const [key, value] of Object.entries(obj)) {
+    result += `${key}: "${value}"; `;
+  }
+
+  return `{${result}}`;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeceptjs",
-  "version": "3.5.0",
+  "version": "3.5.2",
   "description": "Supercharged End 2 End Testing Framework for NodeJS",
   "keywords": [
     "acceptance",
@@ -65,7 +65,7 @@
     "@cucumber/gherkin": "^26",
     "@cucumber/messages": "^21.0.1",
     "@xmldom/xmldom": "^0.7.9",
-    "acorn": "^7.4.1",
+    "acorn": "^8.10.0",
     "arrify": "^2.0.1",
     "axios": "^1.3.3",
     "chai": "^4.3.6",
@@ -75,13 +75,12 @@
     "cross-spawn": "^7.0.3",
     "css-to-xpath": "^0.1.0",
     "envinfo": "^7.8.1",
-    "escape-string-regexp": "^1.0.3",
+    "escape-string-regexp": "^4.0.0",
     "figures": "^3.2.0",
     "fn-args": "^4.0.0",
     "fs-extra": "^8.1.0",
     "glob": "^6.0.1",
     "html-minifier": "^4.0.0",
-    "i": "^0.3.7",
     "inquirer": "^6.5.2",
     "joi": "^17.6.0",
     "js-beautify": "^1.14.0",
@@ -89,9 +88,7 @@
     "lodash.merge": "^4.6.2",
     "mkdirp": "^1.0.4",
     "mocha": "^10.2.0",
-    "mocha-junit-reporter": "^1.23.3",
     "ms": "^2.1.3",
-    "npm": "^9.6.7",
     "openai": "^3.2.1",
     "ora-classic": "^5.4.2",
     "parse-function": "^5.6.4",
@@ -118,9 +115,9 @@
     "contributor-faces": "^1.0.3",
     "documentation": "^12.3.0",
     "dtslint": "^4.1.6",
-    "electron": "^12.2.3",
+    "electron": "^25.2.0",
     "eslint": "^6.8.0",
-    "eslint-config-airbnb-base": "^14.2.1",
+    "eslint-config-airbnb-base": "^15.0.0",
     "eslint-plugin-import": "^2.25.4",
     "eslint-plugin-mocha": "^6.3.0",
     "expect": "^26.6.2",
@@ -149,8 +146,8 @@
     "typescript": "^4.8.4",
     "wdio-docker-service": "^1.5.0",
     "webdriverio": "^8.3.8",
-    "xml2js": "^0.4.23",
-    "xmldom": "^0.5.0",
+    "xml2js": "^0.6.0",
+    "xmldom": "^0.6.0",
     "xpath": "0.0.27"
   },
   "engines": {