Feat/aria selectors (#5260)

* implemented aria selectors for PW/WebDriver/Puppeteer

* added aria elements

* Implemented by role selector and aria locators with tests

* fixed aria selectors for WebDriverIO

* added tests, reverted runok

* 4.0.0-beta.1

* fixed aria tests

* fixed WD tests

* improved output

* fixed webdriver types

---------

Co-authored-by: DavertMik <[email protected]>

Author: 2 people

docs/webapi/click.mustache

@@ -3,9 +3,13 @@ If a fuzzy locator is given, the page will be searched for a button, link, or im
 For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched.
 For images, the "alt" attribute and inner text of any parent links are searched.
 
+If no locator is provided, defaults to clicking the body element (`'//body'`).
+
 The second parameter is a context (CSS or XPath locator) to narrow the search.
 
 ```js
+// click body element (default)
+I.click();
 // simple link
 I.click('Logout');
 // button of form
@@ -20,6 +24,6 @@ I.click('Logout', '#nav');
 I.click({css: 'nav a.login'});
 ```
 
-@param {CodeceptJS.LocatorOrString} locator clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+@param {CodeceptJS.LocatorOrString} [locator='//body'] (optional, `'//body'` by default) clickable link or button located by text, or any element located by CSS|XPath|strict locator.
 @param {?CodeceptJS.LocatorOrString | null} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
 @returns {void} automatically synchronized promise through #recorder

lib/command/init.js

@@ -40,7 +40,6 @@ const packages = []
 let isTypeScript = false
 let extension = 'js'
 
-const requireCodeceptConfigure = "const { setHeadlessWhen, setCommonPlugins } = require('@codeceptjs/configure');"
 const importCodeceptConfigure = "import { setHeadlessWhen, setCommonPlugins } from '@codeceptjs/configure';"
 
 const configHeader = `
@@ -237,9 +236,9 @@ export default async function (initPath) {
           fs.writeFileSync(typeScriptconfigFile, configSource, 'utf-8')
           print(`Config created at ${typeScriptconfigFile}`)
         } else {
-          configSource = beautify(`/** @type {CodeceptJS.MainConfig} */\nexports.config = ${inspect(config, false, 4, false)}`)
+          configSource = beautify(`/** @type {CodeceptJS.MainConfig} */\nexport const config = ${inspect(config, false, 4, false)}`)
 
-          if (hasConfigure) configSource = requireCodeceptConfigure + configHeader + configSource
+          if (hasConfigure) configSource = importCodeceptConfigure + configHeader + configSource
 
           fs.writeFileSync(configFile, configSource, 'utf-8')
           print(`Config created at ${configFile}`)

lib/helper/Playwright.js

@@ -30,7 +30,7 @@ import ElementNotFound from './errors/ElementNotFound.js'
 import RemoteBrowserConnectionRefused from './errors/RemoteBrowserConnectionRefused.js'
 import Popup from './extras/Popup.js'
 import Console from './extras/Console.js'
-import { findReact, findVue, findByPlaywrightLocator } from './extras/PlaywrightReactVueLocator.js'
+import { buildLocatorString, findElements, findElement, getVisibleElements, findReact, findVue, findByPlaywrightLocator, findByRole } from './extras/PlaywrightLocator.js'
 
 let playwright
 let perfTiming
@@ -2068,7 +2068,7 @@ class Playwright extends Helper {
    * ```
    *
    */
-  async click(locator, context = null, options = {}) {
+  async click(locator = '//body', context = null, options = {}) {
     return proceedClick.call(this, locator, context, options)
   }
 
@@ -2666,17 +2666,28 @@ class Playwright extends Helper {
    *
    */
   async grabTextFrom(locator) {
-    locator = this._contextLocator(locator)
+    const originalLocator = locator
+    const matchedLocator = new Locator(locator)
+
+    if (!matchedLocator.isFuzzy()) {
+      const els = await this._locate(matchedLocator)
+      assertElementExists(els, locator)
+      const text = await els[0].innerText()
+      this.debugSection('Text', text)
+      return text
+    }
+
+    const contextAwareLocator = this._contextLocator(matchedLocator.value)
     let text
     try {
-      text = await this.page.textContent(locator)
+      text = await this.page.textContent(contextAwareLocator)
     } catch (err) {
       if (err.message.includes('Timeout') || err.message.includes('exceeded')) {
-        throw new Error(`Element ${new Locator(locator).toString()} was not found by text|CSS|XPath`)
+        throw new Error(`Element ${new Locator(originalLocator).toString()} was not found by text|CSS|XPath`)
       }
       throw err
     }
-    assertElementExists(text, locator)
+    assertElementExists(text, contextAwareLocator)
     this.debugSection('Text', text)
     return text
   }
@@ -2866,6 +2877,33 @@ class Playwright extends Helper {
     return array
   }
 
+  /**
+   * Retrieves the ARIA snapshot for an element using Playwright's [`locator.ariaSnapshot`](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot).
+   * This method returns a YAML representation of the accessibility tree that can be used for assertions.
+   * If no locator is provided, it captures the snapshot of the entire page body.
+   *
+   * ```js
+   * const snapshot = await I.grabAriaSnapshot();
+   * expect(snapshot).toContain('heading "Sign up"');
+   *
+   * const formSnapshot = await I.grabAriaSnapshot('#login-form');
+   * expect(formSnapshot).toContain('textbox "Email"');
+   * ```
+   *
+   * [Learn more about ARIA snapshots](https://playwright.dev/docs/aria-snapshots)
+   *
+   * @param {string|object} [locator='//body'] element located by CSS|XPath|strict locator. Defaults to body element.
+   * @return {Promise<string>} YAML representation of the accessibility tree
+   */
+  async grabAriaSnapshot(locator = '//body') {
+    const matchedLocator = new Locator(locator)
+    const els = await this._locate(matchedLocator)
+    assertElementExists(els, locator)
+    const snapshot = await els[0].ariaSnapshot()
+    this.debugSection('Aria Snapshot', snapshot)
+    return snapshot
+  }
+
   /**
    * {{> saveElementScreenshot }}
    *
@@ -4123,157 +4161,6 @@ class Playwright extends Helper {
 
 export default Playwright
 
-function buildCustomLocatorString(locator) {
-  // Note: this.debug not available in standalone function, using console.log
-  console.log(`Building custom locator string: ${locator.type}=${locator.value}`)
-  return `${locator.type}=${locator.value}`
-}
-
-function buildLocatorString(locator) {
-  if (locator.isCustom()) {
-    return buildCustomLocatorString(locator)
-  }
-  if (locator.isXPath()) {
-    return `xpath=${locator.value}`
-  }
-  return locator.simplify()
-}
-
-async function findElements(matcher, locator) {
-  if (locator.react) return findReact(matcher, locator)
-  if (locator.vue) return findVue(matcher, locator)
-  if (locator.pw) return findByPlaywrightLocator.call(this, matcher, locator)
-
-  locator = new Locator(locator, 'css')
-
-  // Handle custom locators directly instead of relying on Playwright selector engines
-  if (locator.isCustom()) {
-    return findCustomElements.call(this, matcher, locator)
-  }
-
-  // Check if we have a custom context locator and need to search within it
-  if (this.contextLocator) {
-    const contextLocatorObj = new Locator(this.contextLocator, 'css')
-    if (contextLocatorObj.isCustom()) {
-      // Find the context elements first
-      const contextElements = await findCustomElements.call(this, matcher, contextLocatorObj)
-      if (contextElements.length === 0) {
-        return []
-      }
-
-      // Search within the first context element
-      const locatorString = buildLocatorString(locator)
-      return contextElements[0].locator(locatorString).all()
-    }
-  }
-
-  const locatorString = buildLocatorString(locator)
-
-  return matcher.locator(locatorString).all()
-}
-
-async function findCustomElements(matcher, locator) {
-  const customLocatorStrategies = this.customLocatorStrategies || globalCustomLocatorStrategies
-  const strategyFunction = customLocatorStrategies.get ? customLocatorStrategies.get(locator.type) : customLocatorStrategies[locator.type]
-
-  if (!strategyFunction) {
-    throw new Error(`Custom locator strategy "${locator.type}" is not defined. Please define "customLocatorStrategies" in your configuration.`)
-  }
-
-  // Execute the custom locator function in the browser context using page.evaluate
-  const page = matcher.constructor.name === 'Page' ? matcher : await matcher.page()
-
-  const elements = await page.evaluate(
-    ({ strategyCode, selector }) => {
-      const strategy = new Function('return ' + strategyCode)()
-      const result = strategy(selector, document)
-
-      // Convert NodeList or single element to array
-      if (result && result.nodeType) {
-        return [result]
-      } else if (result && result.length !== undefined) {
-        return Array.from(result)
-      } else if (Array.isArray(result)) {
-        return result
-      }
-
-      return []
-    },
-    {
-      strategyCode: strategyFunction.toString(),
-      selector: locator.value,
-    },
-  )
-
-  // Convert the found elements back to Playwright locators
-  if (elements.length === 0) {
-    return []
-  }
-
-  // Create CSS selectors for the found elements and return as locators
-  const locators = []
-  const timestamp = Date.now()
-
-  for (let i = 0; i < elements.length; i++) {
-    // Use a unique attribute approach to target specific elements
-    const uniqueAttr = `data-codecept-custom-${timestamp}-${i}`
-
-    await page.evaluate(
-      ({ index, uniqueAttr, strategyCode, selector }) => {
-        // Re-execute the strategy to find elements and mark the specific one
-        const strategy = new Function('return ' + strategyCode)()
-        const result = strategy(selector, document)
-
-        let elementsArray = []
-        if (result && result.nodeType) {
-          elementsArray = [result]
-        } else if (result && result.length !== undefined) {
-          elementsArray = Array.from(result)
-        } else if (Array.isArray(result)) {
-          elementsArray = result
-        }
-
-        if (elementsArray[index]) {
-          elementsArray[index].setAttribute(uniqueAttr, 'true')
-        }
-      },
-      {
-        index: i,
-        uniqueAttr,
-        strategyCode: strategyFunction.toString(),
-        selector: locator.value,
-      },
-    )
-
-    locators.push(page.locator(`[${uniqueAttr}="true"]`))
-  }
-
-  return locators
-}
-
-async function findElement(matcher, locator) {
-  if (locator.react) return findReact(matcher, locator)
-  if (locator.vue) return findVue(matcher, locator)
-  if (locator.pw) return findByPlaywrightLocator.call(this, matcher, locator)
-
-  locator = new Locator(locator, 'css')
-
-  return matcher.locator(buildLocatorString(locator)).first()
-}
-
-async function getVisibleElements(elements) {
-  const visibleElements = []
-  for (const element of elements) {
-    if (await element.isVisible()) {
-      visibleElements.push(element)
-    }
-  }
-  if (visibleElements.length === 0) {
-    return elements
-  }
-  return visibleElements
-}
-
 async function proceedClick(locator, context = null, options = {}) {
   let matcher = await this._getContext()
   if (context) {
@@ -4310,15 +4197,26 @@ async function proceedClick(locator, context = null, options = {}) {
 }
 
 async function findClickable(matcher, locator) {
-  if (locator.react) return findReact(matcher, locator)
-  if (locator.vue) return findVue(matcher, locator)
-  if (locator.pw) return findByPlaywrightLocator.call(this, matcher, locator)
+  const matchedLocator = new Locator(locator)
 
-  locator = new Locator(locator)
-  if (!locator.isFuzzy()) return findElements.call(this, matcher, locator)
+  if (!matchedLocator.isFuzzy()) return findElements.call(this, matcher, matchedLocator)
 
   let els
-  const literal = xpathLocator.literal(locator.value)
+  const literal = xpathLocator.literal(matchedLocator.value)
+
+  try {
+    els = await matcher.getByRole('button', { name: matchedLocator.value }).all()
+    if (els.length) return els
+  } catch (err) {
+    // getByRole not supported or failed
+  }
+
+  try {
+    els = await matcher.getByRole('link', { name: matchedLocator.value }).all()
+    if (els.length) return els
+  } catch (err) {
+    // getByRole not supported or failed
+  }
 
   els = await findElements.call(this, matcher, Locator.clickable.narrow(literal))
   if (els.length) return els
@@ -4333,7 +4231,7 @@ async function findClickable(matcher, locator) {
     // Do nothing
   }
 
-  return findElements.call(this, matcher, locator.value) // by css or xpath
+  return findElements.call(this, matcher, matchedLocator.value) // by css or xpath
 }
 
 async function proceedSee(assertType, text, context, strict = false) {
@@ -4374,10 +4272,10 @@ async function findCheckable(locator, context) {
 
   const matchedLocator = new Locator(locator)
   if (!matchedLocator.isFuzzy()) {
-    return findElements.call(this, contextEl, matchedLocator.simplify())
+    return findElements.call(this, contextEl, matchedLocator)
   }
 
-  const literal = xpathLocator.literal(locator)
+  const literal = xpathLocator.literal(matchedLocator.value)
   let els = await findElements.call(this, contextEl, Locator.checkable.byText(literal))
   if (els.length) {
     return els
@@ -4386,7 +4284,7 @@ async function findCheckable(locator, context) {
   if (els.length) {
     return els
   }
-  return findElements.call(this, contextEl, locator)
+  return findElements.call(this, contextEl, matchedLocator.value)
 }
 
 async function proceedIsChecked(assertType, option) {