codeceptjs 4.0.0-rc.8 → 4.0.0

package/lib/helper/WebDriver.js

@@ -10,6 +10,7 @@ import promiseRetry from 'promise-retry'
 import { includes as stringIncludes } from '../assert/include.js'
 import { urlEquals, equals } from '../assert/equal.js'
 import store from '../store.js'
+import { checkFocusBeforeType, checkFocusBeforePressKey } from './extras/focusCheck.js'
 import output from '../output.js'
 const { debug } = output
 import { empty } from '../assert/empty.js'
@@ -40,6 +41,8 @@ import { dontSeeElementError, seeElementError, seeElementInDOMError, dontSeeElem
 import { dropFile } from './scripts/dropFile.js'
 import { dontSeeTraffic, seeTraffic, grabRecordedNetworkTraffics, stopRecordingTraffic, flushNetworkTraffics } from './network/actions.js'
 import WebElement from '../element/WebElement.js'
+import { selectElement } from './extras/elementSelection.js'
+import { fillRichEditor } from './extras/richTextEditor.js'
 
 const SHADOW = 'shadow'
 const webRoot = 'body'
@@ -94,11 +97,7 @@ const config = {}
  * WebDriver helper which wraps [webdriverio](http://webdriver.io/) library to
  * manipulate browser using Selenium WebDriver or PhantomJS.
  *
- * WebDriver requires Selenium Server and ChromeDriver/GeckoDriver to be installed. Those tools can be easily installed via NPM. Please check [Testing with WebDriver](https://codecept.io/webdriver/#testing-with-webdriver) for more details.
- *
- * With the release of WebdriverIO version v8.14.0, and onwards, all driver management hassles are now a thing of the past 🙌. Read more [here](https://webdriver.io/blog/2023/07/31/driver-management/).
- * One of the significant advantages of this update is that you can now get rid of any driver services you previously had to manage, such as
- * `wdio-chromedriver-service`, `wdio-geckodriver-service`, `wdio-edgedriver-service`, `wdio-safaridriver-service`, and even `@wdio/selenium-standalone-service`.
+ * No Selenium Server, ChromeDriver, or GeckoDriver to install or start. Since WebdriverIO 9, driver management is fully automatic — WebdriverIO downloads and starts the matching driver for you. Read more [here](https://webdriver.io/blog/2023/07/31/driver-management/). Please check [Testing with WebDriver](https://codecept.io/webdriver/#testing-with-webdriver) for more details.
  *
  * For those who require custom driver options, fear not; WebDriver Helper allows you to pass in driver options through custom WebDriver configuration.
  * If you have a custom grid, use a cloud service, or prefer to run your own driver, there's no need to worry since WebDriver Helper will only start a driver when there are no other connection information settings like hostname or port specified.
@@ -905,13 +904,6 @@ class WebDriver extends Helper {
       return els
     }
 
-    // special locator type for React
-    if (locator.react) {
-      const els = await this.browser.react$$(locator.react, locator.props || undefined, locator.state || undefined)
-      this.debugSection('Elements', `Found ${els.length} react components`)
-      return els
-    }
-
     // special locator type for ARIA roles
     if (locator.role) {
       return this._locateByRole(locator)
@@ -1081,7 +1073,6 @@ class WebDriver extends Helper {
   /**
    * {{> click }}
    *
-   * {{ react }}
    */
   async click(locator, context = null) {
     const clickMethod = this.browser.isMobile && this.browser.capabilities.platformName !== 'android' ? 'touchClick' : 'elementClick'
@@ -1093,8 +1084,7 @@ class WebDriver extends Helper {
     } else {
       assertElementExists(res, locator, 'Clickable element')
     }
-    if (this.options.strict) assertOnlyOneElement(res, locator, this)
-    const elem = usingFirstElement(res)
+    const elem = selectElement(res, locator, this)
     highlightActiveElement.call(this, elem)
     return this.browser[clickMethod](getElementId(elem))
   }
@@ -1102,7 +1092,6 @@ class WebDriver extends Helper {
   /**
    * {{> forceClick }}
    *
-   * {{ react }}
    */
   async forceClick(locator, context = null) {
     const locateFn = prepareLocateFn.call(this, context)
@@ -1113,8 +1102,7 @@ class WebDriver extends Helper {
     } else {
       assertElementExists(res, locator, 'Clickable element')
     }
-    if (this.options.strict) assertOnlyOneElement(res, locator, this)
-    const elem = usingFirstElement(res)
+    const elem = selectElement(res, locator, this)
     highlightActiveElement.call(this, elem)
 
     return this.executeScript(el => {
@@ -1130,7 +1118,6 @@ class WebDriver extends Helper {
   /**
    * {{> doubleClick }}
    *
-   * {{ react }}
    */
   async doubleClick(locator, context = null) {
     const locateFn = prepareLocateFn.call(this, context)
@@ -1141,9 +1128,8 @@ class WebDriver extends Helper {
     } else {
       assertElementExists(res, locator, 'Clickable element')
     }
-    if (this.options.strict) assertOnlyOneElement(res, locator, this)
 
-    const elem = usingFirstElement(res)
+    const elem = selectElement(res, locator, this)
     highlightActiveElement.call(this, elem)
     return elem.doubleClick()
   }
@@ -1151,7 +1137,6 @@ class WebDriver extends Helper {
   /**
    * {{> rightClick }}
    *
-   * {{ react }}
    */
   async rightClick(locator, context) {
     const locateFn = prepareLocateFn.call(this, context)
@@ -1162,9 +1147,8 @@ class WebDriver extends Helper {
     } else {
       assertElementExists(res, locator, 'Clickable element')
     }
-    if (this.options.strict) assertOnlyOneElement(res, locator, this)
 
-    const el = usingFirstElement(res)
+    const el = selectElement(res, locator, this)
 
     await el.moveTo()
 
@@ -1247,7 +1231,6 @@ class WebDriver extends Helper {
   /**
    * {{> forceRightClick }}
    *
-   * {{ react }}
    */
   async forceRightClick(locator, context = null) {
     const locateFn = prepareLocateFn.call(this, context)
@@ -1272,16 +1255,19 @@ class WebDriver extends Helper {
 
   /**
    * {{> fillField }}
-   * {{ react }}
    * {{ custom }}
    *
    */
   async fillField(field, value, context = null) {
     const res = await findFields.call(this, field, context)
     assertElementExists(res, field, 'Field')
-    if (this.options.strict) assertOnlyOneElement(res, field, this)
-    const elem = usingFirstElement(res)
+    const elem = selectElement(res, field, this)
     highlightActiveElement.call(this, elem)
+
+    if (await fillRichEditor(this, elem, value)) {
+      return
+    }
+
     try {
       await elem.clearValue()
     } catch (err) {
@@ -1298,13 +1284,11 @@ class WebDriver extends Helper {
 
   /**
    * {{> appendField }}
-   * {{ react }}
    */
   async appendField(field, value, context = null) {
     const res = await findFields.call(this, field, context)
     assertElementExists(res, field, 'Field')
-    if (this.options.strict) assertOnlyOneElement(res, field, this)
-    const elem = usingFirstElement(res)
+    const elem = selectElement(res, field, this)
     highlightActiveElement.call(this, elem)
     return elem.addValue(value.toString())
   }
@@ -1316,8 +1300,7 @@ class WebDriver extends Helper {
   async clearField(field, context = null) {
     const res = await findFields.call(this, field, context)
     assertElementExists(res, field, 'Field')
-    if (this.options.strict) assertOnlyOneElement(res, field, this)
-    const elem = usingFirstElement(res)
+    const elem = selectElement(res, field, this)
     highlightActiveElement.call(this, elem)
     return elem.clearValue(getElementId(elem))
   }
@@ -1334,22 +1317,22 @@ class WebDriver extends Helper {
       this.debugSection('SelectOption', `Strict: ${JSON.stringify(select)}`)
       const els = await locateFn(select)
       assertElementExists(els, select, 'Selectable element')
-      return proceedSelectOption.call(this, usingFirstElement(els), option)
+      return proceedSelectOption.call(this, selectElement(els, select, this), option)
     }
 
     // Fuzzy: try combobox
     this.debugSection('SelectOption', `Fuzzy: "${matchedLocator.value}"`)
     let els = await this._locateByRole({ role: 'combobox', text: matchedLocator.value })
-    if (els?.length) return proceedSelectOption.call(this, usingFirstElement(els), option)
+    if (els?.length) return proceedSelectOption.call(this, selectElement(els, select, this), option)
 
     // Fuzzy: try listbox
     els = await this._locateByRole({ role: 'listbox', text: matchedLocator.value })
-    if (els?.length) return proceedSelectOption.call(this, usingFirstElement(els), option)
+    if (els?.length) return proceedSelectOption.call(this, selectElement(els, select, this), option)
 
     // Fuzzy: try native select
     const res = await findFields.call(this, select, context)
     assertElementExists(res, select, 'Selectable field')
-    return proceedSelectOption.call(this, usingFirstElement(res), option)
+    return proceedSelectOption.call(this, selectElement(res, select, this), option)
   }
 
   /**
@@ -1358,7 +1341,7 @@ class WebDriver extends Helper {
    * {{> attachFile }}
    */
   async attachFile(locator, pathToFile, context = null) {
-    let file = path.join(global.codecept_dir, pathToFile)
+    let file = path.join(store.codeceptDir, pathToFile)
     if (!fileExists(file)) {
       throw new Error(`File at ${file} can not be found on local system`)
     }
@@ -1367,7 +1350,7 @@ class WebDriver extends Helper {
     this.debug(`Uploading ${file}`)
 
     if (res.length) {
-      const el = usingFirstElement(res)
+      const el = selectElement(res, locator, this)
       const tag = await this.browser.execute(function (elem) { return elem.tagName }, el)
       const type = await this.browser.execute(function (elem) { return elem.type }, el)
       if (tag === 'INPUT' && type === 'file') {
@@ -1385,7 +1368,7 @@ class WebDriver extends Helper {
 
     const targetRes = res.length ? res : await this._locate(locator)
     assertElementExists(targetRes, locator, 'Element')
-    const targetEl = usingFirstElement(targetRes)
+    const targetEl = selectElement(targetRes, locator, this)
     const fileData = {
       base64Content: base64EncodeFile(file),
       fileName: path.basename(file),
@@ -1405,7 +1388,7 @@ class WebDriver extends Helper {
     const res = await findCheckable.call(this, field, locateFn)
 
     assertElementExists(res, field, 'Checkable')
-    const elem = usingFirstElement(res)
+    const elem = selectElement(res, field, this)
     const elementId = getElementId(elem)
     highlightActiveElement.call(this, elem)
 
@@ -1426,7 +1409,7 @@ class WebDriver extends Helper {
     const res = await findCheckable.call(this, field, locateFn)
 
     assertElementExists(res, field, 'Checkable')
-    const elem = usingFirstElement(res)
+    const elem = selectElement(res, field, this)
     const elementId = getElementId(elem)
     highlightActiveElement.call(this, elem)
 
@@ -1598,7 +1581,6 @@ class WebDriver extends Helper {
   /**
    * {{> see }}
    *
-   * {{ react }}
    */
   async see(text, context = null) {
     return proceedSee.call(this, 'assert', text, context)
@@ -1614,7 +1596,6 @@ class WebDriver extends Helper {
   /**
    * {{> dontSee }}
    *
-   * {{ react }}
    */
   async dontSee(text, context = null) {
     return proceedSee.call(this, 'negate', text, context)
@@ -1656,7 +1637,6 @@ class WebDriver extends Helper {
 
   /**
    * {{> seeElement }}
-   * {{ react }}
    *
    */
   async seeElement(locator, context = null) {
@@ -1673,7 +1653,6 @@ class WebDriver extends Helper {
 
   /**
    * {{> dontSeeElement }}
-   * {{ react }}
    */
   async dontSeeElement(locator, context = null) {
     const locateFn = prepareLocateFn.call(this, context)
@@ -1758,7 +1737,6 @@ class WebDriver extends Helper {
 
   /**
    * {{> seeNumberOfElements }}
-   * {{ react }}
    */
   async seeNumberOfElements(locator, num) {
     const res = await this._locate(locator)
@@ -1767,7 +1745,6 @@ class WebDriver extends Helper {
 
   /**
    * {{> seeNumberOfVisibleElements }}
-   * {{ react }}
    */
   async seeNumberOfVisibleElements(locator, num) {
     const res = await this.grabNumberOfVisibleElements(locator)
@@ -2243,6 +2220,7 @@ class WebDriver extends Helper {
    * {{> pressKeyWithKeyNormalization }}
    */
   async pressKey(key) {
+    await checkFocusBeforePressKey(this, key)
     const modifiers = []
     if (Array.isArray(key)) {
       for (let k of key) {
@@ -2289,6 +2267,8 @@ class WebDriver extends Helper {
    * {{> type }}
    */
   async type(keys, delay = null) {
+    await checkFocusBeforeType(this)
+
     if (!Array.isArray(keys)) {
       keys = keys.toString()
       keys = keys.split('')
@@ -3301,6 +3281,19 @@ function assertElementExists(res, locator, prefix, suffix) {
 }
 
 function usingFirstElement(els) {
+  const rawIndex = store.currentStep?.opts?.elementIndex
+  if (rawIndex != null && els.length > 1) {
+    let elementIndex = rawIndex
+    if (elementIndex === 'first') elementIndex = 1
+    if (elementIndex === 'last') elementIndex = -1
+    if (Number.isInteger(elementIndex) && elementIndex !== 0) {
+      const idx = elementIndex > 0 ? elementIndex - 1 : els.length + elementIndex
+      if (idx >= 0 && idx < els.length) {
+        debug(`[Elements] Using element #${rawIndex} out of ${els.length}`)
+        return els[idx]
+      }
+    }
+  }
   if (els.length > 1) debug(`[Elements] Using first element out of ${els.length}`)
   return els[0]
 }
@@ -3473,7 +3466,7 @@ function isModifierKey(key) {
 }
 
 function highlightActiveElement(element) {
-  if (this.options.highlightElement && global.debugMode) {
+  if (this.options.highlightElement && store.debugMode) {
     highlightElement(element, this.browser)
   }
 }
@@ -3484,9 +3477,6 @@ function prepareLocateFn(context) {
     l = new Locator(l, 'css')
     return this._locate(context, true).then(async res => {
       assertElementExists(res, context, 'Context element')
-      if (l.react) {
-        return res[0].react$$(l.react, l.props || undefined)
-      }
       return res[0].$$(l.simplify())
     })
   }

package/lib/helper/errors/NonFocusedType.js

@@ -0,0 +1,8 @@
+class NonFocusedType extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'NonFocusedType'
+  }
+}
+
+export default NonFocusedType

package/lib/helper/extras/Download.js

@@ -0,0 +1,45 @@
+import fs from 'fs'
+import path from 'path'
+import minimatch from 'minimatch'
+import store from '../../store.js'
+import assert from 'assert'
+
+function getDownloadDir() {
+  return path.join(store.outputDir, 'downloads')
+}
+
+function getNewFiles(downloadDir, sinceTimestamp) {
+  if (!fs.existsSync(downloadDir)) return []
+  return fs.readdirSync(downloadDir).filter(name => {
+    const stat = fs.statSync(path.join(downloadDir, name))
+    return stat.isFile() && stat.mtimeMs >= sinceTimestamp
+  })
+}
+
+function seeFileDownloaded(arg) {
+  const downloadDir = getDownloadDir()
+  const files = getNewFiles(downloadDir, this._downloadStartTimestamp)
+
+  if (arg === undefined || arg === null) {
+    assert.ok(files.length > 0, `No files downloaded to ${downloadDir}`)
+    return
+  }
+  if (typeof arg === 'number') {
+    assert.strictEqual(files.length, arg, `Expected ${arg} downloaded file(s), found ${files.length}: [${files.join(', ')}]`)
+    return
+  }
+  const regexMatch = arg.match(/^\/(.+)\/$/)
+  if (regexMatch) {
+    const re = new RegExp(regexMatch[1])
+    assert.ok(files.some(f => re.test(f)), `No file matches ${arg}. Downloaded: [${files.join(', ')}]`)
+    return
+  }
+  if (/[*?[\]]/.test(arg)) {
+    const matched = minimatch.match(files, arg)
+    assert.ok(matched.length > 0, `No file matches glob "${arg}". Downloaded: [${files.join(', ')}]`)
+    return
+  }
+  assert.ok(files.includes(arg), `File "${arg}" not downloaded. Downloaded: [${files.join(', ')}]`)
+}
+
+export { seeFileDownloaded, getDownloadDir }

package/lib/helper/extras/PlaywrightLocator.js

@@ -0,0 +1,10 @@
+async function findByPlaywrightLocator(matcher, locator) {
+  const pwLocator = locator.locator || locator
+  if (pwLocator && pwLocator.toString && pwLocator.toString().includes(process.env.testIdAttribute)) {
+    return matcher.getByTestId(pwLocator.pw.value.split('=')[1])
+  }
+  const pwValue = typeof pwLocator.pw === 'string' ? pwLocator.pw : pwLocator.pw
+  return matcher.locator(pwValue).all()
+}
+
+export { findByPlaywrightLocator }

package/lib/helper/extras/elementSelection.js

@@ -0,0 +1,58 @@
+import store from '../../store.js'
+import output from '../../output.js'
+import WebElement from '../../element/WebElement.js'
+import MultipleElementsFound from '../errors/MultipleElementsFound.js'
+
+function resolveElementIndex(value) {
+  if (value === 'first') return 1
+  if (value === 'last') return -1
+  return value
+}
+
+function isStrictStep(opts, helper) {
+  if (opts?.exact === true || opts?.strictMode === true) return true
+  if (opts?.exact === false || opts?.strictMode === false) return false
+  return helper.options.strict
+}
+
+function selectElement(els, locator, helper) {
+  const opts = store.currentStep?.opts
+  const rawIndex = opts?.elementIndex
+  const elementIndex = resolveElementIndex(rawIndex)
+
+  if (elementIndex != null) {
+    if (els.length === 1) return els[0]
+
+    if (!Number.isInteger(elementIndex) || elementIndex === 0) {
+      throw new Error(`elementIndex must be a non-zero integer or 'first'/'last', got: ${rawIndex}`)
+    }
+
+    let idx
+    if (elementIndex > 0) {
+      idx = elementIndex - 1
+      if (idx >= els.length) {
+        throw new Error(`elementIndex ${elementIndex} exceeds the number of elements found (${els.length}) for "${locator}"`)
+      }
+    } else {
+      idx = els.length + elementIndex
+      if (idx < 0) {
+        throw new Error(`elementIndex ${elementIndex} exceeds the number of elements found (${els.length}) for "${locator}"`)
+      }
+    }
+
+    output.debug(`[Elements] Using element #${elementIndex} out of ${els.length}`)
+    return els[idx]
+  }
+
+  if (isStrictStep(opts, helper)) {
+    if (els.length > 1) {
+      const webElements = Array.from(els).map(el => new WebElement(el, helper))
+      throw new MultipleElementsFound(locator, webElements)
+    }
+  }
+
+  if (els.length > 1) output.debug(`[Elements] Using first element out of ${els.length}`)
+  return els[0]
+}
+
+export { selectElement }

package/lib/helper/extras/focusCheck.js

@@ -0,0 +1,43 @@
+import store from '../../store.js'
+import NonFocusedType from '../errors/NonFocusedType.js'
+
+const MODIFIER_PATTERN = /^(control|ctrl|meta|cmd|command|commandorcontrol|ctrlorcommand)/i
+const EDITING_KEYS = new Set(['a', 'c', 'x', 'v', 'z', 'y'])
+
+async function isNoElementFocused(helper) {
+  return helper.executeScript(() => {
+    const ae = document.activeElement
+    return !ae || ae === document.documentElement || (ae === document.body && !ae.isContentEditable)
+  })
+}
+
+export async function checkFocusBeforeType(helper) {
+  if (!helper.options.strict && !store.debugMode) return
+  if (!await isNoElementFocused(helper)) return
+
+  const message = 'No element is in focus. Use I.click() or I.focus() to activate an element before typing.'
+  if (helper.options.strict) throw new NonFocusedType(message)
+  helper.debugSection('Warning', message)
+}
+
+export async function checkFocusBeforePressKey(helper, originalKey) {
+  if (!helper.options.strict && !store.debugMode) return
+  if (!Array.isArray(originalKey)) return
+
+  let hasCtrlOrMeta = false
+  let actionKey = null
+  for (const k of originalKey) {
+    if (MODIFIER_PATTERN.test(k)) {
+      hasCtrlOrMeta = true
+    } else {
+      actionKey = k
+    }
+  }
+  if (!hasCtrlOrMeta || !actionKey || !EDITING_KEYS.has(actionKey.toLowerCase())) return
+
+  if (!await isNoElementFocused(helper)) return
+
+  const message = `No element is in focus. Key combination with "${originalKey.join('+')}" may not work as expected. Use I.click() or I.focus() first.`
+  if (helper.options.strict) throw new NonFocusedType(message)
+  helper.debugSection('Warning', message)
+}

package/lib/helper/extras/richTextEditor.js

@@ -0,0 +1,178 @@
+import WebElement from '../../element/WebElement.js'
+
+const MARKER = 'data-codeceptjs-rte-target'
+
+const EDITOR = {
+  STANDARD: 'standard',
+  IFRAME: 'iframe',
+  CONTENTEDITABLE: 'contenteditable',
+  HIDDEN_TEXTAREA: 'hidden-textarea',
+  UNREACHABLE: 'unreachable',
+}
+
+function detectAndMark(el, opts) {
+  const marker = opts.marker
+  const kinds = opts.kinds
+  const CE = '[contenteditable="true"], [contenteditable=""]'
+
+  function mark(kind, target) {
+    document.querySelectorAll('[' + marker + ']').forEach(n => n.removeAttribute(marker))
+    if (target && target.nodeType === 1) target.setAttribute(marker, '1')
+    return kind
+  }
+
+  if (!el || el.nodeType !== 1) return mark(kinds.STANDARD, el)
+
+  const tag = el.tagName
+  if (tag === 'IFRAME') return mark(kinds.IFRAME, el)
+  if (el.isContentEditable) return mark(kinds.CONTENTEDITABLE, el)
+
+  const isFormHidden = tag === 'INPUT' && el.type === 'hidden'
+  if ((tag === 'INPUT' || tag === 'TEXTAREA') && !isFormHidden) {
+    const style = window.getComputedStyle(el)
+    if (style.display === 'none') return mark(kinds.UNREACHABLE, el)
+  }
+
+  const canSearchDescendants = tag !== 'INPUT' && tag !== 'TEXTAREA'
+  if (canSearchDescendants) {
+    const iframe = el.querySelector('iframe')
+    if (iframe) return mark(kinds.IFRAME, iframe)
+    const ce = el.querySelector(CE)
+    if (ce) return mark(kinds.CONTENTEDITABLE, ce)
+    const textareas = [...el.querySelectorAll('textarea')]
+    const focusable = textareas.find(t => window.getComputedStyle(t).display !== 'none')
+    const textarea = focusable || textareas[0]
+    if (textarea) return mark(kinds.HIDDEN_TEXTAREA, textarea)
+  }
+
+  return mark(kinds.STANDARD, el)
+}
+
+function detectInsideFrame() {
+  const MARKER = 'data-codeceptjs-rte-target'
+  const CE = '[contenteditable="true"], [contenteditable=""]'
+  const CONTENTEDITABLE = 'contenteditable'
+  const HIDDEN_TEXTAREA = 'hidden-textarea'
+  const body = document.body
+  document.querySelectorAll('[' + MARKER + ']').forEach(n => n.removeAttribute(MARKER))
+
+  if (body.isContentEditable) return CONTENTEDITABLE
+
+  const ce = body.querySelector(CE)
+  if (ce) {
+    ce.setAttribute(MARKER, '1')
+    return CONTENTEDITABLE
+  }
+
+  const textareas = [...body.querySelectorAll('textarea')]
+  const focusable = textareas.find(t => window.getComputedStyle(t).display !== 'none')
+  const textarea = focusable || textareas[0]
+  if (textarea) {
+    textarea.setAttribute(MARKER, '1')
+    return HIDDEN_TEXTAREA
+  }
+
+  return CONTENTEDITABLE
+}
+
+async function evaluateInFrame(helper, body, fn) {
+  if (body.helperType === 'webdriver') {
+    return helper.executeScript(fn)
+  }
+  return body.element.evaluate(fn)
+}
+
+function focusMarkedInFrameScript() {
+  const el = document.querySelector('[data-codeceptjs-rte-target]') || document.body
+  el.focus()
+  return document.activeElement === el
+}
+
+function selectAllInFrameScript() {
+  const el = document.querySelector('[data-codeceptjs-rte-target]') || document.body
+  el.focus()
+  const range = document.createRange()
+  range.selectNodeContents(el)
+  const sel = window.getSelection()
+  sel.removeAllRanges()
+  sel.addRange(range)
+  return document.activeElement === el
+}
+
+function selectAllInEditable(el) {
+  const doc = el.ownerDocument
+  const win = doc.defaultView
+  el.focus()
+  const range = doc.createRange()
+  range.selectNodeContents(el)
+  const sel = win.getSelection()
+  sel.removeAllRanges()
+  sel.addRange(range)
+}
+
+function unmarkAll(marker) {
+  document.querySelectorAll('[' + marker + ']').forEach(n => n.removeAttribute(marker))
+}
+
+function isActive(el) {
+  return el.ownerDocument.activeElement === el
+}
+
+async function assertFocused(target) {
+  const focused = await target.evaluate(isActive)
+  if (!focused) {
+    throw new Error('fillField: rich editor target did not accept focus. Locator must point at the visible editor surface (a wrapper, iframe, or contenteditable) — not a hidden backing element.')
+  }
+}
+
+async function findMarked(helper) {
+  const root = helper.page || helper.browser
+  const raw = await root.$('[' + MARKER + ']')
+  return new WebElement(raw, helper)
+}
+
+async function clearMarker(helper) {
+  if (helper.page) return helper.page.evaluate(unmarkAll, MARKER)
+  return helper.executeScript(unmarkAll, MARKER)
+}
+
+export async function fillRichEditor(helper, el, value) {
+  const source = el instanceof WebElement ? el : new WebElement(el, helper)
+  const kind = await source.evaluate(detectAndMark, { marker: MARKER, kinds: EDITOR })
+  if (kind === EDITOR.STANDARD) return false
+  if (kind === EDITOR.UNREACHABLE) {
+    throw new Error('fillField: cannot fill a display:none form control. Locator must point at the visible editor surface (a wrapper, iframe, or contenteditable).')
+  }
+
+  const target = await findMarked(helper)
+  const delay = helper.options.pressKeyDelay
+
+  if (kind === EDITOR.IFRAME) {
+    await target.inIframe(async body => {
+      const innerKind = await evaluateInFrame(helper, body, detectInsideFrame)
+      if (innerKind === EDITOR.HIDDEN_TEXTAREA) {
+        const focused = await evaluateInFrame(helper, body, focusMarkedInFrameScript)
+        if (!focused) throw new Error('fillField: rich editor target inside iframe did not accept focus.')
+        await body.selectAllAndDelete()
+        await body.typeText(value, { delay })
+      } else {
+        const focused = await evaluateInFrame(helper, body, selectAllInFrameScript)
+        if (!focused) throw new Error('fillField: rich editor target inside iframe did not accept focus.')
+        await body.typeText(value, { delay })
+      }
+    })
+  } else if (kind === EDITOR.HIDDEN_TEXTAREA) {
+    await target.focus()
+    await assertFocused(target)
+    await target.selectAllAndDelete()
+    await target.typeText(value, { delay })
+  } else if (kind === EDITOR.CONTENTEDITABLE) {
+    await target.click()
+    await target.evaluate(selectAllInEditable)
+    await assertFocused(target)
+    await target.typeText(value, { delay })
+  }
+
+  await clearMarker(helper)
+  return true
+}