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

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

Generate a CodeceptJS.WebElement declaration from lib/element/WebElement.js
and use it as the return type of grabWebElement() and grabWebElements().
Fix WebElement JSDoc that jsdoc could not parse or that referenced
undefined types, and mark click()/type() options as optional.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(Puppeteer): return WebElement from grabWebElement()

A duplicate grabWebElement() overrode the WebElement-returning one and
returned the raw ElementHandle, contradicting the new typings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(webapi): check grabWebElement() result via toOuterHTML()

getText() is not implemented for CDPBrowser's WebElement, which broke
the Lightpanda, Moli and Obscura jobs. toOuterHTML() works on all
helpers and still fails on a raw Puppeteer ElementHandle.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: mirao

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

@@ -2744,7 +2744,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<CodeceptJS.StepPromise>(playwright.dontSeeInField(str, str));
 expectType<CodeceptJS.ElementStepPromise>(playwright.attachFile(str, str));
 expectType<CodeceptJS.ElementStepPromise>(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<CodeceptJS.StepPromise>(playwright.seeInCurrentUrl(str));
 expectType<CodeceptJS.StepPromise>(playwright.dontSeeInCurrentUrl(str));
 expectType<CodeceptJS.StepPromise>(playwright.seeCurrentUrlEquals(str));
@@ -156,3 +158,14 @@ expectType<CodeceptJS.ElementStepPromise>(playwright.checkOption(str).at(2))
 expectType<CodeceptJS.StepPromise>(playwright.see(str).timeout(5))
 expectType<CodeceptJS.StepPromise>(playwright.see(str).retry(3))
 expectType<CodeceptJS.ElementStepPromise>(playwright.click(str).first().timeout(5).retry(3))
+
+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<CodeceptJS.StepPromise>(playwright.dontSeeInField(str, str));
 expectType<CodeceptJS.ElementStepPromise>(playwright.attachFile(str, str));
 expectType<CodeceptJS.ElementStepPromise>(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<CodeceptJS.StepPromise>(playwright.seeInCurrentUrl(str));
 expectType<CodeceptJS.StepPromise>(playwright.dontSeeInCurrentUrl(str));
 expectType<CodeceptJS.StepPromise>(playwright.seeCurrentUrlEquals(str));