codeceptjs 4.0.0-rc.1 → 4.0.0-rc.10

package/lib/helper/Playwright.js

@@ -23,7 +23,11 @@ import {
   clearString,
   requireWithFallback,
   normalizeSpacesInString,
+  normalizePath,
+  resolveUrl,
   relativeDir,
+  getMimeType,
+  base64EncodeFile,
 } from '../utils.js'
 import { isColorProperty, convertColorToRGBA } from '../colorUtils.js'
 import ElementNotFound from './errors/ElementNotFound.js'
@@ -32,7 +36,9 @@ import RemoteBrowserConnectionRefused from './errors/RemoteBrowserConnectionRefu
 import Popup from './extras/Popup.js'
 import Console from './extras/Console.js'
 import { findReact, findVue, findByPlaywrightLocator } from './extras/PlaywrightReactVueLocator.js'
+import { dropFile } from './scripts/dropFile.js'
 import WebElement from '../element/WebElement.js'
+import { selectElement } from './extras/elementSelection.js'
 
 let playwright
 let perfTiming
@@ -1490,8 +1496,23 @@ class Playwright extends Helper {
    *
    */
   async moveCursorTo(locator, offsetX = 0, offsetY = 0) {
-    const el = await this._locateElement(locator)
-    assertElementExists(el, locator)
+    let context = null
+    if (typeof offsetX !== 'number') {
+      context = offsetX
+      offsetX = 0
+    }
+
+    let el
+    if (context) {
+      const contextEls = await this._locate(context)
+      assertElementExists(contextEls, context, 'Context element')
+      el = await findElements.call(this, contextEls[0], locator)
+      assertElementExists(el, locator)
+      el = el[0]
+    } else {
+      el = await this._locateElement(locator)
+      assertElementExists(el, locator)
+    }
 
     // Use manual mouse.move instead of .hover() so the offset can be added to the coordinates
     const { x, y } = await clickablePoint(el)
@@ -1759,8 +1780,7 @@ class Playwright extends Helper {
     if (elements.length === 0) {
       throw new ElementNotFound(locator, 'Element', 'was not found')
     }
-    if (this.options.strict) assertOnlyOneElement(elements, locator)
-    return elements[0]
+    return selectElement(elements, locator, this)
   }
 
   /**
@@ -1775,8 +1795,7 @@ class Playwright extends Helper {
     const context = providedContext || (await this._getContext())
     const els = await findCheckable.call(this, locator, context)
     assertElementExists(els[0], locator, 'Checkbox or radio')
-    if (this.options.strict) assertOnlyOneElement(els, locator)
-    return els[0]
+    return selectElement(els, locator, this)
   }
 
   /**
@@ -1944,8 +1963,15 @@ class Playwright extends Helper {
    * {{> seeElement }}
    *
    */
-  async seeElement(locator) {
-    let els = await this._locate(locator)
+  async seeElement(locator, context = null) {
+    let els
+    if (context) {
+      const contextEls = await this._locate(context)
+      assertElementExists(contextEls, context, 'Context element')
+      els = await findElements.call(this, contextEls[0], locator)
+    } else {
+      els = await this._locate(locator)
+    }
     els = await Promise.all(els.map(el => el.isVisible()))
     try {
       return empty('visible elements').negate(els.filter(v => v).fill('ELEMENT'))
@@ -1958,8 +1984,15 @@ class Playwright extends Helper {
    * {{> dontSeeElement }}
    *
    */
-  async dontSeeElement(locator) {
-    let els = await this._locate(locator)
+  async dontSeeElement(locator, context = null) {
+    let els
+    if (context) {
+      const contextEls = await this._locate(context)
+      assertElementExists(contextEls, context, 'Context element')
+      els = await findElements.call(this, contextEls[0], locator)
+    } else {
+      els = await this._locate(locator)
+    }
     els = await Promise.all(els.map(el => el.isVisible()))
     try {
       return empty('visible elements').assert(els.filter(v => v).fill('ELEMENT'))
@@ -2245,11 +2278,10 @@ class Playwright extends Helper {
    * {{> fillField }}
    *
    */
-  async fillField(field, value) {
-    const els = await findFields.call(this, field)
+  async fillField(field, value, context = null) {
+    const els = await findFields.call(this, field, context)
     assertElementExists(els, field, 'Field')
-    if (this.options.strict) assertOnlyOneElement(els, field)
-    const el = els[0]
+    const el = selectElement(els, field, this)
 
     await el.clear()
     if (store.debugMode) this.debugSection('Focused', await elToString(el, 1))
@@ -2262,28 +2294,13 @@ class Playwright extends Helper {
   }
 
   /**
-   * Clears the text input element: `<input>`, `<textarea>` or `[contenteditable]` .
-   *
-   *
-   * Examples:
-   *
-   * ```js
-   * I.clearField('.text-area')
-   *
-   * // if this doesn't work use force option
-   * I.clearField('#submit', { force: true })
-   * ```
-   * Use `force` to bypass the [actionability](https://playwright.dev/docs/actionability) checks.
-   *
-   * @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-clear) for available options object as 2nd argument.
+   * {{> clearField }}
    */
-  async clearField(locator, options = {}) {
-    const els = await findFields.call(this, locator)
+  async clearField(locator, context = null) {
+    const els = await findFields.call(this, locator, context)
     assertElementExists(els, locator, 'Field to clear')
-    if (this.options.strict) assertOnlyOneElement(els, locator)
 
-    const el = els[0]
+    const el = selectElement(els, locator, this)
 
     await highlightActiveElement.call(this, el)
 
@@ -2295,76 +2312,101 @@ class Playwright extends Helper {
   /**
    * {{> appendField }}
    */
-  async appendField(field, value) {
-    const els = await findFields.call(this, field)
+  async appendField(field, value, context = null) {
+    const els = await findFields.call(this, field, context)
     assertElementExists(els, field, 'Field')
-    if (this.options.strict) assertOnlyOneElement(els, field)
-    await highlightActiveElement.call(this, els[0])
-    await els[0].press('End')
-    await els[0].type(value.toString(), { delay: this.options.pressKeyDelay })
+    const el = selectElement(els, field, this)
+    await highlightActiveElement.call(this, el)
+    await el.press('End')
+    await el.type(value.toString(), { delay: this.options.pressKeyDelay })
     return this._waitForAction()
   }
 
   /**
    * {{> seeInField }}
    */
-  async seeInField(field, value) {
+  async seeInField(field, value, context = null) {
     const _value = typeof value === 'boolean' ? value : value.toString()
-    return proceedSeeInField.call(this, 'assert', field, _value)
+    return proceedSeeInField.call(this, 'assert', field, _value, context)
   }
 
   /**
    * {{> dontSeeInField }}
    */
-  async dontSeeInField(field, value) {
+  async dontSeeInField(field, value, context = null) {
     const _value = typeof value === 'boolean' ? value : value.toString()
-    return proceedSeeInField.call(this, 'negate', field, _value)
+    return proceedSeeInField.call(this, 'negate', field, _value, context)
   }
 
   /**
    * {{> attachFile }}
    *
    */
-  async attachFile(locator, pathToFile) {
+  async attachFile(locator, pathToFile, context = null) {
     const file = path.join(global.codecept_dir, pathToFile)
 
     if (!fileExists(file)) {
       throw new Error(`File at ${file} can not be found on local system`)
     }
-    const els = await findFields.call(this, locator)
-    assertElementExists(els, locator, 'Field')
-    await els[0].setInputFiles(file)
+    const els = await findFields.call(this, locator, context)
+    if (els.length) {
+      const el = selectElement(els, locator, this)
+      const tag = await el.evaluate(el => el.tagName)
+      const type = await el.evaluate(el => el.type)
+      if (tag === 'INPUT' && type === 'file') {
+        await el.setInputFiles(file)
+        return this._waitForAction()
+      }
+    }
+
+    const targetEls = els.length ? els : await this._locate(locator)
+    assertElementExists(targetEls, locator, 'Element')
+    const el = selectElement(targetEls, locator, this)
+    const fileData = {
+      base64Content: base64EncodeFile(file),
+      fileName: path.basename(file),
+      mimeType: getMimeType(path.basename(file)),
+    }
+    await el.evaluate(dropFile, fileData)
     return this._waitForAction()
   }
 
   /**
    * {{> selectOption }}
    */
-  async selectOption(select, option) {
-    const context = await this.context
+  async selectOption(select, option, context = null) {
+    const pageContext = await this.context
     const matchedLocator = new Locator(select)
 
+    let contextEl
+    if (context) {
+      const contextEls = await this._locate(context)
+      assertElementExists(contextEls, context, 'Context element')
+      contextEl = contextEls[0]
+    }
+
     // Strict locator
     if (!matchedLocator.isFuzzy()) {
       this.debugSection('SelectOption', `Strict: ${JSON.stringify(select)}`)
-      const els = await this._locate(matchedLocator)
+      const els = contextEl ? await findElements.call(this, contextEl, matchedLocator) : await this._locate(matchedLocator)
       assertElementExists(els, select, 'Selectable element')
-      return proceedSelect.call(this, context, els[0], option)
+      return proceedSelect.call(this, pageContext, selectElement(els, select, this), option)
     }
 
     // Fuzzy: try combobox
     this.debugSection('SelectOption', `Fuzzy: "${matchedLocator.value}"`)
-    let els = await findByRole(context, { role: 'combobox', name: matchedLocator.value })
-    if (els?.length) return proceedSelect.call(this, context, els[0], option)
+    const comboboxSearchCtx = contextEl || pageContext
+    let els = await findByRole(comboboxSearchCtx, { role: 'combobox', name: matchedLocator.value })
+    if (els?.length) return proceedSelect.call(this, pageContext, selectElement(els, select, this), option)
 
     // Fuzzy: try listbox
-    els = await findByRole(context, { role: 'listbox', name: matchedLocator.value })
-    if (els?.length) return proceedSelect.call(this, context, els[0], option)
+    els = await findByRole(comboboxSearchCtx, { role: 'listbox', name: matchedLocator.value })
+    if (els?.length) return proceedSelect.call(this, pageContext, selectElement(els, select, this), option)
 
     // Fuzzy: try native select
-    els = await findFields.call(this, select)
+    els = await findFields.call(this, select, context)
     assertElementExists(els, select, 'Selectable element')
-    return proceedSelect.call(this, context, els[0], option)
+    return proceedSelect.call(this, pageContext, selectElement(els, select, this), option)
   }
 
   /**
@@ -2405,6 +2447,26 @@ class Playwright extends Helper {
     urlEquals(this.options.url).negate(url, await this._getPageUrl())
   }
 
+  /**
+   * {{> seeCurrentPathEquals }}
+   */
+  async seeCurrentPathEquals(path) {
+    const currentUrl = await this._getPageUrl()
+    const baseUrl = this.options.url || 'http://localhost'
+    const actualPath = new URL(currentUrl, baseUrl).pathname
+    return equals('url path').assert(normalizePath(path), normalizePath(actualPath))
+  }
+
+  /**
+   * {{> dontSeeCurrentPathEquals }}
+   */
+  async dontSeeCurrentPathEquals(path) {
+    const currentUrl = await this._getPageUrl()
+    const baseUrl = this.options.url || 'http://localhost'
+    const actualPath = new URL(currentUrl, baseUrl).pathname
+    return equals('url path').negate(normalizePath(path), normalizePath(actualPath))
+  }
+
   /**
    * {{> see }}
    *
@@ -2638,15 +2700,12 @@ class Playwright extends Helper {
    *
    */
   async grabTextFrom(locator) {
-    // Handle role locators with text/exact options
-    if (isRoleLocatorObject(locator)) {
-      const elements = await handleRoleLocator(this.page, locator)
-      if (elements && elements.length > 0) {
-        const text = await elements[0].textContent()
-        assertElementExists(text, JSON.stringify(locator))
-        this.debugSection('Text', text)
-        return text
-      }
+    const roleElements = await handleRoleLocator(this.page, locator)
+    if (roleElements && roleElements.length > 0) {
+      const text = await roleElements[0].textContent()
+      assertElementExists(text, JSON.stringify(locator))
+      this.debugSection('Text', text)
+      return text
     }
 
     const locatorObj = new Locator(locator, 'css')
@@ -3362,6 +3421,7 @@ class Playwright extends Helper {
    */
   async waitInUrl(urlPart, sec = null) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout
+    const expectedUrl = resolveUrl(urlPart, this.options.url)
 
     return this.page
       .waitForFunction(
@@ -3369,13 +3429,13 @@ class Playwright extends Helper {
           const currUrl = decodeURIComponent(decodeURIComponent(decodeURIComponent(window.location.href)))
           return currUrl.indexOf(urlPart) > -1
         },
-        urlPart,
+        expectedUrl,
         { timeout: waitTimeout },
       )
       .catch(async e => {
-        const currUrl = await this._getPageUrl() // Required because the waitForFunction can't return data.
+        const currUrl = await this._getPageUrl()
         if (/Timeout/i.test(e.message)) {
-          throw new Error(`expected url to include ${urlPart}, but found ${currUrl}`)
+          throw new Error(`expected url to include ${expectedUrl}, but found ${currUrl}`)
         } else {
           throw e
         }
@@ -3387,26 +3447,46 @@ class Playwright extends Helper {
    */
   async waitUrlEquals(urlPart, sec = null) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout
-
-    const baseUrl = this.options.url
-    let expectedUrl = urlPart
-    if (urlPart.indexOf('http') < 0) {
-      expectedUrl = baseUrl + urlPart
-    }
+    const expectedUrl = resolveUrl(urlPart, this.options.url)
 
     try {
       await this.page.waitForURL(
-        url => url.href.includes(expectedUrl),
+        url => url.href === expectedUrl,
         { timeout: waitTimeout },
       )
     } catch (e) {
       const currUrl = await this._getPageUrl()
       if (/Timeout/i.test(e.message)) {
-        if (!currUrl.includes(expectedUrl)) {
-          throw new Error(`expected url to be ${expectedUrl}, but found ${currUrl}`)
-        } else {
-          throw new Error(`expected url not loaded, error message: ${e.message}`)
-        }
+        throw new Error(`expected url to be ${expectedUrl}, but found ${currUrl}`)
+      } else {
+        throw e
+      }
+    }
+  }
+
+  /**
+   * {{> waitCurrentPathEquals }}
+   */
+  async waitCurrentPathEquals(path, sec = null) {
+    const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout
+    const normalizedPath = normalizePath(path)
+
+    try {
+      await this.page.waitForFunction(
+        expectedPath => {
+          const actualPath = window.location.pathname
+          const normalizePath = p => (p === '' || p === '/' ? '/' : p.replace(/\/+/g, '/').replace(/\/$/, '') || '/')
+          return normalizePath(actualPath) === expectedPath
+        },
+        normalizedPath,
+        { timeout: waitTimeout },
+      )
+    } catch (e) {
+      const currentUrl = await this._getPageUrl()
+      const baseUrl = this.options.url || 'http://localhost'
+      const actualPath = new URL(currentUrl, baseUrl).pathname
+      if (/Timeout/i.test(e.message)) {
+        throw new Error(`expected path to be ${normalizedPath}, but found ${normalizePath(actualPath)}`)
       } else {
         throw e
       }
@@ -4092,9 +4172,15 @@ class Playwright extends Helper {
 
 export default Playwright
 
-function buildLocatorString(locator) {
+export function buildLocatorString(locator) {
   if (locator.isXPath()) {
-    return `xpath=${locator.value}`
+    // Make XPath relative so it works correctly within scoped contexts (e.g. within()).
+    // Playwright's XPath engine auto-converts "//..." to ".//..." when the root is not a Document,
+    // but only when the selector starts with "/". Locator methods like at() wrap XPath in
+    // parentheses (e.g. "(//...)[position()=1]"), bypassing that auto-conversion.
+    // We fix this by prepending "." before the first "//" that follows any leading parentheses.
+    const value = locator.value.replace(/^(\(*)\/\//, '$1.//')
+    return `xpath=${value}`
   }
   if (locator.isShadow()) {
     // Convert shadow locator to CSS with >> chaining operator
@@ -4105,25 +4191,22 @@ function buildLocatorString(locator) {
   return locator.simplify()
 }
 
-/**
- * Checks if a locator is a role locator object (e.g., {role: 'button', text: 'Submit', exact: true})
- */
-function isRoleLocatorObject(locator) {
-  return locator && typeof locator === 'object' && locator.role && !locator.type
-}
-
 /**
  * Handles role locator objects by converting them to Playwright's getByRole() API
+ * Accepts both raw objects ({role: 'button', text: 'Submit'}) and Locator-wrapped role objects.
  * Returns elements array if role locator, null otherwise
  */
 async function handleRoleLocator(context, locator) {
-  if (!isRoleLocatorObject(locator)) return null
+  const loc = new Locator(locator)
+  if (!loc.isRole()) return null
 
+  const roleObj = loc.locator || {}
   const options = {}
-  if (locator.text) options.name = locator.text
-  if (locator.exact !== undefined) options.exact = locator.exact
+  if (roleObj.text) options.name = roleObj.text
+  if (roleObj.name) options.name = roleObj.name
+  if (roleObj.exact !== undefined) options.exact = roleObj.exact
 
-  return context.getByRole(locator.role, Object.keys(options).length > 0 ? options : undefined).all()
+  return context.getByRole(roleObj.role, Object.keys(options).length > 0 ? options : undefined).all()
 }
 
 async function findByRole(context, locator) {
@@ -4192,16 +4275,22 @@ async function proceedClick(locator, context = null, options = {}) {
     assertElementExists(els, locator, 'Clickable element')
   }
 
-  await highlightActiveElement.call(this, els[0])
-  if (store.debugMode) this.debugSection('Clicked', await elToString(els[0], 1))
+  const opts = store.currentStep?.opts
+  let element
+  if (opts?.elementIndex != null) {
+    element = selectElement(els, locator, this)
+  } else {
+    const strict = (opts?.exact === false || opts?.strictMode === false) ? false : (this.options.strict || opts?.exact === true || opts?.strictMode === true)
+    if (strict) assertOnlyOneElement(els, locator, this)
+    element = els.length > 1 ? (await getVisibleElements(els))[0] : els[0]
+  }
+
+  await highlightActiveElement.call(this, element)
+  if (store.debugMode) this.debugSection('Clicked', await elToString(element, 1))
 
-  /*
-    using the force true options itself but instead dispatching a click
-  */
   if (options.force) {
-    await els[0].dispatchEvent('click')
+    await element.dispatchEvent('click')
   } else {
-    const element = els.length > 1 ? (await getVisibleElements(els))[0] : els[0]
     await element.click(options)
   }
   const promises = []
@@ -4218,7 +4307,6 @@ async function findClickable(matcher, locator) {
 
   if (!matchedLocator.isFuzzy()) {
     const els = await findElements.call(this, matcher, matchedLocator)
-    if (this.options.strict) assertOnlyOneElement(els, locator)
     return els
   }
 
@@ -4227,42 +4315,27 @@ async function findClickable(matcher, locator) {
 
   try {
     els = await matcher.getByRole('button', { name: matchedLocator.value }).all()
-    if (els.length) {
-      if (this.options.strict) assertOnlyOneElement(els, locator)
-      return els
-    }
+    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) {
-      if (this.options.strict) assertOnlyOneElement(els, locator)
-      return els
-    }
+    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) {
-    if (this.options.strict) assertOnlyOneElement(els, locator)
-    return els
-  }
+  if (els.length) return els
 
   els = await findElements.call(this, matcher, Locator.clickable.wide(literal))
-  if (els.length) {
-    if (this.options.strict) assertOnlyOneElement(els, locator)
-    return els
-  }
+  if (els.length) return els
 
   try {
     els = await findElements.call(this, matcher, Locator.clickable.self(literal))
-    if (els.length) {
-      if (this.options.strict) assertOnlyOneElement(els, locator)
-      return els
-    }
+    if (els.length) return els
   } catch (err) {
     // Do nothing
   }
@@ -4335,34 +4408,42 @@ async function proceedIsChecked(assertType, option) {
   return truth(`checkable ${option}`, 'to be checked')[assertType](selected)
 }
 
-async function findFields(locator) {
-  // Handle role locators with text/exact options
-  if (isRoleLocatorObject(locator)) {
-    const page = await this.page
-    const roleElements = await handleRoleLocator(page, locator)
-    if (roleElements) return roleElements
+async function findFields(locator, context = null) {
+  let contextEl
+  if (context) {
+    const contextEls = await this._locate(context)
+    assertElementExists(contextEls, context, 'Context element')
+    contextEl = contextEls[0]
   }
 
+  const locateFn = contextEl
+    ? loc => findElements.call(this, contextEl, loc)
+    : loc => this._locate(loc)
+
+  const matcher = contextEl || (await this.page)
+  const roleElements = await handleRoleLocator(matcher, locator)
+  if (roleElements) return roleElements
+
   const matchedLocator = new Locator(locator)
   if (!matchedLocator.isFuzzy()) {
-    return this._locate(matchedLocator)
+    return locateFn(matchedLocator)
   }
   const literal = xpathLocator.literal(locator)
 
-  let els = await this._locate({ xpath: Locator.field.labelEquals(literal) })
+  let els = await locateFn({ xpath: Locator.field.labelEquals(literal) })
   if (els.length) {
     return els
   }
 
-  els = await this._locate({ xpath: Locator.field.labelContains(literal) })
+  els = await locateFn({ xpath: Locator.field.labelContains(literal) })
   if (els.length) {
     return els
   }
-  els = await this._locate({ xpath: Locator.field.byName(literal) })
+  els = await locateFn({ xpath: Locator.field.byName(literal) })
   if (els.length) {
     return els
   }
-  return this._locate({ css: locator })
+  return locateFn({ css: locator })
 }
 
 async function proceedSelect(context, el, option) {
@@ -4411,8 +4492,8 @@ async function proceedSelect(context, el, option) {
   return this._waitForAction()
 }
 
-async function proceedSeeInField(assertType, field, value) {
-  const els = await findFields.call(this, field)
+async function proceedSeeInField(assertType, field, value, context) {
+  const els = await findFields.call(this, field, context)
   assertElementExists(els, field, 'Field')
   const el = els[0]
   const tag = await el.evaluate(e => e.tagName)
@@ -4526,9 +4607,10 @@ function assertElementExists(res, locator, prefix, suffix) {
   }
 }
 
-function assertOnlyOneElement(elements, locator) {
+function assertOnlyOneElement(elements, locator, helper) {
   if (elements.length > 1) {
-    throw new MultipleElementsFound(locator, elements)
+    const webElements = elements.map(el => new WebElement(el, helper))
+    throw new MultipleElementsFound(locator, webElements)
   }
 }