codeceptjs 3.5.0 → 3.5.1

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 3.5.1
+
+🛩️ Features
+
+* [Puppeteer][WebDriver][TestCafe] Added methods by @KobeNguyenT in #3737 
+  * `blur`
+  * `focus`
+* Improved BDD output to print steps without `I.` commands` by @davertmik #3739
+* Improved `codecept init` setup for Electron tests by @KobeNguyenT. See #3733
+
+🐛 Bug Fixes
+
+* Fixed serializing of custom errors making tests stuck. Fix #3739 by @davertmik.
+
+📖 Documentation
+
+* Fixed Playwright docs by @Horsty80
+* Fixed ai docs by @ngraf 
+* Various fixes by @KobeNguyenT
+
 ## 3.5.0
 
 🛩️ Features

package/README.md

@@ -309,22 +309,22 @@ Thanks all to those who are and will have contributing to this awesome project!
 <a href="https://github.com/nikocanvacom"><img src="https://avatars.githubusercontent.com/u/83254493?v=4" title="nikocanvacom" width="80" height="80"></a>
 <a href="https://github.com/elukoyanov"><img src="https://avatars.githubusercontent.com/u/11647141?v=4" title="elukoyanov" width="80" height="80"></a>
 <a href="https://github.com/gkushang"><img src="https://avatars.githubusercontent.com/u/3663389?v=4" title="gkushang" width="80" height="80"></a>
+<a href="https://github.com/actions-user"><img src="https://avatars.githubusercontent.com/u/65916846?v=4" title="actions-user" width="80" height="80"></a>
 <a href="https://github.com/tsuemura"><img src="https://avatars.githubusercontent.com/u/17092259?v=4" title="tsuemura" width="80" height="80"></a>
 <a href="https://github.com/EgorBodnar"><img src="https://avatars.githubusercontent.com/u/63167966?v=4" title="EgorBodnar" width="80" height="80"></a>
 <a href="https://github.com/VikalpP"><img src="https://avatars.githubusercontent.com/u/11846339?v=4" title="VikalpP" width="80" height="80"></a>
+<a href="https://github.com/apps/dependabot"><img src="https://avatars.githubusercontent.com/in/29110?v=4" title="dependabot[bot]" width="80" height="80"></a>
 <a href="https://github.com/BorisOsipov"><img src="https://avatars.githubusercontent.com/u/6514276?v=4" title="BorisOsipov" width="80" height="80"></a>
 <a href="https://github.com/elaichenkov"><img src="https://avatars.githubusercontent.com/u/29764053?v=4" title="elaichenkov" width="80" height="80"></a>
-<a href="https://github.com/apps/dependabot"><img src="https://avatars.githubusercontent.com/in/29110?v=4" title="dependabot[bot]" width="80" height="80"></a>
 <a href="https://github.com/nitschSB"><img src="https://avatars.githubusercontent.com/u/39341455?v=4" title="nitschSB" width="80" height="80"></a>
 <a href="https://github.com/hubidu"><img src="https://avatars.githubusercontent.com/u/13134082?v=4" title="hubidu" width="80" height="80"></a>
 <a href="https://github.com/jploskonka"><img src="https://avatars.githubusercontent.com/u/669483?v=4" title="jploskonka" width="80" height="80"></a>
+<a href="https://github.com/ngraf"><img src="https://avatars.githubusercontent.com/u/7094389?v=4" title="ngraf" width="80" height="80"></a>
 <a href="https://github.com/maojunxyz"><img src="https://avatars.githubusercontent.com/u/28778042?v=4" title="maojunxyz" width="80" height="80"></a>
 <a href="https://github.com/abhimanyupandian"><img src="https://avatars.githubusercontent.com/u/36107381?v=4" title="abhimanyupandian" width="80" height="80"></a>
 <a href="https://github.com/martomo"><img src="https://avatars.githubusercontent.com/u/1850135?v=4" title="martomo" width="80" height="80"></a>
 <a href="https://github.com/denis-sokolov"><img src="https://avatars.githubusercontent.com/u/113721?v=4" title="denis-sokolov" width="80" height="80"></a>
 <a href="https://github.com/lennym"><img src="https://avatars.githubusercontent.com/u/117398?v=4" title="lennym" width="80" height="80"></a>
-<a href="https://github.com/petehouston"><img src="https://avatars.githubusercontent.com/u/9006720?v=4" title="petehouston" width="80" height="80"></a>
-<a href="https://github.com/jancorvus"><img src="https://avatars.githubusercontent.com/u/67001310?v=4" title="jancorvus" width="80" height="80"></a>
 
 [//]: contributor-faces
 

package/docs/ai.md

@@ -3,6 +3,8 @@ permalink: /ai
 title: Testing with AI 🪄 
 ---
 
+# 🪄 Testing with AI
+
 **CodeceptJS is the first open-source test automation framework with AI** features to improve the testing experience. CodeceptJS uses OpenAI GPT to auto-heal failing tests, assist in writing tests, and more...
 
 Think of it as your testing co-pilot built into the testing framework
@@ -22,7 +24,7 @@ CodeceptJS AI can do the following:
 * 🚑 **self-heal failing tests** (can be used on CI)
 * 💬 send arbitrary prompts to GPT from any tested page attaching its HTML contents
 
-![](/images/fill_form.gif)
+![](/img/fill_form.gif)
 
 ### How it works
 
@@ -32,7 +34,7 @@ GPT models have limits on information passed, and HTML pages can be huge. And so
 
 Even though, the HTML is still quite big and may exceed the token limit. So we recommend using **gpt-3.5-turbo-16k** model, as it accepts 16K tokens (approx. 50K of HTML text), which should be enough for most web pages. It is possible to strictly limit the size of HTML to not exceed GPT tokens limit.
 
-> 👨‍💼 **AI features require sending HTML contents** of tested applications to OpenAI servers for analysis. If you use it in enterprise, ensure that your company requirements match [OpenAI complience](https://openai.com/security).
+> ❗AI features require sending HTML contents to OpenAI. If you use it in enterprise, ensure that your company requirements match [OpenAI complience](https://openai.com/security). If you work on public web applications this should be ok, as HTML code is genrally available to all web application users.
 
 
 ### Getting Started
@@ -88,17 +90,17 @@ When pause mode started you can ask GPT to fill in the fields on this page. Use
  I.fill checkout form with valid values without submitting it
 ```
 
-![](/images/ai_form1.png)
+![](/img/fill_form_1.png)
 
 GPT will generate code and data and CodeceptJS will try to execute its code. If it succeeds, the code will be saved to history and you will be able to copy it to your test.
 
-![](/images/ai_form2.png)
+![](/img/fill_form2.png)
 
 This AI copilot works best with long static forms. In the case of complex and dynamic single-page applications, it may not perform as well, as the form may not be present on HTML page yet. For instance, interacting with calendars or inputs with real-time validations (like credit cards) can not yet be performed by AI.
 
 Please keep in mind that GPT can't react to page changes and operates with static text only. This is why it is not ready yet to write the test completely. However, if you are new to CodeceptJS and automated testing AI copilot may help you write tests more efficiently. 
 
-> 👶 Eable AI copilot for junior test automation engineers. It may help them to get started with CodeceptJS and to write good semantic locators.
+> 👶 Enable AI copilot for junior test automation engineers. It may help them to get started with CodeceptJS and to write good semantic locators.
 
 ### Self-Healing Tests
 
@@ -110,7 +112,7 @@ Heal actions **work only on actions like `click`, `fillField`**, etc, and won't
 
 If Heal plugin successfully fixes the step, it will print a suggested change at the end of execution. Take it as actionable advice and use it to update the codebase. Heal plugin is supposed to be used on CI, and works automatically without human assistance.
 
-To start, enable `heal` plugin in `codecept.conf.js`` or `codecept.conf.ts`:
+To start, enable `heal` plugin in `codecept.conf.js` or `codecept.conf.ts`:
 
 ```js
 plugins: {
@@ -126,7 +128,7 @@ and run tests in AI mode with `OPENAI_API_KEY` provided:
 OPENAI_API_KEY=sk-******** npx codeceptjs run
 ```
 
-![](/images/heal.png)
+![](/img/heal.png)
 
 
 ### Arbitrary GPT Prompts
@@ -153,7 +155,7 @@ Here are some good use cases for this helper:
 const pageDoc = await I.askGptOnPageFragment('Act as technical writer, describe what is this page for', '#container');
 ```
 
-As of now, those use cases are not really applicable to test automation but maybe you can apply them to your testing setup. 
+As of now, those use cases do not apply to test automation but maybe you can apply them to your testing setup. 
 
 ## Configuration
 
@@ -243,4 +245,4 @@ To debug AI features run tests with `DEBUG="codeceptjs:ai"` flag. This will prin
 
 ```
 DEBUG="codeceptjs:ai" OPENAI_API_KEY=sk-******** npx codeceptjs run
-```
+```

package/docs/build/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',
+      },
     ];
   }
 
@@ -945,16 +970,18 @@ 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');
    * ```
+   * 
+   * @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.
+   * 
    *
    */
   async focus(locator, options = {}) {
@@ -967,13 +994,11 @@ 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.
-   *
+   * 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')
    * ```
@@ -983,6 +1008,10 @@ class Playwright extends Helper {
    * 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.
+   * 
    *
    */
   async blur(locator, options = {}) {
@@ -1943,18 +1972,21 @@ 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;

package/docs/build/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;
@@ -743,6 +745,60 @@ class Puppeteer extends Helper {
     return this._waitForAction();
   }
 
+  /**
+   * 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.
+   * 
+   *
+   */
+  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();
+  }
+
+  /**
+   * 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.
+   * 
+   *
+   */
+  async blur(locator) {
+    const els = await this._locate(locator);
+    assertElementExists(els, locator, 'Element to blur');
+
+    await blurElement(els[0], this.page);
+    return this._waitForAction();
+  }
+
   /**
    * Drag an item to a destination element.
    * 

package/docs/build/TestCafe.js

@@ -362,6 +362,63 @@ class TestCafe extends Helper {
     return this.t.resizeWindow(width, height).catch(mapError);
   }
 
+  /**
+   * 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.
+   * 
+   *
+   */
+  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();
+  }
+
+  /**
+   * 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.
+   * 
+   *
+   */
+  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();
+  }
+
   /**
    * Perform a click on a link or a button, given by a locator.
    * If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.
@@ -1214,7 +1271,7 @@ class TestCafe extends Helper {
    * ⚠️ returns a _promise_ which is synchronized internally by recorder
    * 
    *
-   * 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/docs/build/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';
@@ -2764,6 +2766,59 @@ class WebDriver extends Helper {
     }
   }
 
+  /**
+   * 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.
+   * 
+   *
+   */
+  async focus(locator) {
+    const els = await this._locate(locator);
+    assertElementExists(els, locator, 'Element to focus');
+    const el = usingFirstElement(els);
+
+    await focusElement(el, this.browser);
+  }
+
+  /**
+   * 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.
+   * 
+   *
+   */
+  async blur(locator) {
+    const els = await this._locate(locator);
+    assertElementExists(els, locator, 'Element to blur');
+    const el = usingFirstElement(els);
+
+    await blurElement(el, this.browser);
+  }
+
   /**
    * Drag an item to a destination element.
    * 

package/docs/changelog.md

@@ -7,6 +7,26 @@ layout: Section
 
 # Releases
 
+## 3.5.1
+
+🛩️ Features
+
+* [Puppeteer][WebDriver][TestCafe] Added methods by **[KobeNguyenT](https://github.com/KobeNguyenT)** in [#3737](https://github.com/codeceptjs/CodeceptJS/issues/3737) 
+  * `blur`
+  * `focus`
+* Improved BDD output to print steps without `I.` commands` by **[davertmik](https://github.com/davertmik)** [#3739](https://github.com/codeceptjs/CodeceptJS/issues/3739)
+* Improved `codecept init` setup for Electron tests by **[KobeNguyenT](https://github.com/KobeNguyenT)**. See [#3733](https://github.com/codeceptjs/CodeceptJS/issues/3733)
+
+🐛 Bug Fixes
+
+* Fixed serializing of custom errors making tests stuck. Fix [#3739](https://github.com/codeceptjs/CodeceptJS/issues/3739) by **[davertmik](https://github.com/davertmik)**.
+
+📖 Documentation
+
+* Fixed Playwright docs by **[Horsty80](https://github.com/Horsty80)**
+* Fixed ai docs by **[ngraf](https://github.com/ngraf)** 
+* Various fixes by **[KobeNguyenT](https://github.com/KobeNguyenT)**
+
 ## 3.5.0
 
 🛩️ Features