feat: expose WebElement (#4043)

Author: kobenguyent

docs/helpers/Playwright.md

@@ -1389,6 +1389,36 @@ let inputs = await I.grabValueFromAll('//form/input');
 
 Returns **[Promise][22]<[Array][10]<[string][9]>>** attribute value
 
+### grabWebElement
+
+Grab WebElement for given locator
+Resumes test execution, so **should be used inside an async function with `await`** operator.
+
+```js
+const webElement = await I.grabWebElement('#button');
+```
+
+#### Parameters
+
+-   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
+
+Returns **[Promise][22]<any>** WebElement of being used Web helper
+
+### grabWebElements
+
+Grab WebElements for given locator
+Resumes test execution, so **should be used inside an async function with `await`** operator.
+
+```js
+const webElements = await I.grabWebElements('#button');
+```
+
+#### Parameters
+
+-   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
+
+Returns **[Promise][22]<any>** WebElement of being used Web helper
+
 ### grabWebSocketMessages
 
 Grab the recording WS messages

docs/helpers/Puppeteer.md

@@ -1216,6 +1216,21 @@ let inputs = await I.grabValueFromAll('//form/input');
 
 Returns **[Promise][13]<[Array][15]<[string][6]>>** attribute value
 
+### grabWebElements
+
+Grab WebElements for given locator
+Resumes test execution, so **should be used inside an async function with `await`** operator.
+
+```js
+const webElements = await I.grabWebElements('#button');
+```
+
+#### Parameters
+
+-   `locator` **([string][6] | [object][4])** element located by CSS|XPath|strict locator.
+
+Returns **[Promise][13]<any>** WebElement of being used Web helper
+
 ### handleDownloads
 
 Sets a directory to where save files. Allows to test file downloads.

docs/helpers/WebDriver.md

@@ -1367,6 +1367,21 @@ let inputs = await I.grabValueFromAll('//form/input');
 
 Returns **[Promise][25]<[Array][28]<[string][17]>>** attribute value
 
+### grabWebElements
+
+Grab WebElements for given locator
+Resumes test execution, so **should be used inside an async function with `await`** operator.
+
+```js
+const webElements = await I.grabWebElements('#button');
+```
+
+#### Parameters
+
+-   `locator` **([string][17] | [object][16])** element located by CSS|XPath|strict locator.
+
+Returns **[Promise][25]<any>** WebElement of being used Web helper
+
 ### moveCursorTo
 
 Moves cursor to element matched by locator.

docs/webapi/grabWebElement.mustache

@@ -0,0 +1,9 @@
+Grab WebElement for given locator
+Resumes test execution, so **should be used inside an async function with `await`** operator.
+
+```js
+const webElement = await I.grabWebElement('#button');
+```
+
+@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+@returns {Promise<*>} WebElement of being used Web helper

docs/webapi/grabWebElements.mustache

@@ -0,0 +1,9 @@
+Grab WebElements for given locator
+Resumes test execution, so **should be used inside an async function with `await`** operator.
+
+```js
+const webElements = await I.grabWebElements('#button');
+```
+
+@param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+@returns {Promise<*>} WebElement of being used Web helper

lib/helper/Playwright.js

@@ -1304,6 +1304,22 @@ class Playwright extends Helper {
     return findFields.call(this, locator);
   }
 
+  /**
+   * {{> grabWebElements }}
+   *
+   */
+  async grabWebElements(locator) {
+    return this._locate(locator);
+  }
+
+  /**
+   * {{> grabWebElement }}
+   *
+   */
+  async grabWebElement(locator) {
+    return this._locateElement(locator);
+  }
+
   /**
    * Switch focus to a particular tab by its number. It waits tabs loading and then switch tab
    *

lib/helper/Puppeteer.js

@@ -917,6 +917,14 @@ class Puppeteer extends Helper {
     return findFields.call(this, locator);
   }
 
+  /**
+   * {{> grabWebElements }}
+   *
+   */
+  async grabWebElements(locator) {
+    return this._locate(locator);
+  }
+
   /**
    * Switch focus to a particular tab by its number. It waits tabs loading and then switch tab
    *

lib/helper/WebDriver.js

@@ -869,6 +869,14 @@ class WebDriver extends Helper {
     return findFields.call(this, locator).then(res => res);
   }
 
+  /**
+   * {{> grabWebElements }}
+   *
+   */
+  async grabWebElements(locator) {
+    return this._locate(locator);
+  }
+
   /**
    * Set [WebDriver timeouts](https://webdriver.io/docs/timeouts.html) in realtime.
    *

test/helper/Playwright_test.js

@@ -1,4 +1,4 @@
-const assert = require('assert');
+const { assert } = require('chai');
 const expect = require('chai').expect;
 const path = require('path');
 const fs = require('fs');
@@ -1638,4 +1638,21 @@ describe('Playwright - HAR', () => {
     await I.amOnPage('https://demo.playwright.dev/api-mocking');
     await I.see('CodeceptJS');
   });
+
+  describe('#grabWebElements, #grabWebElement', () => {
+    it('should return an array of WebElement', async () => {
+      await I.amOnPage('/form/focus_blur_elements');
+
+      const webElements = await I.grabWebElements('#button');
+      assert.equal(webElements[0], 'locator(\'#button\').first()');
+      assert.isAbove(webElements.length, 0);
+    });
+
+    it('should return a WebElement', async () => {
+      await I.amOnPage('/form/focus_blur_elements');
+
+      const webElement = await I.grabWebElement('#button');
+      assert.equal(webElement, 'locator(\'#button\').first()');
+    });
+  });
 });

test/helper/Puppeteer_test.js

@@ -1,4 +1,4 @@
-const assert = require('assert');
+const { assert } = require('chai');
 const expect = require('chai').expect;
 const path = require('path');
 
@@ -1083,4 +1083,14 @@ describe('Puppeteer - Trace', () => {
     assert.ok(fs.existsSync(test.artifacts.trace));
     expect(test.artifacts.trace).to.include(path.join(global.output_dir, 'trace'));
   });
+
+  describe('#grabWebElements', () => {
+    it('should return an array of WebElement', async () => {
+      await I.amOnPage('/form/focus_blur_elements');
+
+      const webElements = await I.grabWebElements('#button');
+      assert.include(webElements[0].constructor.name, 'CDPElementHandle');
+      assert.isAbove(webElements.length, 0);
+    });
+  });
 });