fix(typings): type grabWebElement(s) as CodeceptJS.WebElement (#5786)

docs/webapi/grabWebElement.mustache

@@ -6,4 +6,4 @@ 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
+@returns {Promise<CodeceptJS.WebElement>} WebElement of being used Web helper

docs/webapi/grabWebElements.mustache

@@ -6,4 +6,4 @@ 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
+@returns {Promise<CodeceptJS.WebElement[]>} WebElements of being used Web helper

lib/element/WebElement.js

@@ -29,7 +29,7 @@ class WebElement {
 
   /**
    * Get the native element instance
-   * @returns {ElementHandle|WebElement|ElementHandle} Native element
+   * @returns {any} Native element (Playwright/Puppeteer ElementHandle or WebdriverIO element)
    */
   getNativeElement() {
     return this.element
@@ -220,7 +220,7 @@ class WebElement {
 
   /**
    * Click the element
-   * @param {Object} options Click options
+   * @param {Object} [options] Click options
    * @returns {Promise<void>}
    */
   async click(options = {}) {
@@ -239,7 +239,7 @@ class WebElement {
   /**
    * Type text into the element
    * @param {string} text Text to type
-   * @param {Object} options Type options
+   * @param {Object} [options] Type options
    * @returns {Promise<void>}
    */
   async type(text, options = {}) {
@@ -362,7 +362,7 @@ class WebElement {
    * Treat this element as an iframe; invoke `fn` with a WebElement wrapping
    * the iframe body. For WebDriver this switches the browser into the frame
    * for the duration of the callback and switches back on exit.
-   * @param {(body: WebElement) => Promise<any>} fn
+   * @param {function(WebElement): Promise<any>} fn
    * @returns {Promise<any>} Return value of fn
    */
   async inIframe(fn) {
@@ -530,7 +530,7 @@ class WebElement {
    * @param {object}   [opts]
    * @param {number}   [opts.maxHtmlLength=300]   passed through to toSimplifiedHTML
    * @param {string[]} [opts.attrs]               attribute names to surface
-   * @returns {Promise<{text?: string, html?: string, visible?: boolean, enabled?: boolean, attrs?: object}>}
+   * @returns {Promise<{text: (string|undefined), html: (string|undefined), visible: (boolean|undefined), enabled: (boolean|undefined), attrs: (Object|undefined)}>}
    */
   async describe({ maxHtmlLength = 300, attrs = ['id', 'class', 'name', 'role', 'type', 'href', 'value', 'aria-label', 'placeholder', 'data-testid'] } = {}) {
     const out = {}

lib/helper/Puppeteer.js

@@ -1097,12 +1097,6 @@ class Puppeteer extends Helper {
     return new WebElement(elements[0], this)
   }
 
-  async grabWebElement(locator) {
-    const els = await this._locate(locator)
-    assertElementExists(els, locator)
-    return els[0]
-  }
-
   /**
    * Switch focus to a particular tab by its number. It waits tabs loading and then switch tab
    *

test/helper/webapi.js

@@ -2738,7 +2738,7 @@ export function tests() {
       // Test grabbing specific element
       if (!isHelper('WebDriver')) {
         const submitButton = await I.grabWebElement({ role: 'button', text: 'Submit' })
-        assert.ok(submitButton)
+        assert.match(await submitButton.toOuterHTML(), /id="submitBtn"/)
       }
 
       // Test grabbing text from role elements

typings/jsdoc.conf.json

@@ -10,6 +10,7 @@
       "./lib/data/table.js",
       "./lib/data/dataTableArgument.js",
       "./lib/effects.js",
+      "./lib/element/WebElement.js",
       "./lib/event.js",
       "./lib/index.js",
       "./lib/locator.js",

typings/tests/helpers/Playwright.types.ts

@@ -76,6 +76,8 @@ expectType<void>(playwright.dontSeeInField(str, str));
 expectType<void>(playwright.attachFile(str, str));
 expectType<void>(playwright.selectOption(str, str));
 expectType<Promise<number>>(playwright.grabNumberOfVisibleElements(str));
+expectType<Promise<CodeceptJS.WebElement[]>>(playwright.grabWebElements(str));
+expectType<Promise<CodeceptJS.WebElement>>(playwright.grabWebElement(str));
 expectType<void>(playwright.seeInCurrentUrl(str));
 expectType<void>(playwright.dontSeeInCurrentUrl(str));
 expectType<void>(playwright.seeCurrentUrlEquals(str));
@@ -148,3 +150,14 @@ expectType<void>(playwright.dontSeeTraffic({ name: str, url: str }));
 expectType<void>(playwright.dontSeeTraffic({ name: str, url: /hello/ }));
 expectError(playwright.dontSeeTraffic({ name: str }));
 expectError(playwright.dontSeeTraffic({ url: str }));
+
+async function webElementTypes(el: CodeceptJS.WebElement) {
+  expectType<string>(await el.getText());
+  expectType<string | null>(await el.getAttribute(str));
+  expectType<boolean>(await el.isVisible());
+  expectType<void>(await el.click());
+  expectType<CodeceptJS.WebElement | null>(await el.$(str));
+  expectType<CodeceptJS.WebElement[]>(await el.$$(str));
+  expectError(el.getAtribute(str));
+  expectError(el.getAttribute(num));
+}

typings/tests/helpers/PlaywrightTs.types.ts

@@ -74,6 +74,8 @@ expectType<Promise<any>>(playwright.dontSeeInField(str, str));
 expectType<Promise<any>>(playwright.attachFile(str, str));
 expectType<Promise<any>>(playwright.selectOption(str, str));
 expectType<Promise<number>>(playwright.grabNumberOfVisibleElements(str));
+expectType<Promise<CodeceptJS.WebElement[]>>(playwright.grabWebElements(str));
+expectType<Promise<CodeceptJS.WebElement>>(playwright.grabWebElement(str));
 expectType<Promise<any>>(playwright.seeInCurrentUrl(str));
 expectType<Promise<any>>(playwright.dontSeeInCurrentUrl(str));
 expectType<Promise<any>>(playwright.seeCurrentUrlEquals(str));