feat: blur and focus for other helpers (#3737)

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.

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.

lib/helper/Playwright.js

@@ -908,17 +908,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 +921,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 = {}) {

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 }}
    */

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 });

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

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
+    }
+  }
+};

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
+    }
+  }
+};

test/helper/Playwright_test.js

@@ -184,43 +184,6 @@ describe('Playwright', function () {
       .then(() => I.dontSee('Hovered', '#show')));
   });
 
-  describe('#focus, #blur', () => {
-    it('should focus a button, field and textarea', async () => {
-      await I.amOnPage('/form/focus_blur_elements');
-
-      await I.focus('#button');
-      await I.see('Button is focused', '#buttonMessage');
-
-      await I.focus('#field');
-      await I.see('Button not focused', '#buttonMessage');
-      await I.see('Input field is focused', '#fieldMessage');
-
-      await I.focus('#textarea');
-      await I.see('Button not focused', '#buttonMessage');
-      await I.see('Input field not focused', '#fieldMessage');
-      await I.see('Textarea is focused', '#textareaMessage');
-    });
-
-    it('should blur focused button, field and textarea', async () => {
-      await I.amOnPage('/form/focus_blur_elements');
-
-      await I.focus('#button');
-      await I.see('Button is focused', '#buttonMessage');
-      await I.blur('#button');
-      await I.see('Button not focused', '#buttonMessage');
-
-      await I.focus('#field');
-      await I.see('Input field is focused', '#fieldMessage');
-      await I.blur('#field');
-      await I.see('Input field not focused', '#fieldMessage');
-
-      await I.focus('#textarea');
-      await I.see('Textarea is focused', '#textareaMessage');
-      await I.blur('#textarea');
-      await I.see('Textarea not focused', '#textareaMessage');
-    });
-  });
-
   describe('#switchToNextTab, #switchToPreviousTab, #openNewTab, #closeCurrentTab, #closeOtherTabs, #grabNumberOfOpenTabs', () => {
     it('should only have 1 tab open when the browser starts and navigates to the first page', () => I.amOnPage('/')
       .then(() => I.wait(1))

test/helper/webapi.js

@@ -1491,4 +1491,43 @@ module.exports.tests = function () {
       await I.see('Step Two Button');
     });
   });
+
+  describe('#focus, #blur', () => {
+    it('should focus a button, field and textarea', async () => {
+      if (isHelper('Nightmare')) return;
+      await I.amOnPage('/form/focus_blur_elements');
+
+      await I.focus('#button');
+      await I.see('Button is focused', '#buttonMessage');
+
+      await I.focus('#field');
+      await I.see('Button not focused', '#buttonMessage');
+      await I.see('Input field is focused', '#fieldMessage');
+
+      await I.focus('#textarea');
+      await I.see('Button not focused', '#buttonMessage');
+      await I.see('Input field not focused', '#fieldMessage');
+      await I.see('Textarea is focused', '#textareaMessage');
+    });
+
+    it('should blur focused button, field and textarea', async () => {
+      if (isHelper('Nightmare')) return;
+      await I.amOnPage('/form/focus_blur_elements');
+
+      await I.focus('#button');
+      await I.see('Button is focused', '#buttonMessage');
+      await I.blur('#button');
+      await I.see('Button not focused', '#buttonMessage');
+
+      await I.focus('#field');
+      await I.see('Input field is focused', '#fieldMessage');
+      await I.blur('#field');
+      await I.see('Input field not focused', '#fieldMessage');
+
+      await I.focus('#textarea');
+      await I.see('Textarea is focused', '#textareaMessage');
+      await I.blur('#textarea');
+      await I.see('Textarea not focused', '#textareaMessage');
+    });
+  });
 };

typings/tests/helpers/WebDriverIO.types.ts

@@ -8,6 +8,42 @@ const num = 1;
 wd.amOnPage(); // $ExpectError
 wd.amOnPage(''); // $ExpectType void
 
+wd.focus(); // $ExpectError
+wd.focus('div'); // $ExpectType void
+wd.focus({ css: 'div' });
+wd.focus({ xpath: '//div' });
+wd.focus({ name: 'div' });
+wd.focus({ id: 'div' });
+wd.focus({ android: 'div' });
+wd.focus({ ios: 'div' });
+wd.focus(locate('div'));
+wd.focus('div', 'body');
+wd.focus('div', locate('div'));
+wd.focus('div', { css: 'div' });
+wd.focus('div', { xpath: '//div' });
+wd.focus('div', { name: '//div' });
+wd.focus('div', { id: '//div' });
+wd.focus('div', { android: '//div' });
+wd.focus('div', { ios: '//div' });
+
+wd.blur(); // $ExpectError
+wd.blur('div'); // $ExpectType void
+wd.blur({ css: 'div' });
+wd.blur({ xpath: '//div' });
+wd.blur({ name: 'div' });
+wd.blur({ id: 'div' });
+wd.blur({ android: 'div' });
+wd.blur({ ios: 'div' });
+wd.blur(locate('div'));
+wd.blur('div', 'body');
+wd.blur('div', locate('div'));
+wd.blur('div', { css: 'div' });
+wd.blur('div', { xpath: '//div' });
+wd.blur('div', { name: '//div' });
+wd.blur('div', { id: '//div' });
+wd.blur('div', { android: '//div' });
+wd.blur('div', { ios: '//div' });
+
 wd.click(); // $ExpectError
 wd.click('div'); // $ExpectType void
 wd.click({ css: 'div' });