codeceptjs 4.2.0-beta.4 → 4.2.1-beta.1

package/lib/helper/CDPBrowser.js

@@ -1,3 +1,5 @@
+import { spawn } from 'child_process'
+import net from 'net'
 import path from 'path'
 import fs from 'fs'
 import axios from 'axios'
@@ -7,7 +9,7 @@ import installCodeceptClient from './clientscripts/cdpBrowserClient.js'
 import xpathPolyfillSource from './clientscripts/xpathPolyfill.js'
 import Locator from '../locator.js'
 import store from '../store.js'
-import { xpathLocator, normalizePath, resolveUrl, toCamelCase, convertCssPropertiesToCamelCase, normalizeSpacesInString, fileExists, base64EncodeFile, getMimeType } from '../utils.js'
+import { xpathLocator, normalizePath, resolveUrl, toCamelCase, convertCssPropertiesToCamelCase, normalizeSpacesInString, fileExists, base64EncodeFile, getMimeType, isFile, isWindows } from '../utils.js'
 import ElementNotFound from './errors/ElementNotFound.js'
 import MultipleElementsFound from './errors/MultipleElementsFound.js'
 import { includes as stringIncludes } from '../assert/include.js'
@@ -18,6 +20,7 @@ import { isColorProperty, convertColorToRGBA } from '../colorUtils.js'
 import WebElement from '../element/WebElement.js'
 import CDPElementHandle from './extras/CDPElementHandle.js'
 import { checkFocusBeforeType, checkFocusBeforePressKey } from './extras/focusCheck.js'
+import { CLIPBOARD_READ_TIMEOUT_MS, readClipboardScript, writeClipboardScript, clipboardExpression } from './extras/clipboard.js'
 import { dontSeeTraffic, seeTraffic, grabRecordedNetworkTraffics, flushNetworkTraffics } from './network/actions.js'
 import { assembleApng, isPng } from './extras/apngAssembler.js'
 
@@ -29,16 +32,16 @@ import { assembleApng, isPng } from './extras/apngAssembler.js'
  * @typedef CDPBrowserConfig
  * @type {object}
  * @prop {string} [url=http://localhost] - base url of website to be tested.
- * @prop {string} [endpoint=http://127.0.0.1:9222] - Chrome DevTools Protocol endpoint. Either an `http(s)://` address exposing `/json/version` (from which the `webSocketDebuggerUrl` is resolved) or a raw `ws(s)://` debugger URL.
- * @prop {object} [headers={}] - headers sent with the endpoint resolution request and the WebSocket handshake. Useful for authenticated remote browser providers.
- * @prop {string} [input=auto] - how synthetic user actions (click, fill, etc.) are dispatched by helpers built on top of this class. `auto` picks `cdp` when a real layout engine is detected and `synthetic` otherwise; can be pinned to `cdp` or `synthetic`.
- * @prop {string|boolean} [xpathPolyfill=auto] - whether to inject the bundled XPath polyfill before installing the in-page client. `auto` probes the page and only injects when `document.evaluate` is unavailable or broken; `true`/`false` force the behavior.
- * @prop {object} [capabilities={}] - pre-seed detected browser capabilities (`layout`, `xpath`, `screenshot`, `innerText`) to skip runtime probing. Values set here are never overwritten by `_probeCapabilities`/`_ensureClient`.
- * @prop {number} [waitForTimeout=5] - default wait* timeout in seconds, used by helpers built on top of this class.
- * @prop {number} [waitForAction=100] - only takes effect when set explicitly: a literal fixed pacing sleep (in milliseconds) after click, type, or other interactions, mirroring other browser helpers. Left unset, actions settle in an event-aware way instead — near-instant when nothing navigates, waiting for the navigation to actually finish (not a guessed fixed delay) when one does.
- * @prop {number} [pollInterval=25] - interval in milliseconds between retries while polling for a condition (e.g. page ready state, `waitFor*`). Distinct from `waitForAction`.
- * @prop {number} [getPageTimeout=30] - maximum time in seconds to wait for a page to finish loading after navigation or reload; also used as the CDP command timeout (in ms, x1000).
- * @prop {string} [waitForNavigation=load] - when to consider a navigation finished: `load`, `domcontentloaded`, or `networkidle`. Mirrors the Puppeteer helper's option name. `networkidle` waits for the CDP `networkIdle` lifecycle event, which on a busy page can lag `load` by a second or more — only opt in if the extra wait is actually needed.
+ * @prop {string} [endpoint=http://127.0.0.1:9222] - Chrome DevTools Protocol endpoint: an `http(s)://` address or a `ws(s)://` debugger URL.
+ * @prop {object} [headers={}] - headers sent when connecting to the endpoint, e.g. for authenticated remote browsers.
+ * @prop {string} [input=auto] - how actions are dispatched: `cdp` (real mouse and keyboard events) or `synthetic` (DOM events). `auto` picks `cdp` when the browser renders layout.
+ * @prop {string|boolean} [xpathPolyfill=auto] - inject an XPath polyfill for browsers with incomplete XPath support. `auto` detects when it is needed.
+ * @prop {object} [capabilities={}] - browser capabilities (`layout`, `xpath`, `screenshot`, `innerText`) to use instead of detecting them at runtime.
+ * @prop {number} [waitForTimeout=5] - default timeout for wait* actions, in seconds.
+ * @prop {number} [waitForAction] - fixed delay after each action, in milliseconds. When unset, actions wait only for the navigation they trigger.
+ * @prop {number} [pollInterval=25] - interval between checks while waiting, in milliseconds.
+ * @prop {number} [getPageTimeout=30] - maximum time to wait for a page to load, in seconds.
+ * @prop {string} [waitForNavigation=load] - when a navigation is considered finished: `load`, `domcontentloaded`, or `networkidle`.
  */
 const config = {}
 
@@ -82,6 +85,8 @@ const ACTION_SETTLE_GRACE_MS = 20
  * script evaluation, and simple in-page element interaction (installed lazily through the
  * `window.__codecept` client script). It does not launch a browser itself — point `endpoint` at an
  * already-running Chrome (or any CDP-compatible browser) started with `--remote-debugging-port`.
+ * Subclasses for browsers shipped as a standalone binary opt into launching and reaping their own
+ * server process through `_manageServer`.
  *
  * ## Example
  *
@@ -124,6 +129,12 @@ class CDPBrowser extends Helper {
     this.cdp = null
     this.sessionId = null
     this.targetId = null
+    this.mode = 'attach'
+    this.server = null
+    this.serverProcess = null
+    this.serverError = null
+    this.binaryPath = null
+    this._selfManagedResolved = false
     this.capabilities = { layout: null, xpath: null, screenshot: null, innerText: null, ...this.options.capabilities }
     this.withinCandidates = null
     this.requests = []
@@ -142,24 +153,8 @@ class CDPBrowser extends Helper {
     this._waitForActionExplicit = config?.waitForAction !== undefined
   }
 
-  /**
-   * No-op hook kept for interface parity with other browser helpers. Connecting to the CDP
-   * endpoint is deferred to `_before`, since a fresh target/session is opened per test.
-   */
   _init() {}
 
-  /**
-   * Resolves `options.endpoint` to a raw WebSocket debugger URL. If the configured endpoint is
-   * an `http(s)://` address, this fetches `/json/version` from it and reads `webSocketDebuggerUrl`
-   * from the response, matching the discovery flow exposed by Chrome's `--remote-debugging-port`.
-   * A `ws(s)://` endpoint is returned unchanged.
-   *
-   * This is the subclass override point for helpers that connect through a different discovery
-   * mechanism (e.g. a cloud browser provider with its own session-creation API).
-   *
-   * @returns {Promise<string>} a `ws(s)://` debugger URL ready to be passed to `CDPConnection`.
-   * @protected
-   */
   async _resolveEndpoint() {
     let endpoint = this.options.endpoint
     if (endpoint.startsWith('http')) {
@@ -170,32 +165,198 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Resolves the CDP endpoint and opens the underlying `CDPConnection`, storing it on `this.cdp`.
+   * Opts a subclass into managing its own browser server process. Called from a subclass
+   * constructor with the raw user config and a server descriptor:
+   *
+   * - `name` — binary name looked up on `PATH`, also used in messages
+   * - `envVar` — environment variable that may point at the binary
+   * - `args(port)` — arguments the binary is spawned with to serve CDP on `port`
+   * - `env` — extra environment variables for the spawned process
+   * - `releases` — URL shown when no binary can be resolved
    *
+   * An explicit `endpoint` in the user config always wins: the helper stays in ATTACH mode and
+   * never spawns or kills anything. Otherwise the helper becomes SELF-MANAGED and the default
+   * `endpoint` is cleared until `_resolveSelfManaged` sets the real one.
+   *
+   * @param {object} config - the config object the helper was constructed with.
+   * @param {object} server - the server descriptor described above.
    * @protected
    */
-  async _connect() {
-    const endpoint = await this._resolveEndpoint()
-    this.cdp = new CDPConnection(endpoint, { headers: this.options.headers, timeout: this.options.getPageTimeout * 1000 })
-    await this.cdp.connect()
+  _manageServer(config, server) {
+    if (config && config.endpoint) return
+    this.mode = 'self-managed'
+    this.options.endpoint = null
+    this.server = server
+  }
+
+  /**
+   * Resolves how to reach a SELF-MANAGED browser, trying, in order: spawn a binary
+   * (`binaryPath` config, then the descriptor's `envVar`, then its `name` on `PATH`) on
+   * `options.port` or a free port, courtesy-attach to `http://127.0.0.1:9222` if something already
+   * answers there (never killed by this helper), or throw a loud, actionable error. Sets
+   * `this.options.endpoint` as a side effect.
+   *
+   * A spawn failure (e.g. a bad binary) is delivered asynchronously by Node as an `error` event;
+   * it is recorded on `this.serverError` and surfaced as a rejection from `_waitForServer` instead
+   * of crashing the process as an uncaught exception.
+   *
+   * @protected
+   */
+  async _resolveSelfManaged() {
+    const { name, envVar, args, env, releases } = this.server
+    const helperName = this.constructor.name
+    const binaryPath = this._resolveBinary()
+    if (binaryPath) {
+      this.binaryPath = binaryPath
+      const port = this.options.port || (await this._findFreePort())
+      this.options.port = port
+      this.serverError = null
+      this.serverProcess = spawn(binaryPath, args(port), { stdio: 'ignore', env: { ...process.env, ...env } })
+      this.serverProcess.on('error', err => {
+        this.serverError = err
+      })
+      await this._waitForServer()
+      this.options.endpoint = `http://127.0.0.1:${port}`
+      return
+    }
+    if (await this._probeUp('http://127.0.0.1:9222/json/version')) {
+      this.debugSection(helperName, `no binaryPath/${envVar}/${name}-on-PATH found — courtesy-attaching to an already-running ${name} on 127.0.0.1:9222 (this helper will not manage or kill it)`)
+      this.options.endpoint = 'http://127.0.0.1:9222'
+      return
+    }
+    throw new Error(
+      [
+        `${helperName} has no endpoint configured, no binary could be resolved (checked config.binaryPath, ${envVar}, and PATH), and nothing answered http://127.0.0.1:9222/json/version.`,
+        `Start it yourself:  ${name} ${args(9222).join(' ')}`,
+        `Or let this helper launch it: put a release binary on PATH, set ${envVar}=/path/to/${name}, or pass binaryPath in the config.`,
+        `Releases: ${releases}`,
+      ].join('\n  '),
+    )
+  }
+
+  /**
+   * Resolves the binary to spawn, in priority order: `options.binaryPath`, then the server
+   * descriptor's environment variable, then its name on `PATH`. The `PATH` lookup walks the
+   * directories itself instead of shelling out to `which`, which does not exist on Windows: on
+   * Windows every `PATHEXT` suffix is tried, so a `.exe` on `PATH` is found too.
+   *
+   * @returns {string|null} an absolute or relative path to the binary, or null if none resolved.
+   * @protected
+   */
+  _resolveBinary() {
+    const { name, envVar } = this.server
+    if (this.options.binaryPath) return this.options.binaryPath
+    if (process.env[envVar]) return process.env[envVar]
+    const windows = isWindows()
+    const extensions = windows ? (process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';') : ['']
+    for (const entry of (process.env.PATH || '').split(path.delimiter)) {
+      const dir = windows ? entry.replace(/^"|"$/g, '') : entry
+      if (!dir) continue
+      for (const extension of extensions) {
+        const candidate = path.join(dir, `${name}${extension}`)
+        if (!isFile(candidate)) continue
+        try {
+          fs.accessSync(candidate, fs.constants.X_OK)
+          return candidate
+        } catch (e) {
+          continue
+        }
+      }
+    }
+    return null
+  }
+
+  /**
+   * Picks a free TCP port on 127.0.0.1 by briefly listening on port 0 and reading back the
+   * OS-assigned port. Used when `options.port` isn't explicitly set, so multiple `run-workers`
+   * workers never collide on the same port.
+   *
+   * @returns {Promise<number>} a free port.
+   * @protected
+   */
+  async _findFreePort() {
+    return new Promise((resolve, reject) => {
+      const srv = net.createServer()
+      srv.unref()
+      srv.on('error', reject)
+      srv.listen(0, '127.0.0.1', () => {
+        const { port } = srv.address()
+        srv.close(() => resolve(port))
+      })
+    })
   }
 
   /**
-   * Hook executed before each test. Ensures a live `CDPConnection` exists (connecting lazily on
-   * first use, and reconnecting if a previous connection was closed), then creates a fresh
-   * `about:blank` target and attaches to it with `Target.attachToTarget`, storing `this.targetId`
-   * and `this.sessionId`. `Page` and `Runtime` domains are enabled on the new session, and engine
-   * capabilities are probed here (against `about:blank`, uncontended) rather than only lazily on
-   * the first real page — see `_probeCapabilities`.
+   * Probes a `/json/version`-style URL with a short timeout, used for the courtesy-attach check.
    *
-   * Also resets `_navStartWaiters` and `_lastMainFrameNav`: both are scoped to a single
-   * `sessionId`/`targetId`, which are about to change, so anything left over from the previous test
-   * (e.g. an action-settle waiter still armed because its test threw between arming and settling)
-   * can never legitimately resolve against the new session — better to drop it here than leave it
-   * waiting for the rest of the run.
+   * @param {string} url
+   * @returns {Promise<boolean>} true if the URL answered.
+   * @protected
+   */
+  async _probeUp(url) {
+    try {
+      await axios.get(url, { timeout: 1000 })
+      return true
+    } catch (e) {
+      return false
+    }
+  }
+
+  /**
+   * Polls `http://127.0.0.1:<port>/json/version` until the spawned server responds,
+   * `this.serverError` is set by the process' `error` event, or `options.serverStartTimeout`
+   * elapses. The process typically comes up within tens of milliseconds — a 20ms retry interval
+   * keeps the wasted tail after the server is actually ready small, since this cost is paid once
+   * per run and counts directly toward real-world startup latency.
    *
    * @protected
    */
+  async _waitForServer() {
+    const { name } = this.server
+    const timeout = this.options.serverStartTimeout || 15000
+    const deadline = Date.now() + timeout
+    while (Date.now() < deadline) {
+      if (this.serverError) {
+        throw new Error(`Failed to start ${name} at ${this.binaryPath}: ${this.serverError.message}`)
+      }
+      try {
+        await axios.get(`http://127.0.0.1:${this.options.port}/json/version`, { timeout: Math.min(1000, deadline - Date.now()) })
+        return
+      } catch (e) {
+        await new Promise(r => setTimeout(r, 20))
+      }
+    }
+    if (this.serverError) {
+      throw new Error(`Failed to start ${name} at ${this.binaryPath}: ${this.serverError.message}`)
+    }
+    throw new Error(`${name} did not start on port ${this.options.port} within ${timeout}ms`)
+  }
+
+  /**
+   * In SELF-MANAGED mode, resolves and spawns the browser server (or courtesy-attaches to an
+   * already-running one on :9222) exactly once via `_resolveSelfManaged`. Then resolves the CDP
+   * endpoint and opens the underlying `CDPConnection`, storing it on `this.cdp`.
+   *
+   * @protected
+   */
+  async _connect() {
+    if (this.server) {
+      if (this._selfManagedError) throw this._selfManagedError
+      if (!this._selfManagedResolved) {
+        this._selfManagedResolved = true
+        try {
+          await this._resolveSelfManaged()
+        } catch (err) {
+          this._selfManagedError = err
+          throw err
+        }
+      }
+    }
+    const endpoint = await this._resolveEndpoint()
+    this.cdp = new CDPConnection(endpoint, { headers: this.options.headers, timeout: this.options.getPageTimeout * 1000 })
+    await this.cdp.connect()
+  }
+
   async _before() {
     if (!this.cdp || !this.cdp.isConnected) await this._connect()
     this._navStartWaiters = []
@@ -210,33 +371,6 @@ class CDPBrowser extends Helper {
     await this._probeCapabilities()
   }
 
-  /**
-   * Lazily installs a single, persistent `Page.lifecycleEvent` listener on the underlying
-   * `CDPConnection` and drains it into whichever `_waitForLoadEvent` calls are currently pending,
-   * matched by `loaderId`. Installed once per helper instance (the connection outlives individual
-   * tests), never removed — `CDPConnection` has no listener-removal API, so a single persistent
-   * dispatcher (rather than one listener per navigation) is what keeps this leak-free.
-   *
-   * Also, for the main frame (`params.frameId === this.targetId`, which holds for a page target's
-   * own top-level frame) only:
-   * - Drains `_navStartWaiters` (armed by `_armActionSettle`, before an action, for `_waitForAction`'s
-   *   event-aware settle) on an `'init'` event — confirmed via a raw probe (against both Obscura and
-   *   Chrome, through the actual CLI path) to be the earliest signal CDP emits when a new top-level
-   *   navigation begins. Arming happens *before* the action is dispatched, not after: the same probe
-   *   found `'init'` can arrive while the action's own CDP round trip is still in flight, sometimes
-   *   only a millisecond or two after it started — a listener installed only once the action's
-   *   promise resolves can already be too late, not merely unlucky.
-   * - Maintains `_lastMainFrameNav`, a rolling `{loaderId, events}` record of every lifecycle event
-   *   name seen for the current main-frame navigation (reset whenever `loaderId` changes). On a
-   *   fast/local navigation, the same raw probe found the *entire* sequence — `init` through
-   *   `networkIdle` — arriving as one batch while the triggering action's own round trip was still
-   *   in flight. Without this cache, `_waitForAction` would correctly detect that a navigation
-   *   started, then arm a *fresh* wait for the `load` event specifically — which, in that common
-   *   case, had already fired and will never fire again, paying the full grace-window-plus-poll cost
-   *   of `_waitForPageLoad` on every single navigating action instead of settling immediately.
-   *
-   * @protected
-   */
   _ensureLifecycleListener() {
     if (this._lifecycleListenerInstalled) return
     this._lifecycleListenerInstalled = true
@@ -260,24 +394,6 @@ class CDPBrowser extends Helper {
     })
   }
 
-  /**
-   * Starts waiting for a `Page.lifecycleEvent` named `eventName` for the given `loaderId` on the
-   * current session. `loaderId` (from the `Page.navigate` response) discriminates the awaited
-   * navigation from any other in-flight or stale lifecycle events (e.g. the `about:blank` target
-   * created in `_before`), which is essential since Chrome emits the target's initial `about:blank`
-   * lifecycle sequence asynchronously, sometimes after this listener is already installed.
-   *
-   * Returns a `{promise, cancel}` pair rather than a bare promise: `_waitForPageLoad` races this
-   * against a readyState poll, and whichever side loses must be actively torn down (not just have
-   * its rejection swallowed) — an abandoned-but-still-pending wait would sit in `_pageLoadWaiters`
-   * for the full timeout on every single navigation, for no purpose.
-   *
-   * @param {string} loaderId - the loader id of the navigation to wait for, from `Page.navigate`'s response.
-   * @param {string} eventName - the `Page.lifecycleEvent` name to wait for (e.g. `load`, `DOMContentLoaded`, `networkIdle`).
-   * @param {number} timeoutSec - maximum time to wait, in seconds.
-   * @returns {{promise: Promise<void>, cancel: function}}
-   * @protected
-   */
   _waitForLoadEvent(loaderId, eventName, timeoutSec) {
     this._ensureLifecycleListener()
     let waiter
@@ -303,19 +419,6 @@ class CDPBrowser extends Helper {
     return { promise, cancel: () => waiter.cancel() }
   }
 
-  /**
-   * Arms the event-aware settle's navigation-start listener. Must be called *before* the action
-   * that might trigger a navigation is dispatched, not after — see `_ensureLifecycleListener` for
-   * why. Returns `null` when `options.waitForAction` was set explicitly, since `_waitForAction`
-   * ignores the armed listener entirely in that case (a literal fixed sleep, as before this round).
-   *
-   * No timeout here: `_waitForAction` applies the grace window itself, starting from when *it*
-   * runs (after the action's own dispatch already resolved), racing this already-armed listener
-   * against a fresh timer instead of one that started ticking before the action even began.
-   *
-   * @returns {({promise: Promise<string|null>, cancel: function}|null)}
-   * @protected
-   */
   _armActionSettle() {
     if (this._waitForActionExplicit) return null
     this._ensureLifecycleListener()
@@ -327,30 +430,6 @@ class CDPBrowser extends Helper {
     return { promise, cancel: () => { this._navStartWaiters = this._navStartWaiters.filter(w => w !== waiter) } }
   }
 
-  /**
-   * Waits for a page to finish loading after `Page.navigate`/`Page.reload`, per `options.waitForNavigation`.
-   *
-   * Purely event-driven for the first `PAGE_LOAD_GRACE_MS`: only the push-based
-   * `Page.lifecycleEvent` signal (matched by `loaderId`) is awaited, issuing zero `_evaluate` calls
-   * — this matters because an `_evaluate` sent while the page's own JavaScript is still busy (e.g.
-   * a real-world page doing post-load hydration/analytics work) can queue behind it for hundreds of
-   * ms to multiple seconds, measured directly against a JS-heavy page. Only if the grace window
-   * elapses without the event (an engine that doesn't emit it, or a genuinely slow navigation) does
-   * the `document.readyState` poll (via `_poll`) start, racing the still-pending lifecycle wait —
-   * both bounded by the same `options.getPageTimeout`, so a lifecycle-less engine costs at most
-   * `PAGE_LOAD_GRACE_MS` more than the poll alone would have, never double the timeout. No
-   * `loaderId` (e.g. from `Page.reload`, which returns none) skips straight to the poll.
-   *
-   * Whichever side ultimately loses is actively cancelled, not merely abandoned — an abandoned poll
-   * or lifecycle wait would otherwise keep running (issuing readyState `_evaluate` calls every
-   * `pollInterval`, or holding a `_pageLoadWaiters` entry) for up to the full timeout on every
-   * navigation, competing for the same CDP connection with real work.
-   *
-   * @param {string|null} loaderId - loader id from the triggering `Page.navigate` response, if any.
-   * @param {string} timeoutMessage - error message used if the readyState poll times out.
-   * @returns {Promise<void>}
-   * @protected
-   */
   async _waitForPageLoad(loaderId, timeoutMessage) {
     const waitUntil = READY_STATE_EXPR_BY_WAIT_UNTIL[this.options.waitForNavigation] ? this.options.waitForNavigation : 'load'
     const readyStateCheck = () => this._evaluate(READY_STATE_EXPR_BY_WAIT_UNTIL[waitUntil]).catch(() => false)
@@ -386,13 +465,6 @@ class CDPBrowser extends Helper {
     }
   }
 
-  /**
-   * Hook executed after each test. Closes the target opened in `_before` via `Target.closeTarget`
-   * and clears `this.targetId`/`this.sessionId`. The underlying `CDPConnection` is left open so it
-   * can be reused by the next test.
-   *
-   * @protected
-   */
   async _after() {
     if (!this.targetId) return
     await this.cdp.send('Target.closeTarget', { targetId: this.targetId }).catch(() => null)
@@ -402,26 +474,49 @@ class CDPBrowser extends Helper {
 
   /**
    * Hook executed after all tests are run. Closes the underlying `CDPConnection` (and its
-   * WebSocket) and clears `this.cdp`. Must leave no open sockets or pending timers behind, so the
-   * process can exit on its own.
+   * WebSocket) and clears `this.cdp`, then kills the server process spawned by
+   * `_resolveSelfManaged`, if any (`this.serverProcess` is never set when attaching). Must leave no
+   * open sockets, pending timers or child processes behind, so the process can exit on its own.
+   *
+   * The kill runs in a `finally` so the process is always reaped even if closing the CDP
+   * connection throws. It sends `SIGTERM` first and waits for the process to exit; a process that
+   * ignores `SIGTERM` is escalated to `SIGKILL` after 5s. The promise only resolves once the child
+   * has actually exited (confirmed via the `exit` event, not merely once `SIGKILL` was sent — the
+   * kernel needs a moment to reap it), with a final safety-net timeout so a stuck child can never
+   * keep the event loop alive even if that confirmation is somehow lost.
    *
    * @protected
    */
   async _finishTest() {
-    if (this.cdp) await this.cdp.close()
-    this.cdp = null
+    try {
+      if (this.cdp) await this.cdp.close()
+      this.cdp = null
+    } finally {
+      if (this.serverProcess) {
+        const proc = this.serverProcess
+        this.serverProcess = null
+        await new Promise(resolve => {
+          if (proc.exitCode !== null || proc.signalCode !== null) {
+            resolve()
+            return
+          }
+          let settled = false
+          const finish = () => {
+            if (settled) return
+            settled = true
+            clearTimeout(killTimer)
+            clearTimeout(safetyTimer)
+            resolve()
+          }
+          proc.once('exit', finish)
+          const killTimer = setTimeout(() => proc.kill('SIGKILL'), 5000)
+          const safetyTimer = setTimeout(finish, 5500)
+          proc.kill()
+        })
+      }
+    }
   }
 
-  /**
-   * Evaluates a JavaScript expression in the page attached to the current session via
-   * `Runtime.evaluate`, awaiting any returned promise and returning the value by reference
-   * (`returnByValue: true`). If the expression throws, the browser-side exception description
-   * (or fallback text) is re-thrown as a JS `Error`.
-   *
-   * @param {string} expression - a JavaScript expression (or IIFE) to run in the page context.
-   * @returns {Promise<any>} the evaluated value, or `undefined` if the expression has no result.
-   * @protected
-   */
   async _evaluate(expression) {
     const res = await this.cdp.send('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: true }, this.sessionId)
     if (res.exceptionDetails) {
@@ -431,39 +526,12 @@ class CDPBrowser extends Helper {
     return res.result ? res.result.value : undefined
   }
 
-  /**
-   * Ensures the in-page client (`window.__codecept`, installed from `cdpBrowserClient.js`) is
-   * present on the current page, installing it (and the XPath polyfill, if needed) exactly once.
-   * Safe to call repeatedly; it is a no-op once the client is detected.
-   *
-   * @protected
-   */
   async _ensureClient() {
     const installed = await this._evaluate(`typeof window.__codecept !== 'undefined'`)
     if (installed) return
     await this._installClient()
   }
 
-  /**
-   * Installs the in-page client unconditionally — no `typeof window.__codecept` presence check.
-   * Used by callers that already know, from a sentinel value returned alongside a failed action,
-   * that the client is missing on the current page, so re-checking would just be a redundant
-   * contended round trip.
-   *
-   * The 171KB XPath polyfill is only injected alongside the client when `needsXPath` is true (the
-   * default, for callers without candidate information) *and* the engine actually needs it
-   * (`capabilities.xpath === 'polyfill'`, cached from `_before`'s probe). Callers that know their
-   * candidates never resolve to an `xpath` strategy (e.g. `_runSelected`, once it has inspected
-   * `candidates`/`within`) can pass `false` to skip that inject — the client is still told, via the
-   * `xpathNeedsPolyfill` flag baked in at install time, that the *engine* will eventually need it,
-   * so a later call that does hit an xpath candidate gets a clean `'__NO_XPATH__'` miss signal
-   * (from `window.__codecept.run`) instead of silently falling through to a broken native
-   * `document.evaluate` — `_runSelected` reacts to that sentinel by injecting the polyfill and
-   * retrying once, mirroring the `'__NO_CLIENT__'` handling right next to it.
-   *
-   * @param {boolean} [needsXPath=true]
-   * @protected
-   */
   async _installClient(needsXPath = true) {
     const enginePolyfillNeeded = await this._needsXPathPolyfill()
     if (needsXPath && enginePolyfillNeeded) {
@@ -472,36 +540,12 @@ class CDPBrowser extends Helper {
     await this._evaluate(`(${installCodeceptClient.toString()})(${JSON.stringify(enginePolyfillNeeded)})`)
   }
 
-  /**
-   * Whether any candidate strategy — in `candidates` itself, or in any of the `within` scoping
-   * `layers` searched before it — is an `xpath` locator. Used to decide, before the client is even
-   * installed, whether the XPath polyfill needs to be bundled into that install or can be deferred.
-   *
-   * @param {?Array<{type: string, value: string}>} candidates
-   * @param {Array<Array<{type: string, value: string}>>} layers
-   * @returns {boolean}
-   * @protected
-   */
   _candidatesNeedXPath(candidates, layers) {
     const hasXPath = arr => Array.isArray(arr) && arr.some(c => c && c.type === 'xpath')
     if (hasXPath(candidates)) return true
     return layers.some(hasXPath)
   }
 
-  /**
-   * Determines whether the bundled XPath polyfill must be injected before the in-page client is
-   * installed. Honors an explicit `options.xpathPolyfill` boolean; otherwise reuses a previously
-   * probed `capabilities.xpath`, or probes the page's native `document.evaluate`. The probe appends
-   * two throwaway elements distinguished only by text content and asserts that a text-value XPath
-   * predicate (`normalize-space(string(.))=...`, the basis of every fuzzy/clickable locator) resolves
-   * to exactly the matching one — merely checking that `document.evaluate` runs without throwing is
-   * not enough, since some engines execute a text-value predicate without actually filtering by it,
-   * silently returning every candidate node instead of none or one. The result is cached on
-   * `capabilities.xpath` (`'native'` or `'polyfill'`).
-   *
-   * @returns {Promise<boolean>} `true` if the polyfill should be injected.
-   * @protected
-   */
   async _needsXPathPolyfill() {
     if (this.options.xpathPolyfill === true) return true
     if (this.options.xpathPolyfill === false) return false
@@ -526,18 +570,6 @@ class CDPBrowser extends Helper {
     return !ok
   }
 
-  /**
-   * Determines whether `see`/`dontSee`/`waitForText` should read whole-page text through the
-   * client's own visibility-aware `visibleText()` walker instead of the native
-   * `document.body.innerText`. Probes once per page by appending a `display:none` element and a
-   * `<script>` element, each with distinguishing text, and checking that native `innerText`
-   * excludes both — some engines return an `innerText` that does not honor computed visibility or
-   * exclude script/style content, even when `getComputedStyle`/layout are otherwise reliable. The
-   * result is cached on `capabilities.innerText` (`'native'` or `'computed'`).
-   *
-   * @returns {Promise<boolean>} `true` if the `visibleText()` fallback should be used.
-   * @protected
-   */
   async _needsVisibleTextFallback() {
     if (this.capabilities.innerText) return this.capabilities.innerText === 'computed'
     const ok = await this._evaluate(`(function(){
@@ -561,27 +593,6 @@ class CDPBrowser extends Helper {
     return !ok
   }
 
-  /**
-   * Probes and caches capabilities that depend on the actual browser *engine* rather than any
-   * particular page's content: `capabilities.layout` (via `getComputedStyle`), `capabilities.screenshot`
-   * (inferred from `layout`), `capabilities.xpath` (via `_needsXPathPolyfill`), and
-   * `capabilities.innerText` (via `_needsVisibleTextFallback`). Already-known capabilities
-   * (pre-seeded through `options.capabilities`, or probed earlier) are never re-probed — so, across
-   * a whole run, this issues a handful of `_evaluate` calls exactly once and is a no-op afterward.
-   *
-   * Called from `_before`, against the fresh `about:blank` target created there, specifically so
-   * these probes run before any real navigation — measured directly (a full stall ledger against
-   * `github.com`) that running them on the first *real* page instead can cost seconds each, since
-   * every one is an `_evaluate` competing with that page's own JavaScript for the V8 isolate.
-   * `about:blank` has no such competition. Also called (cheaply, already cached by then) from
-   * `amOnPage`, so a helper that skips `_before` for some reason still probes correctly.
-   *
-   * The `xpath`/`innerText` probes determine *whether* their respective fallback is needed; they
-   * do not install anything — injection stays deferred to `_ensureClient`'s reactive install and
-   * `_textSource`'s own read, matching `amOnPage` no longer eagerly installing the client.
-   *
-   * @protected
-   */
   async _probeCapabilities() {
     if (this.capabilities.layout === null) {
       const display = await this._evaluate(`getComputedStyle(document.documentElement).display`)
@@ -601,47 +612,10 @@ class CDPBrowser extends Helper {
     }
   }
 
-  /**
-   * Delegates a find-and-act call to `window.__codecept.run(candidates, action, payload)`. This is
-   * the primary extension point used by helpers built on top of this class for element queries and
-   * interactions.
-   *
-   * A per-call `context` locator, when given, is resolved and layered on top of any active
-   * `within` block (searched inside it, not instead of it), so `context` narrows the search
-   * without breaking out of a surrounding `within`.
-   *
-   * @param {Array<{type: 'css'|'xpath', value: string}>} candidates - locator strategies to try, in order, until one matches at least one element.
-   * @param {string} action - name of the action to run against the matched elements (e.g. `count`, `click`, `fill`).
-   * @param {object} [payload] - extra data the action needs (e.g. `{ value }` for `fill`).
-   * @param {?CodeceptJS.LocatorOrString} [context=null] - element to search in, narrowing the candidates below it.
-   * @returns {Promise<{found: number, result: any}>} number of matched elements and the action's result.
-   * @protected
-   */
   async _run(candidates, action, payload, context = null) {
     return this._runSelected(candidates, action, payload, this._selectionDescriptor(), context)
   }
 
-  /**
-   * Same as `_run`, but takes an explicit selection descriptor instead of reading one from
-   * `store.currentStep`/`options.strict`. Used internally by `CDPElementHandle` to address one
-   * specific element out of a candidate set by its 1-based index.
-   *
-   * The in-page client's presence is checked in the same round-trip as the action itself: the
-   * evaluated expression resolves to a sentinel string when `window.__codecept` is missing (e.g.
-   * right after a navigation the registered script didn't reach), in which case the client is
-   * installed and the call is retried exactly once. Separately, if the client is already present
-   * but reports (via its own `'__NO_XPATH__'` sentinel) that this call needs the XPath polyfill and
-   * it was not bundled into that earlier install, the polyfill is injected and the call is retried
-   * once more — see `_installClient`.
-   *
-   * @param {Array<{type: 'css'|'xpath', value: string}>} candidates
-   * @param {string} action
-   * @param {object|null} payload
-   * @param {object|null} selection - `{index}` or `{strict: true}`, mirroring `_selectionDescriptor`.
-   * @param {?CodeceptJS.LocatorOrString} [context=null]
-   * @returns {Promise<{found: number, result: any}>}
-   * @protected
-   */
   async _runSelected(candidates, action, payload, selection, context = null) {
     const layers = []
     if (this.withinCandidates) layers.push(this.withinCandidates)
@@ -669,17 +643,6 @@ class CDPBrowser extends Helper {
     return res
   }
 
-  /**
-   * Builds the `{index, strict}` element-selection descriptor from the current step's options
-   * (`store.currentStep.opts`) and `options.strict`, mirroring the semantics of
-   * `lib/helper/extras/elementSelection.js` (used by Puppeteer/WebDriver): a per-step
-   * `elementIndex` (numeric, or the `'first'`/`'last'` aliases) always takes precedence and
-   * disables strict mode for that step; otherwise `exact`/`strictMode` per-step options
-   * override `options.strict` to enable or cancel strict mode.
-   *
-   * @returns {object|null} descriptor with optional `index` and `strict` keys, or `null` when neither applies.
-   * @protected
-   */
   _selectionDescriptor() {
     const opts = store.currentStep?.opts
     let index = opts?.elementIndex
@@ -692,27 +655,10 @@ class CDPBrowser extends Helper {
     return strict ? { strict: true } : null
   }
 
-  /**
-   * A short, human-readable label built from `candidates`, used in `_run`'s elementIndex/strict
-   * error messages when no locator string is otherwise available.
-   *
-   * @param {?Array<{type: 'css'|'xpath', value: string}>} candidates
-   * @returns {string}
-   * @protected
-   */
   _candidatesLabel(candidates) {
     return (candidates || []).map(c => c.value).join(' | ')
   }
 
-  /**
-   * Starts a `within` block, scoping every subsequent `_run` call (and therefore every element
-   * lookup performed by this helper) to the descendants of the element matched by `locator`.
-   * Verifies the element exists (against the full document, i.e. unscoped) before narrowing.
-   *
-   * @param {CodeceptJS.LocatorOrString} locator - element located by CSS|XPath|strict locator.
-   * @returns {Promise<void>}
-   * @throws {ElementNotFound} if no element matches `locator`.
-   */
   async _withinBegin(locator) {
     const candidates = this._candidates(locator)
     const { found } = await this._run(candidates, 'count')
@@ -720,27 +666,10 @@ class CDPBrowser extends Helper {
     this.withinCandidates = candidates
   }
 
-  /**
-   * Ends the current `within` block, restoring unscoped element lookups.
-   *
-   * @returns {Promise<void>}
-   */
   async _withinEnd() {
     this.withinCandidates = null
   }
 
-  /**
-   * Repeatedly calls `fn` until it returns a truthy value or `timeoutSec` elapses, checking
-   * immediately and waiting `options.pollInterval` milliseconds between subsequent attempts.
-   *
-   * @param {function} fn - the condition to poll; should resolve to a truthy value once satisfied.
-   * @param {number} timeoutSec - maximum time to poll, in seconds.
-   * @param {string} message - error message used when the timeout is reached.
-   * @param {?{cancelled: boolean}} [cancelToken] - when `cancelled` becomes `true` (set by the caller from outside), polling stops early with an error instead of continuing to `timeoutSec`. Used by `_waitForPageLoad` to tear down the losing side of a race instead of leaving it running.
-   * @returns {Promise<any>} the truthy value returned by `fn`.
-   * @throws {Error} with `message` if `timeoutSec` elapses without `fn` returning a truthy value, or a cancellation error if `cancelToken.cancelled` is set first.
-   * @protected
-   */
   async _poll(fn, timeoutSec, message, cancelToken) {
     const deadline = Date.now() + timeoutSec * 1000
     while (Date.now() < deadline) {
@@ -753,43 +682,13 @@ class CDPBrowser extends Helper {
     throw new Error(message)
   }
 
-  /**
-   * Resolves a path against `options.url`. Absolute URLs (matching `scheme://`) are returned
-   * unchanged; anything else is appended to `options.url` with its trailing slash stripped.
-   *
-   * @param {string} path - an absolute URL or a path relative to `options.url`.
-   * @returns {string} the resolved, absolute URL.
-   * @protected
-   */
   _url(path) {
     if (/^\w+:\/\//.test(path)) return path
     return this.options.url.replace(/\/$/, '') + path
   }
 
   /**
-   * Opens a web page in the current session.
-   *
-   * ```js
-   * I.amOnPage('/'); // opens main page of website
-   * I.amOnPage('https://github.com'); // opens github
-   * I.amOnPage('/login'); // opens a login page
-   * ```
-   *
-   * Navigates via `Page.navigate`, then waits (up to `options.getPageTimeout` seconds) for the page
-   * to finish loading, preferring the push-based `Page.lifecycleEvent` signal (per
-   * `options.waitForNavigation`) over polling `document.readyState`. Capabilities are (re-)probed
-   * (a no-op after the first page, since they're cached for the helper's lifetime).
-   *
-   * The in-page client is deliberately *not* eagerly (re-)installed here — navigation discards any
-   * previously injected script, but installing it is deferred to the first actual action after
-   * this call, via `_runSelected`'s sentinel-and-retry. This keeps `amOnPage` itself down to the
-   * navigate command plus the push-based wait: no `_evaluate` call is issued on this hot path,
-   * which matters most right when the page's own JavaScript may still be busy (measured directly:
-   * an `_evaluate` sent in that window can queue behind it for hundreds of ms to multiple seconds
-   * on a JS-heavy real-world page, regardless of how small the evaluated expression is).
-   *
-   * @param {string} url - url path or global url.
-   * @returns {Promise<void>}
+   * {{> amOnPage }}
    */
   async amOnPage(url) {
     const navRes = await this.cdp.send('Page.navigate', { url: this._url(url) }, this.sessionId)
@@ -798,16 +697,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Reloads the current page.
-   *
-   * ```js
-   * I.refreshPage();
-   * ```
-   *
-   * Triggers `Page.reload` and waits (up to `options.getPageTimeout` seconds) for
-   * `document.readyState` to reach `'complete'`.
-   *
-   * @returns {Promise<void>}
+   * {{> refreshPage }}
    */
   async refreshPage() {
     await this.cdp.send('Page.reload', {}, this.sessionId)
@@ -815,22 +705,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Executes a JavaScript function in the browser context and returns its result.
-   *
-   * If a function is passed, it is serialized with `Function.prototype.toString()`, so it must
-   * not reference variables from the outer (Node.js) scope — pass any needed data as arguments
-   * instead. A string is evaluated as-is.
-   *
-   * ```js
-   * let title = await I.executeScript(() => document.title);
-   * let sum = await I.executeScript((a, b) => a + b, 2, 3);
-   * ```
-   *
-   * If the function returns a promise, `executeScript` waits for it to resolve.
-   *
-   * @param {(string|function)} fn - a JavaScript function to be executed in the browser context, or a string expression.
-   * @param {...any} args - arguments to pass into the function.
-   * @returns {Promise<any>} the value returned (or resolved) by the function.
+   * {{> executeScript }}
    */
   async executeScript(fn, ...args) {
     const body = typeof fn === 'function' ? `(${fn.toString()})(...${JSON.stringify(args)})` : fn
@@ -838,62 +713,26 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Retrieves the page URL of the current page.
-   *
-   * ```js
-   * let url = await I.grabCurrentUrl();
-   * console.log(`Current URL is [${url}]`);
-   * ```
-   *
-   * @returns {Promise<string>} current URL.
+   * {{> grabCurrentUrl }}
    */
   async grabCurrentUrl() {
     return this._evaluate('window.location.href')
   }
 
   /**
-   * Retrieves a page title.
-   *
-   * ```js
-   * let title = await I.grabTitle();
-   * ```
-   *
-   * @returns {Promise<string>} title of the page.
+   * {{> grabTitle }}
    */
   async grabTitle() {
     return this._evaluate('document.title')
   }
 
   /**
-   * Retrieves the source code of the current page.
-   *
-   * ```js
-   * let pageSource = await I.grabSource();
-   * ```
-   *
-   * @returns {Promise<string>} source code of the current page (the outer HTML of `<html>`).
+   * {{> grabSource }}
    */
   async grabSource() {
     return this._evaluate('document.documentElement.outerHTML')
   }
 
-  /**
-   * Builds the list of `{type, value}` candidates `_run` should try, in order, for a given
-   * locator and `kind`. A strict locator (CSS/XPath/object form) resolves to a single candidate.
-   * A fuzzy (plain-text) locator is expanded into a strategy-specific list of XPath expressions
-   * mirroring the click/field/checkbox matching used by other browser helpers (matching by
-   * visible text, label, name, placeholder, ARIA attributes, etc.), falling back to treating the
-   * raw text as a CSS selector.
-   *
-   * A role locator (`{role, text, exact}`) resolves to a single `role`-type candidate, resolved
-   * in-page by the client's implicit ARIA role mapping (native elements) plus explicit `role`
-   * attributes, filtered by accessible name/text when `text` is given.
-   *
-   * @param {CodeceptJS.LocatorOrString} locator - element located by CSS|XPath|strict locator, or plain fuzzy text.
-   * @param {'element'|'clickable'|'field'|'checkable'} [kind='element'] - matching strategy to use when `locator` is fuzzy.
-   * @returns {Array<{type: 'css'|'xpath'|'role', value: (string|object)}>} candidates to pass to `_run`.
-   * @protected
-   */
   _candidates(locator, kind = 'element') {
     locator = new Locator(locator)
     if (locator.isShadow()) {
@@ -933,18 +772,6 @@ class CDPBrowser extends Helper {
     return [{ type: 'css', value: locator.value }]
   }
 
-  /**
-   * Resolves the text to search `see`/`dontSee`/`waitForText` against, when no explicit `context`
-   * locator is given. An explicit `context` is always resolved through `_run`, so it is implicitly
-   * scoped to the active `within` block, if any. Without a `context`, this reads the `within` root's
-   * text when a `within` block is active, or the whole page's text otherwise — via native
-   * `document.body.innerText`, or the client's `visibleText()` walker when
-   * `_needsVisibleTextFallback` determines native `innerText` is not trustworthy.
-   *
-   * @param {?CodeceptJS.LocatorOrString} context
-   * @returns {Promise<string>}
-   * @protected
-   */
   async _textSource(context) {
     if (context) return (await this._texts(this._candidates(context))).result?.join(' | ') || ''
     if (this.withinCandidates) return (await this._texts(null)).result?.join(' | ') || ''
@@ -955,32 +782,6 @@ class CDPBrowser extends Helper {
     return this._evaluate('document.body ? document.body.innerText : ""')
   }
 
-  /**
-   * Runs the in-page `containsText` check against the whole page (no `context`/`within` scoping —
-   * those stay on `_textSource`'s per-element path, already small). Returns only `{found, snippet}`
-   * instead of the full haystack: on a page with a large body, serializing that whole string across
-   * the CDP wire (and, on engines where `capabilities.innerText` requires the `visibleText()`
-   * walker, holding it in memory) is avoidable work `see`/`dontSee`/`waitForText` don't actually
-   * need on their common, non-throwing path.
-   *
-   * Also folds the client's install into the very same round trip when it is still missing, instead
-   * of a separate presence-check evaluate followed by an install evaluate before the check itself
-   * can even run — mirroring `_runSelected`'s sentinel-retry design, but collapsed into one evaluate
-   * since the install source itself is known and cacheable up front. That install is client-only,
-   * never the 171KB XPath polyfill: `containsText` never calls `document.evaluate`, so bundling it
-   * here would be pure waste for a scenario that never resolves an xpath locator. The client is
-   * still told, via `installCodeceptClient`'s `xpathNeedsPolyfill` flag, whether the *engine*
-   * (`capabilities.xpath`, cached by `_before`'s `about:blank` probe) will eventually need it, so a
-   * later xpath-resolving action on the same page gets a clean `'__NO_XPATH__'` miss signal from
-   * `window.__codecept.run` instead of silently hitting a broken native `document.evaluate` —
-   * `_runSelected` reacts to that sentinel already. The bootstrap source is built once and reused
-   * for the life of the instance, since whether the engine needs the polyfill never changes.
-   *
-   * @param {string} text
-   * @param {{ignoreCase: boolean, useWalker: boolean}} opts
-   * @returns {Promise<{found: boolean, snippet: (string|null)}>}
-   * @protected
-   */
   async _runTextCheck(text, opts) {
     if (!this._textCheckBootstrap) {
       const needsPolyfill = await this._needsXPathPolyfill()
@@ -990,19 +791,6 @@ class CDPBrowser extends Helper {
     return this._evaluate(expression)
   }
 
-  /**
-   * Shared implementation for `see`/`dontSee`. Without a `context` locator and outside any `within`
-   * block, checks presence via `_runTextCheck`'s fast, boolean-only round trip; the full haystack is
-   * only fetched (one extra, rare evaluate) when the assertion is about to fail, to build the same
-   * `stringIncludes` error as before this optimization. With a `context` or inside `within`, this is
-   * unchanged from before — already a small, per-element read, not the identified cost.
-   *
-   * @param {string} text
-   * @param {?CodeceptJS.LocatorOrString} context
-   * @param {boolean} negate
-   * @returns {Promise<void>}
-   * @protected
-   */
   async _checkText(text, context, negate) {
     const label = context ? `element ${new Locator(context).toString()}` : 'web page'
     const ignoreCase = store.currentStep?.opts?.ignoreCase === true
@@ -1030,112 +818,56 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Checks that a page contains a visible text.
-   * Use context parameter to narrow down the search.
-   *
-   * ```js
-   * I.see('Welcome'); // text welcome on a page
-   * I.see('Welcome', '.content'); // text inside .content div
-   * I.see('Register', {css: 'form.register'}); // use strict locator
-   * ```
-   *
-   * @param {string} text expected on page.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS|Xpath|strict locator in which to search for text.
-   * @returns {Promise<void>}
+   * {{> see }}
    */
   async see(text, context = null) {
     return this._checkText(text, context, false)
   }
 
   /**
-   * Opposite to `see`. Checks that a text is not present on a page.
-   * Use context parameter to narrow down the search.
-   *
-   * ```js
-   * I.dontSee('Login'); // assume we are already logged in.
-   * I.dontSee('Login', '.nav'); // no login inside .nav element
-   * ```
-   *
-   * @param {string} text which is not present.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional) element located by CSS|XPath|strict locator in which to perform search.
-   * @returns {Promise<void>}
+   * {{> dontSee }}
    */
   async dontSee(text, context = null) {
     return this._checkText(text, context, true)
   }
 
   /**
-   * Checks that the current page contains the given string in its raw source code.
-   *
-   * ```js
-   * I.seeInSource('<h1>Green eggs &amp; ham</h1>');
-   * ```
-   *
-   * @param {string} text value to check.
-   * @returns {Promise<void>}
+   * {{> seeInSource }}
    */
   async seeInSource(text) {
     return stringIncludes('HTML source of a page').assert(text, await this.grabSource())
   }
 
   /**
-   * Checks that the current page does not contain the given string in its raw source code.
-   *
-   * @param {string} text value to check.
-   * @returns {Promise<void>}
+   * {{> dontSeeInSource }}
    */
   async dontSeeInSource(text) {
     return stringIncludes('HTML source of a page').negate(text, await this.grabSource())
   }
 
   /**
-   * Checks that current url contains a provided fragment.
-   *
-   * ```js
-   * I.seeInCurrentUrl('/register'); // we are on registration page
-   * ```
-   *
-   * @param {string} url a fragment to check
-   * @returns {Promise<void>}
+   * {{> seeInCurrentUrl }}
    */
   async seeInCurrentUrl(url) {
     return stringIncludes('url').assert(url, await this.grabCurrentUrl())
   }
 
   /**
-   * Checks that current url does not contain a provided fragment.
-   *
-   * @param {string} url value to check.
-   * @returns {Promise<void>}
+   * {{> dontSeeInCurrentUrl }}
    */
   async dontSeeInCurrentUrl(url) {
     return stringIncludes('url').negate(url, await this.grabCurrentUrl())
   }
 
   /**
-   * Checks that title contains text.
-   *
-   * ```js
-   * I.seeInTitle('Home Page');
-   * ```
-   *
-   * @param {string} text text value to check.
-   * @returns {Promise<void>}
+   * {{> seeInTitle }}
    */
   async seeInTitle(text) {
     return stringIncludes('web page title').assert(text, await this.grabTitle())
   }
 
   /**
-   * Checks that a given Element is present in the DOM.
-   * Element is located by CSS or XPath.
-   *
-   * ```js
-   * I.seeElementInDOM('#modal');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @returns {Promise<void>}
+   * {{> seeElementInDOM }}
    */
   async seeElementInDOM(locator) {
     const { found } = await this._run(this._candidates(locator), 'count')
@@ -1143,28 +875,13 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Opposite to `seeElementInDOM`. Checks that element is not on page.
-   *
-   * ```js
-   * I.dontSeeElementInDOM('.nav'); // checks that element is not on page visible or not
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
-   * @returns {Promise<void>}
+   * {{> dontSeeElementInDOM }}
    */
   async dontSeeElementInDOM(locator) {
     const { found } = await this._run(this._candidates(locator), 'count')
     return empty(`elements of ${new Locator(locator).toString()}`).assert(found === 0 ? null : found)
   }
 
-  /**
-   * Throws if the current page has no real layout engine (`capabilities.layout === 'none'`),
-   * used to guard visibility-dependent assertions that cannot be evaluated without one.
-   *
-   * @param {string} action - name of the calling assertion, used in the error message.
-   * @throws {Error} if the page has no layout engine.
-   * @protected
-   */
   _assertLayoutSupported(action) {
     if (this.capabilities.layout === 'none') {
       throw new Error(`${action} requires a layout engine which this browser does not provide. Use ${action}InDOM instead.`)
@@ -1172,16 +889,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Checks that a given Element is visible.
-   * Element is located by CSS or XPath.
-   *
-   * ```js
-   * I.seeElement('#modal');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
-   * @returns {Promise<void>}
+   * {{> seeElement }}
    */
   async seeElement(locator, context = null) {
     this._assertLayoutSupported('seeElement')
@@ -1190,15 +898,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Opposite to `seeElement`. Checks that element is not visible.
-   *
-   * ```js
-   * I.dontSeeElement('.modal'); // modal is not shown
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
-   * @returns {Promise<void>}
+   * {{> dontSeeElement }}
    */
   async dontSeeElement(locator, context = null) {
     this._assertLayoutSupported('dontSeeElement')
@@ -1207,16 +907,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Verifies that the specified checkbox is checked.
-   *
-   * ```js
-   * I.seeCheckboxIsChecked('Agree');
-   * I.seeCheckboxIsChecked('#agree'); // I suppose user agreed to terms
-   * I.seeCheckboxIsChecked({css: '#signup_form input[type=checkbox]'});
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator located by label|name|CSS|XPath|strict locator.
-   * @returns {Promise<void>}
+   * {{> seeCheckboxIsChecked }}
    */
   async seeCheckboxIsChecked(locator) {
     const res = await this._run(this._candidates(locator, 'checkable'), 'checked')
@@ -1225,15 +916,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Verifies that the specified checkbox is not checked.
-   *
-   * ```js
-   * I.dontSeeCheckboxIsChecked('#agree'); // located by ID
-   * I.dontSeeCheckboxIsChecked('I agree to terms'); // located by label
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator located by label|name|CSS|XPath|strict locator.
-   * @returns {Promise<void>}
+   * {{> dontSeeCheckboxIsChecked }}
    */
   async dontSeeCheckboxIsChecked(locator) {
     const res = await this._run(this._candidates(locator, 'checkable'), 'checked')
@@ -1242,16 +925,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Retrieves a text from an element located by CSS or XPath and returns it to test.
-   * Resumes test execution, so **should be used inside async with `await`** operator.
-   *
-   * ```js
-   * let pin = await I.grabTextFrom('#pin');
-   * ```
-   * If multiple elements found returns first element.
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @returns {Promise<string>} text value
+   * {{> grabTextFrom }}
    */
   async grabTextFrom(locator) {
     const res = await this._texts(this._candidates(locator))
@@ -1260,15 +934,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Retrieves all texts from elements located by CSS or XPath and returns it to test.
-   * Resumes test execution, so **should be used inside async with `await`** operator.
-   *
-   * ```js
-   * let pins = await I.grabTextFromAll('#pin li');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @returns {Promise<string[]>} array of text values
+   * {{> grabTextFromAll }}
    */
   async grabTextFromAll(locator) {
     const res = await this._texts(this._candidates(locator))
@@ -1276,17 +942,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Retrieves an array of `WebElement`s matching a locator (`lib/element/WebElement.js`,
-   * wrapping a `CDPElementHandle`). Element handles are re-resolved on demand by re-running
-   * `candidates` and picking the matching index, since `CDPBrowser` never keeps a persistent
-   * handle to a DOM node on the Node side.
-   *
-   * ```js
-   * const buttons = await I.grabWebElements({ role: 'button' });
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @returns {Promise<object[]>} array of WebElement instances.
+   * {{> grabWebElements }}
    */
   async grabWebElements(locator) {
     const candidates = this._candidates(locator)
@@ -1295,15 +951,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Retrieves the first `WebElement` matching a locator.
-   *
-   * ```js
-   * const button = await I.grabWebElement({ role: 'button', text: 'Submit' });
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @returns {Promise<object>} a WebElement instance.
-   * @throws {ElementNotFound} if no element matches `locator`.
+   * {{> grabWebElement }}
    */
   async grabWebElement(locator) {
     const elements = await this.grabWebElements(locator)
@@ -1311,31 +959,13 @@ class CDPBrowser extends Helper {
     return elements[0]
   }
 
-  /**
-   * Resolves whether the `texts` action should read via the client's `visibleText()` walker
-   * (probed once via `_needsVisibleTextFallback` and cached on `capabilities.innerText`) instead
-   * of each element's native `innerText`, then runs it.
-   *
-   * @param {Array<{type: string, value: (string|object)}>} candidates
-   * @returns {Promise<{found: number, result: any}>}
-   * @protected
-   */
   async _texts(candidates) {
     const visible = await this._needsVisibleTextFallback()
     return this._run(candidates, 'texts', { visible })
   }
 
   /**
-   * Retrieves a value from a form element located by CSS or XPath and returns it to test.
-   * Resumes test execution, so **should be used inside async function with `await`** operator.
-   * If more than one element is found - value of first element is returned.
-   *
-   * ```js
-   * let email = await I.grabValueFrom('input[name=email]');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
-   * @returns {Promise<string>} attribute value
+   * {{> grabValueFrom }}
    */
   async grabValueFrom(locator) {
     const res = await this._run(this._candidates(locator, 'field'), 'values')
@@ -1344,15 +974,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Retrieves an array of values from fields located by CSS or XPath and returns it to test.
-   * Resumes test execution, so **should be used inside async function with `await`** operator.
-   *
-   * ```js
-   * let inputs = await I.grabValueFromAll('//form/input');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
-   * @returns {Promise<string[]>} array of attribute values
+   * {{> grabValueFromAll }}
    */
   async grabValueFromAll(locator) {
     const res = await this._run(this._candidates(locator, 'field'), 'values')
@@ -1360,17 +982,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Retrieves an attribute from an element located by CSS or XPath and returns it to test.
-   * Resumes test execution, so **should be used inside async with `await`** operator.
-   * If more than one element is found - attribute of first element is returned.
-   *
-   * ```js
-   * let hint = await I.grabAttributeFrom('#tooltip', 'title');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @param {string} attr attribute name.
-   * @returns {Promise<string>} attribute value
+   * {{> grabAttributeFrom }}
    */
   async grabAttributeFrom(locator, attr) {
     const res = await this._run(this._candidates(locator), 'attrs', { name: attr })
@@ -1378,17 +990,8 @@ class CDPBrowser extends Helper {
     return res.result[0]
   }
 
-  /**
-   * Retrieves an array of attributes from elements located by CSS or XPath and returns it to test.
-   * Resumes test execution, so **should be used inside async with `await`** operator.
-   *
-   * ```js
-   * let hints = await I.grabAttributeFromAll('.tooltip', 'title');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @param {string} attr attribute name.
-   * @returns {Promise<string[]>} array of attribute values
+  /**
+   * {{> grabAttributeFromAll }}
    */
   async grabAttributeFromAll(locator, attr) {
     const res = await this._run(this._candidates(locator), 'attrs', { name: attr })
@@ -1412,34 +1015,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Perform a click on a link or a button, given by a locator.
-   * If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.
-   * 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.
-   *
-   * When `options.input` is `'cdp'`, the click is dispatched as real `Input.dispatchMouseEvent` mouse events
-   * (`mouseMoved` / `mousePressed` / `mouseReleased`) at the center of the element's bounding box, so it
-   * exercises the same input pipeline a real user would. Otherwise it delegates to `forceClick`. A matched
-   * element with a zero-size bounding box (e.g. `display: none`) has no valid coordinate to click and throws;
-   * use `forceClick` to dispatch a synthetic click on such elements instead.
-   *
-   * ```js
-   * // simple link
-   * I.click('Logout');
-   * // button of form
-   * I.click('Submit');
-   * // CSS button
-   * I.click('#form input[type=submit]');
-   * // XPath
-   * I.click('//form/*[@type=submit]');
-   * // using strict locator
-   * 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} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
-   * @returns {Promise<void>}
-   * @throws {Error} if the matched element has a zero-size bounding box.
+   * {{> click }}
    */
   async click(locator, context = null) {
     if (this.options.input !== 'cdp') return this.forceClick(locator, context)
@@ -1459,30 +1035,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Perform an emulated click on a link or a button, given by a locator.
-   * Unlike `click`, this always dispatches a synthetic in-page `el.click()` instead of sending native
-   * CDP input events. This works on hidden, animated or inactive elements as well.
-   *
-   * If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.
-   * 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.
-   *
-   * ```js
-   * // simple link
-   * I.forceClick('Logout');
-   * // button of form
-   * I.forceClick('Submit');
-   * // CSS button
-   * I.forceClick('#form input[type=submit]');
-   * // XPath
-   * I.forceClick('//form/*[@type=submit]');
-   * // using strict locator
-   * I.forceClick({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} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
-   * @returns {Promise<void>}
+   * {{> forceClick }}
    */
   async forceClick(locator, context = null) {
     const armed = this._armActionSettle()
@@ -1491,37 +1044,6 @@ class CDPBrowser extends Helper {
     return this._waitForAction(armed)
   }
 
-  /**
-   * Settles after an interaction (click, key press, etc.) before the next step runs, using the
-   * listener `_armActionSettle` started *before* the interaction was dispatched (`armed`; a fresh
-   * one is armed here too, as a safety net, if a call site forgot to — but arming this late can
-   * only miss a navigation that already started during the action's own dispatch, exactly the race
-   * this design exists to avoid, so every call site should pass its own pre-armed `armed`, not rely
-   * on this fallback).
-   *
-   * If `options.waitForAction` was set explicitly in the config, honors it literally as a fixed
-   * pacing sleep, exactly as before this round — an explicit value is a deliberate choice
-   * (slow-motion debugging, a known-slow app) this never second-guesses.
-   *
-   * Otherwise, event-aware: races the armed listener against a *fresh* `ACTION_SETTLE_GRACE_MS`
-   * window (started now, not when it was armed — the action's own dispatch already ran concurrently
-   * with the arm, so this is genuinely bounded extra time, not a guess). If nothing declares a
-   * navigation, returns immediately once the window elapses — the common case for most actions
-   * (typing, toggling a checkbox, focusing a field) — instead of a fixed `options.waitForAction`
-   * (100ms by default) sleep on every single action regardless of whether anything is happening.
-   *
-   * If a navigation *did* start, `_lastMainFrameNav` (see `_ensureLifecycleListener`) is checked
-   * first: on a fast/local page, the entire lifecycle sequence through the target event has
-   * typically already arrived in the same batch that announced the navigation started, in which
-   * case this returns immediately. Only a navigation still genuinely in flight falls through to
-   * `_waitForPageLoad` (the same mechanism `amOnPage`/`refreshPage` use) — which waits for it to
-   * actually finish, rather than a fixed sleep that has no relationship to how long the navigation
-   * actually takes: strictly more correct for a slow navigation, not just faster for a fast one.
-   *
-   * @param {({promise: Promise<string|null>, cancel: function}|null)} [armed] - from `_armActionSettle`, called before the action.
-   * @returns {Promise<void>}
-   * @protected
-   */
   async _waitForAction(armed) {
     if (this._waitForActionExplicit) {
       return new Promise(r => setTimeout(r, this.options.waitForAction))
@@ -1546,24 +1068,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Fills a text field or textarea, after clearing its value, with the given string.
-   * Field is located by name, label, CSS, or XPath.
-   *
-   * ```js
-   * // by label
-   * I.fillField('Email', 'hello@world.com');
-   * // by name
-   * I.fillField('password', secret('123456'));
-   * // by CSS
-   * I.fillField('form#login input[name=username]', 'John');
-   * // or by strict locator
-   * I.fillField({css: 'form#login input[name=username]'}, 'John');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
-   * @param {CodeceptJS.StringOrSecret} value text value to fill.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
-   * @returns {Promise<void>}
+   * {{> fillField }}
    */
   async fillField(field, value, context = null) {
     const res = await this._run(this._candidates(field, 'field'), 'fill', { value: String(value) }, context)
@@ -1571,19 +1076,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Appends text to a input field or textarea.
-   * Field is located by name, label, CSS or XPath
-   *
-   * ```js
-   * I.appendField('#myTextField', 'appended');
-   * // typing secret
-   * I.appendField('password', secret('123456'));
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator
-   * @param {string} value text value to append.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
-   * @returns {Promise<void>}
+   * {{> appendField }}
    */
   async appendField(field, value, context = null) {
     const res = await this._run(this._candidates(field, 'field'), 'append', { value: String(value) }, context)
@@ -1591,17 +1084,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Clears a `<textarea>` or text `<input>` element's value.
-   *
-   * ```js
-   * I.clearField('Email');
-   * I.clearField('user[email]');
-   * I.clearField('#email');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} field editable field located by label|name|CSS|XPath|strict locator.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
-   * @returns {Promise<void>}
+   * {{> clearField }}
    */
   async clearField(field, context = null) {
     const res = await this._run(this._candidates(field, 'field'), 'clear', null, context)
@@ -1609,23 +1092,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Selects an option in a drop-down select.
-   * Field is searched by label | name | CSS | XPath.
-   * Option is selected by visible text or by value.
-   *
-   * ```js
-   * I.selectOption('Choose Plan', 'Monthly'); // select by label
-   * I.selectOption('subscription', 'Monthly'); // match option by text
-   * I.selectOption('subscription', '0'); // or by value
-   * I.selectOption('//form/select[@name=account]','Premium');
-   * I.selectOption('form select[name=account]', 'Premium');
-   * I.selectOption({css: 'form select[name=account]'}, 'Premium');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} select field located by label|name|CSS|XPath|strict locator.
-   * @param {string|string[]} option visible text or value of option, or an array of them for a multi-select.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
-   * @returns {Promise<void>}
+   * {{> selectOption }}
    */
   async selectOption(select, option, context = null) {
     const value = Array.isArray(option) ? option.map(String) : String(option)
@@ -1638,18 +1105,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Selects a checkbox or radio button.
-   * Element is located by label or name or CSS or XPath.
-   *
-   * ```js
-   * I.checkOption('#agree');
-   * I.checkOption('I Agree to Terms and Conditions');
-   * I.checkOption('agree', '//form');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} field checkbox located by label | name | CSS | XPath | strict locator.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
-   * @returns {Promise<void>}
+   * {{> checkOption }}
    */
   async checkOption(field, context = null) {
     const res = await this._run(this._candidates(field, 'checkable'), 'check', null, context)
@@ -1657,18 +1113,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Unselects a checkbox or radio button.
-   * Element is located by label or name or CSS or XPath.
-   *
-   * ```js
-   * I.uncheckOption('#agree');
-   * I.uncheckOption('I Agree to Terms and Conditions');
-   * I.uncheckOption('agree', '//form');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} field checkbox located by label | name | CSS | XPath | strict locator.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
-   * @returns {Promise<void>}
+   * {{> uncheckOption }}
    */
   async uncheckOption(field, context = null) {
     const res = await this._run(this._candidates(field, 'checkable'), 'uncheck', null, context)
@@ -1676,27 +1121,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Attaches a file to a file input field, or drops it onto a drag-and-drop dropzone element,
-   * resolved by label|name|CSS|XPath|strict locator. `pathToFile` is resolved relative to
-   * `codecept_dir` (matching Puppeteer/WebDriver). Since `CDPBrowser` never brings element handles
-   * back to Node, the resolved element is marked with a throwaway `data-codecept-upload` attribute
-   * in-page (respecting `context`/`within`/elementIndex exactly like every other action). A real
-   * `<input type="file">` is then addressed by that attribute through the CDP `DOM` domain, which
-   * `CDPBrowser` otherwise never uses, to call `DOM.setFileInputFiles`; any other element (a
-   * drag-and-drop dropzone) instead gets a synthetic `dragenter`/`dragover`/`drop` sequence with a
-   * `DataTransfer` built from the file's contents, entirely in-page. The marker is removed again in
-   * a `finally`.
-   *
-   * ```js
-   * I.attachFile('Avatar', 'data/avatar.jpg');
-   * I.attachFile('#file', 'data/avatar.jpg');
-   * I.attachFile('#dropzone', 'data/avatar.jpg');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
-   * @param {string} pathToFile path to file, relative to `codecept_dir`.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
-   * @returns {Promise<void>}
+   * {{> attachFile }}
    */
   async attachFile(field, pathToFile, context = null) {
     const file = path.join(store.codeceptDir, pathToFile)
@@ -1730,17 +1155,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Waits for element to be present on page (by default waits for `options.waitForTimeout` seconds).
-   * Element can be located by CSS or XPath.
-   *
-   * ```js
-   * I.waitForElement('.btn.continue');
-   * I.waitForElement('.btn.continue', 5); // wait for 5 secs
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @param {number} [sec] (optional, `options.waitForTimeout` by default) time in seconds to wait
-   * @returns {Promise<void>}
+   * {{> waitForElement }}
    */
   async waitForElement(locator, sec = null) {
     const timeout = sec || this.options.waitForTimeout
@@ -1753,19 +1168,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Waits for a text to appear (by default waits for `options.waitForTimeout` seconds).
-   * Element can be located by CSS or XPath.
-   * Narrow down search results by providing context.
-   *
-   * ```js
-   * I.waitForText('Thank you, form has been submitted');
-   * I.waitForText('Thank you, form has been submitted', 5, '#modal');
-   * ```
-   *
-   * @param {string} text to wait for.
-   * @param {number} [sec] (optional, `options.waitForTimeout` by default) time in seconds to wait
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional) element located by CSS|XPath|strict locator.
-   * @returns {Promise<void>}
+   * {{> waitForText }}
    */
   async waitForText(text, sec = null, context = null) {
     const timeout = sec || this.options.waitForTimeout
@@ -1801,15 +1204,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Waiting for the part of the URL to match the expected. Useful for SPA to understand that page was changed.
-   *
-   * ```js
-   * I.waitInUrl('/info', 2);
-   * ```
-   *
-   * @param {string} urlPart value to check.
-   * @param {number} [sec] (optional, `options.waitForTimeout` by default) time in seconds to wait
-   * @returns {Promise<void>}
+   * {{> waitInUrl }}
    */
   async waitInUrl(urlPart, sec = null) {
     const timeout = sec || this.options.waitForTimeout
@@ -1829,19 +1224,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Waits for a function to return true (waits for `options.waitForTimeout` seconds by default).
-   * Running in browser context.
-   *
-   * ```js
-   * I.waitForFunction(() => window.requests == 0);
-   * I.waitForFunction(() => window.requests == 0, 5); // waits for 5 sec
-   * I.waitForFunction((count) => window.requests == count, [3], 5) // pass args and wait for 5 sec
-   * ```
-   *
-   * @param {(string|function)} fn to be executed in browser context.
-   * @param {any[]|number} [argsOrSec] (optional) arguments for function or, if a number, seconds to wait.
-   * @param {number} [sec] (optional, `options.waitForTimeout` by default) time in seconds to wait
-   * @returns {Promise<void>}
+   * {{> waitForFunction }}
    */
   async waitForFunction(fn, argsOrSec = null, sec = null) {
     let args = []
@@ -1857,22 +1240,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Sets cookie(s).
-   *
-   * Can be a single cookie object or an array of cookies:
-   *
-   * ```js
-   * I.setCookie({name: 'auth', value: true});
-   *
-   * // as array
-   * I.setCookie([
-   *   {name: 'auth', value: true},
-   *   {name: 'agree', value: true}
-   * ]);
-   * ```
-   *
-   * @param {CodeceptJS.Cookie|Array<CodeceptJS.Cookie>} cookie a cookie object or array of cookie objects.
-   * @returns {Promise<void>}
+   * {{> setCookie }}
    */
   async setCookie(cookie) {
     const cookies = Array.isArray(cookie) ? cookie : [cookie]
@@ -1900,17 +1268,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Gets a cookie object by name.
-   * If none provided gets all cookies.
-   * Resumes test execution, so **should be used inside async function with `await`** operator.
-   *
-   * ```js
-   * let cookie = await I.grabCookie('auth');
-   * assert(cookie.value, '123456');
-   * ```
-   *
-   * @param {string|null} [name=null] cookie name.
-   * @returns {Promise<CodeceptJS.Cookie|Array<CodeceptJS.Cookie>>} a cookie object, or an array of all cookies when `name` is not provided.
+   * {{> grabCookie }}
    */
   async grabCookie(name) {
     const cookies = await this.grabCookies()
@@ -1919,16 +1277,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Clears a cookie by name,
-   * if none provided clears all cookies.
-   *
-   * ```js
-   * I.clearCookie();
-   * I.clearCookie('test');
-   * ```
-   *
-   * @param {string|null} [name=null] (optional, `null` by default) cookie name
-   * @returns {Promise<void>}
+   * {{> clearCookie }}
    */
   async clearCookie(name) {
     const cookies = await this.grabCookies()
@@ -1940,6 +1289,47 @@ class CDPBrowser extends Helper {
     }
   }
 
+  /**
+   * {{> seeInClipboard }}
+   */
+  async seeInClipboard(text) {
+    const clipboard = await this.grabFromClipboard()
+    return stringIncludes('clipboard').assert(text, clipboard)
+  }
+
+  /**
+   * {{> seeClipboardEquals }}
+   */
+  async seeClipboardEquals(text) {
+    const clipboard = await this.grabFromClipboard()
+    return equals('clipboard').assert(clipboard, text)
+  }
+
+  /**
+   * {{> clearClipboard }}
+   */
+  async clearClipboard() {
+    await this._grantClipboardAccess()
+    await this._evaluate(clipboardExpression(writeClipboardScript, ''))
+  }
+
+  /**
+   * {{> grabFromClipboard }}
+   */
+  async grabFromClipboard() {
+    await this._grantClipboardAccess()
+    const clipboard = await this._evaluate(clipboardExpression(readClipboardScript, CLIPBOARD_READ_TIMEOUT_MS))
+    this.debugSection('Clipboard', clipboard)
+    return clipboard
+  }
+
+  async _grantClipboardAccess() {
+    await this.cdp.send('Page.bringToFront', {}, this.sessionId).catch(() => null)
+    const origin = await this._evaluate('window.location.origin').catch(() => null)
+    if (!origin || !origin.startsWith('http')) return
+    await this.cdp.send('Browser.grantPermissions', { origin, permissions: ['clipboardReadWrite', 'clipboardSanitizedWrite'] }).catch(() => null)
+  }
+
   /**
    * Saves a screenshot to the output folder (set in codecept.conf.ts or codecept.conf.js).
    * Filename is relative to the output folder.
@@ -1949,7 +1339,7 @@ class CDPBrowser extends Helper {
    * ```
    *
    * @param {string} fileName file name to save.
-   * @returns {Promise<void>}
+   * @returns {void} automatically synchronized promise through #recorder
    */
   async saveScreenshot(fileName) {
     if (this.capabilities.screenshot === false) {
@@ -1961,15 +1351,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Saves a screenshot of a single element to the output folder.
-   *
-   * ```js
-   * I.saveElementScreenshot('#logo', 'logo.png');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @param {string} fileName file name to save.
-   * @returns {Promise<void>}
+   * {{> saveElementScreenshot }}
    */
   async saveElementScreenshot(locator, fileName) {
     if (this.capabilities.screenshot === false) {
@@ -1984,61 +1366,33 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Pauses execution for a number of seconds.
-   *
-   * ```js
-   * I.wait(2); // waits 2 secs
-   * ```
-   *
-   * @param {number} sec number of seconds to wait.
-   * @returns {Promise<void>}
+   * {{> wait }}
    */
   async wait(sec) {
     return new Promise(r => setTimeout(r, sec * 1000))
   }
 
   /**
-   * Checks that title does not contain text.
-   *
-   * @param {string} text value to check.
-   * @returns {Promise<void>}
+   * {{> dontSeeInTitle }}
    */
   async dontSeeInTitle(text) {
     return stringIncludes('web page title').negate(text, await this.grabTitle())
   }
 
   /**
-   * Checks that current url is equal to provided one.
-   * Unlike `seeInCurrentUrl` performs a strict comparison.
-   *
-   * ```js
-   * I.seeCurrentUrlEquals('/register');
-   * ```
-   *
-   * @param {string} url value to check.
-   * @returns {Promise<void>}
+   * {{> seeCurrentUrlEquals }}
    */
   async seeCurrentUrlEquals(url) {
     return urlEquals(this.options.url).assert(url, await this.grabCurrentUrl())
   }
 
   /**
-   * Checks that current url is not equal to provided one.
-   * Unlike `dontSeeInCurrentUrl` performs a strict comparison.
-   *
-   * @param {string} url value to check.
-   * @returns {Promise<void>}
+   * {{> dontSeeCurrentUrlEquals }}
    */
   async dontSeeCurrentUrlEquals(url) {
     return urlEquals(this.options.url).negate(url, await this.grabCurrentUrl())
   }
 
-  /**
-   * Resolves the current page URL to a `pathname`, ignoring the origin, query string, and hash.
-   *
-   * @returns {Promise<string>} the pathname of the current page.
-   * @protected
-   */
   async _grabCurrentPath() {
     const currentUrl = await this.grabCurrentUrl()
     const baseUrl = this.options.url || 'http://localhost'
@@ -2046,39 +1400,21 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Checks that current url path (ignoring query string and hash) equals to provided one.
-   *
-   * ```js
-   * I.seeCurrentPathEquals('/info');
-   * ```
-   *
-   * @param {string} path value to check.
-   * @returns {Promise<void>}
+   * {{> seeCurrentPathEquals }}
    */
   async seeCurrentPathEquals(path) {
     return equals('url path').assert(normalizePath(path), normalizePath(await this._grabCurrentPath()))
   }
 
   /**
-   * Opposite to `seeCurrentPathEquals`.
-   *
-   * @param {string} path value to check.
-   * @returns {Promise<void>}
+   * {{> dontSeeCurrentPathEquals }}
    */
   async dontSeeCurrentPathEquals(path) {
     return equals('url path').negate(normalizePath(path), normalizePath(await this._grabCurrentPath()))
   }
 
   /**
-   * Waits for the entire URL to match the expected (by default waits for `options.waitForTimeout` seconds).
-   *
-   * ```js
-   * I.waitUrlEquals('/info', 2);
-   * ```
-   *
-   * @param {string} urlPart value to check.
-   * @param {number} [sec] (optional, `options.waitForTimeout` by default) time in seconds to wait
-   * @returns {Promise<void>}
+   * {{> waitUrlEquals }}
    */
   async waitUrlEquals(urlPart, sec = null) {
     const timeout = sec || this.options.waitForTimeout
@@ -2099,15 +1435,16 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Waits for current url path (ignoring query string and hash) to equal to the expected.
+   * Waits for the current URL path to match the expected path.
+   * Query strings and URL fragments are ignored.
    *
    * ```js
-   * I.waitCurrentPathEquals('/info', 2);
+   * I.waitCurrentPathEquals('/info', 5);
    * ```
    *
    * @param {string} path value to check.
-   * @param {number} [sec] (optional, `options.waitForTimeout` by default) time in seconds to wait
-   * @returns {Promise<void>}
+   * @param {number} [sec] (optional, `waitForTimeout` by default) time in seconds to wait
+   * @returns {void} automatically synchronized promise through #recorder
    */
   async waitCurrentPathEquals(path, sec = null) {
     const timeout = sec || this.options.waitForTimeout
@@ -2128,44 +1465,19 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Checks that the given input field or textarea equals (contains) the given value.
-   * For fuzzy locators, the field is searched by label|name|CSS|XPath|strict locator.
-   *
-   * ```js
-   * I.seeInField('Username', 'davert');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
-   * @param {CodeceptJS.StringOrSecret} value value to check.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
-   * @returns {Promise<void>}
+   * {{> seeInField }}
    */
   async seeInField(field, value, context = null) {
     return this._seeInField('assert', field, value, context)
   }
 
   /**
-   * Opposite to `seeInField`.
-   *
-   * @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
-   * @param {CodeceptJS.StringOrSecret} value value to check.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
-   * @returns {Promise<void>}
+   * {{> dontSeeInField }}
    */
   async dontSeeInField(field, value, context = null) {
     return this._seeInField('negate', field, value, context)
   }
 
-  /**
-   * Shared implementation for `seeInField`/`dontSeeInField`.
-   *
-   * @param {'assert'|'negate'} assertType
-   * @param {CodeceptJS.LocatorOrString} field
-   * @param {CodeceptJS.StringOrSecret} value
-   * @param {?CodeceptJS.LocatorOrString} [context=null]
-   * @returns {Promise<void>}
-   * @protected
-   */
   async _seeInField(assertType, field, value, context = null) {
     const locatorText = new Locator(field).toString()
     if (typeof value === 'boolean') {
@@ -2181,14 +1493,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Grab number of visible elements by locator.
-   *
-   * ```js
-   * let numOfVisibleElements = await I.grabNumberOfVisibleElements('p');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
-   * @returns {Promise<number>} number of visible matched elements.
+   * {{> grabNumberOfVisibleElements }}
    */
   async grabNumberOfVisibleElements(locator) {
     this._assertLayoutSupported('grabNumberOfVisibleElements')
@@ -2197,15 +1502,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Asserts that an element appears a given number of times on the page, and that all matching elements are visible.
-   *
-   * ```js
-   * I.seeNumberOfVisibleElements('.buttons', 3);
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
-   * @param {number} num expected number of elements.
-   * @returns {Promise<void>}
+   * {{> seeNumberOfVisibleElements }}
    */
   async seeNumberOfVisibleElements(locator, num) {
     const found = await this.grabNumberOfVisibleElements(locator)
@@ -2213,39 +1510,21 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Retrieves the current page scroll position.
-   *
-   * ```js
-   * let { x, y } = await I.grabPageScrollPosition();
-   * ```
-   *
-   * @returns {Promise<{x: number, y: number}>} scroll position.
+   * {{> grabPageScrollPosition }}
    */
   async grabPageScrollPosition() {
     return this.executeScript(() => ({ x: window.pageXOffset, y: window.pageYOffset }))
   }
 
   /**
-   * Scrolls to the top of the page.
-   *
-   * ```js
-   * I.scrollPageToTop();
-   * ```
-   *
-   * @returns {Promise<void>}
+   * {{> scrollPageToTop }}
    */
   scrollPageToTop() {
     return this.executeScript(() => window.scrollTo(0, 0))
   }
 
   /**
-   * Scrolls to the bottom of the page.
-   *
-   * ```js
-   * I.scrollPageToBottom();
-   * ```
-   *
-   * @returns {Promise<void>}
+   * {{> scrollPageToBottom }}
    */
   scrollPageToBottom() {
     return this.executeScript(() => {
@@ -2256,17 +1535,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Scrolls to the element matched by locator, or to given coordinates.
-   *
-   * ```js
-   * I.scrollTo('#submit');
-   * I.scrollTo(100, 200);
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString|number} locator element to scroll to, or an X coordinate if no element.
-   * @param {number} [offsetX=0] X offset, or Y coordinate if `locator` is a number.
-   * @param {number} [offsetY=0] Y offset applied when scrolling to an element.
-   * @returns {Promise<void>}
+   * {{> scrollTo }}
    */
   async scrollTo(locator, offsetX = 0, offsetY = 0) {
     if (typeof locator === 'number' && typeof offsetX === 'number') {
@@ -2286,16 +1555,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Retrieves a CSS property from an element located by CSS or XPath.
-   * If more than one element is found - value of first element is returned.
-   *
-   * ```js
-   * const value = await I.grabCssPropertyFrom('h3', 'font-weight');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @param {string} cssProperty CSS property name.
-   * @returns {Promise<string>} CSS value
+   * {{> grabCssPropertyFrom }}
    */
   async grabCssPropertyFrom(locator, cssProperty) {
     const values = await this.grabCssPropertyFromAll(locator, cssProperty)
@@ -2304,15 +1564,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Retrieves an array of CSS properties from elements located by CSS or XPath.
-   *
-   * ```js
-   * const values = await I.grabCssPropertyFromAll('h3', 'font-weight');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @param {string} cssProperty CSS property name.
-   * @returns {Promise<string[]>} array of CSS values
+   * {{> grabCssPropertyFromAll }}
    */
   async grabCssPropertyFromAll(locator, cssProperty) {
     const camelProperty = toCamelCase(cssProperty)
@@ -2322,15 +1574,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Checks that all elements matched by locator have the given CSS properties.
-   *
-   * ```js
-   * I.seeCssPropertiesOnElements('h3', { 'font-weight': 'bold', display: 'block' });
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @param {object} cssProperties object with CSS properties and their values to check.
-   * @returns {Promise<void>}
+   * {{> seeCssPropertiesOnElements }}
    */
   async seeCssPropertiesOnElements(locator, cssProperties) {
     const cssPropertiesCamelCase = convertCssPropertiesToCamelCase(cssProperties)
@@ -2348,16 +1592,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Checks that all elements matched by locator have the given attribute values.
-   * An expected value is matched either as an exact match or as a regular expression against the actual value.
-   *
-   * ```js
-   * I.seeAttributesOnElements('//form', { method: 'post' });
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @param {object} attributes object with attribute names and expected values.
-   * @returns {Promise<void>}
+   * {{> seeAttributesOnElements }}
    */
   async seeAttributesOnElements(locator, attributes) {
     const attrs = Object.keys(attributes)
@@ -2376,14 +1611,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Focuses a given element.
-   *
-   * ```js
-   * I.focus('#name');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @returns {Promise<void>}
+   * {{> focus }}
    */
   async focus(locator) {
     const armed = this._armActionSettle()
@@ -2393,14 +1621,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Removes focus from a given element.
-   *
-   * ```js
-   * I.blur('#name');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @returns {Promise<void>}
+   * {{> blur }}
    */
   async blur(locator) {
     const armed = this._armActionSettle()
@@ -2410,25 +1631,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Types characters into the currently focused element (as set by `click`, `focus`, etc). Each
-   * character dispatches a real `keydown` → `keypress` → (value mutated) → `input` → `keyup`
-   * sequence, and mutates a `contenteditable` host's `textContent` instead of `.value`, so this
-   * works on rich-text/contenteditable targets as well as `input`/`textarea`. Mirrors Puppeteer's
-   * `type(text, options)` semantics.
-   *
-   * Without a `delay`, every character is dispatched in a single round-trip to the page. With a
-   * `delay`, characters are dispatched one round-trip at a time so the requested pause actually
-   * elapses between key presses.
-   *
-   * ```js
-   * I.click('Name');
-   * I.type('CodeceptJS');
-   * I.type(['C', 'o', 'd', 'e']);
-   * ```
-   *
-   * @param {string|string[]} keys characters to type, either as a string or an array of characters.
-   * @param {number} [delay] (optional) delay in milliseconds between key presses.
-   * @returns {Promise<void>}
+   * {{> type }}
    */
   async type(keys, delay = null) {
     await checkFocusBeforeType(this)
@@ -2477,9 +1680,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Presses a key or key combination on the currently focused element.
-   * Under `options.strict`, a modifier+editing-key combination (e.g. `Ctrl+A`) dispatched with no
-   * element focused throws `NonFocusedType`, mirroring `focusCheck.js`'s behavior on other helpers.
+   * Presses a key or a key combination on the focused element.
    *
    * ```js
    * I.pressKey('Enter');
@@ -2487,7 +1688,7 @@ class CDPBrowser extends Helper {
    * ```
    *
    * @param {string|string[]} key a key or an array of keys to combine (modifiers first).
-   * @returns {Promise<void>}
+   * @returns {void} automatically synchronized promise through #recorder
    */
   async pressKey(key) {
     const originalKey = Array.isArray(key) ? key : [key]
@@ -2513,15 +1714,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Resizes the browser viewport.
-   *
-   * ```js
-   * I.resizeWindow(1024, 768);
-   * ```
-   *
-   * @param {number|'maximize'} width window width, or `'maximize'`.
-   * @param {number} [height] window height.
-   * @returns {Promise<void>}
+   * {{> resizeWindow }}
    */
   async resizeWindow(width, height) {
     if (width === 'maximize') {
@@ -2533,15 +1726,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Performs a double-click on an element matched by locator.
-   *
-   * ```js
-   * I.doubleClick('Edit');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator clickable element located by text, or any element located by CSS|XPath|strict locator.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default, currently ignored by this helper).
-   * @returns {Promise<void>}
+   * {{> doubleClick }}
    */
   async doubleClick(locator, context = null) {
     const armed = this._armActionSettle()
@@ -2551,15 +1736,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Performs a right-click on an element matched by locator.
-   *
-   * ```js
-   * I.rightClick('Menu');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator clickable element located by text, or any element located by CSS|XPath|strict locator.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default, currently ignored by this helper).
-   * @returns {Promise<void>}
+   * {{> rightClick }}
    */
   async rightClick(locator, context = null) {
     const armed = this._armActionSettle()
@@ -2569,18 +1746,18 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Clicks at global page coordinates, or at coordinates relative to an element.
-   * Dispatches a real CDP mouse click and therefore requires a real layout engine.
+   * Clicks at page coordinates, or at coordinates relative to an element.
+   * Requires a browser that renders layout.
    *
    * ```js
-   * I.clickXY(100, 200); // global coordinates
+   * I.clickXY(100, 200); // page coordinates
    * I.clickXY('#area', 50, 30); // relative to #area
    * ```
    *
-   * @param {CodeceptJS.LocatorOrString|number} locator element to click relative to, or a global X coordinate.
-   * @param {number} [x] X coordinate relative to element, or global Y coordinate if `locator` is a number.
-   * @param {number} [y] Y coordinate relative to element.
-   * @returns {Promise<void>}
+   * @param {CodeceptJS.LocatorOrString|number} locator element to click relative to, or the X page coordinate.
+   * @param {number} [x] X coordinate relative to the element, or the Y page coordinate if `locator` is a number.
+   * @param {number} [y] Y coordinate relative to the element.
+   * @returns {void} automatically synchronized promise through #recorder
    */
   async clickXY(locator, x, y) {
     this._assertLayoutSupported('clickXY')
@@ -2605,15 +1782,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Waits for an element to become visible (by default waits for `options.waitForTimeout` seconds).
-   *
-   * ```js
-   * I.waitForVisible('#popup', 5);
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @param {number} [sec] (optional, `options.waitForTimeout` by default) time in seconds to wait
-   * @returns {Promise<void>}
+   * {{> waitForVisible }}
    */
   async waitForVisible(locator, sec = null) {
     this._assertLayoutSupported('waitForVisible')
@@ -2627,15 +1796,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Waits for an element to become invisible (by default waits for `options.waitForTimeout` seconds).
-   *
-   * ```js
-   * I.waitForInvisible('#popup', 5);
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @param {number} [sec] (optional, `options.waitForTimeout` by default) time in seconds to wait
-   * @returns {Promise<void>}
+   * {{> waitForInvisible }}
    */
   async waitForInvisible(locator, sec = null) {
     this._assertLayoutSupported('waitForInvisible')
@@ -2649,26 +1810,14 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Waits for an element to be hidden. Alias of `waitForInvisible`.
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @param {number} [sec] (optional, `options.waitForTimeout` by default) time in seconds to wait
-   * @returns {Promise<void>}
+   * {{> waitToHide }}
    */
   async waitToHide(locator, sec = null) {
     return this.waitForInvisible(locator, sec)
   }
 
   /**
-   * Waits for an element to be removed from the DOM (by default waits for `options.waitForTimeout` seconds).
-   *
-   * ```js
-   * I.waitForDetached('#popup', 5);
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @param {number} [sec] (optional, `options.waitForTimeout` by default) time in seconds to wait
-   * @returns {Promise<void>}
+   * {{> waitForDetached }}
    */
   async waitForDetached(locator, sec = null) {
     const timeout = sec || this.options.waitForTimeout
@@ -2681,10 +1830,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Checks that a cookie with the given name is set.
-   *
-   * @param {string} name cookie name.
-   * @returns {Promise<void>}
+   * {{> seeCookie }}
    */
   async seeCookie(name) {
     const cookies = await this.grabCookies()
@@ -2692,10 +1838,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Checks that a cookie with the given name is not set.
-   *
-   * @param {string} name cookie name.
-   * @returns {Promise<void>}
+   * {{> dontSeeCookie }}
    */
   async dontSeeCookie(name) {
     const cookies = await this.grabCookies()
@@ -2703,15 +1846,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Waits for a cookie with the given name to be set (by default waits for `options.waitForTimeout` seconds).
-   *
-   * ```js
-   * I.waitForCookie('auth', 5);
-   * ```
-   *
-   * @param {string} name cookie name.
-   * @param {number} [sec] (optional, `options.waitForTimeout` by default) time in seconds to wait
-   * @returns {Promise<void>}
+   * {{> waitForCookie }}
    */
   async waitForCookie(name, sec = null) {
     const timeout = sec || this.options.waitForTimeout
@@ -2719,15 +1854,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Retrieves the inner HTML from an element located by CSS or XPath.
-   * If more than one element is found - HTML of first element is returned.
-   *
-   * ```js
-   * let postHTML = await I.grabHTMLFrom('#post');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @returns {Promise<string>} HTML code for an element
+   * {{> grabHTMLFrom }}
    */
   async grabHTMLFrom(locator) {
     const html = await this.grabHTMLFromAll(locator)
@@ -2736,14 +1863,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Retrieves the inner HTML from elements located by CSS or XPath.
-   *
-   * ```js
-   * let postHTMLs = await I.grabHTMLFromAll('.post');
-   * ```
-   *
-   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
-   * @returns {Promise<string[]>} HTML code for matched elements
+   * {{> grabHTMLFromAll }}
    */
   async grabHTMLFromAll(locator) {
     const res = await this._run(this._candidates(locator), 'innerHtml')
@@ -2751,18 +1871,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Executes an asynchronous script (callback-style, in the same way `window.setTimeout` works)
-   * in the browser context and returns the value passed to `done`.
-   *
-   * ```js
-   * const val = await I.executeAsyncScript(function(val, done) {
-   *   setTimeout(() => done(val + 1), 100)
-   * }, 5)
-   * ```
-   *
-   * @param {function} fn - an asynchronous function to be executed in the browser context; its last argument is a `done` callback.
-   * @param {...any} args - arguments to pass into the function (before `done`).
-   * @returns {Promise<any>} the value passed to `done`.
+   * {{> executeAsyncScript }}
    */
   async executeAsyncScript(fn, ...args) {
     const fnBody = typeof fn === 'function' ? fn.toString() : fn
@@ -2770,19 +1879,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Starts recording network traffic via CDP's `Network.requestWillBeSent`/`responseReceived`
-   * events, in the same shape (`{url, method, requestHeaders, requestPostData, response}` per
-   * request, `response` a promise of `{url(), status(), statusText(), body()}`) the shared
-   * `lib/helper/network` actions expect from Puppeteer/Playwright. The CDP listeners are
-   * installed once (lazily) and left in place afterwards, since `CDPConnection` has no listener
-   * removal and `this.cdp` is reused across tests; they filter by `this.sessionId`, so only the
-   * currently active test/page's requests are recorded.
-   *
-   * ```js
-   * I.startRecordingTraffic();
-   * ```
-   *
-   * @returns {Promise<void>}
+   * {{> startRecordingTraffic }}
    */
   async startRecordingTraffic() {
     this.flushNetworkTraffics()
@@ -2797,12 +1894,6 @@ class CDPBrowser extends Helper {
     this.cdp.on('Network.loadingFailed', (params, sessionId) => this._onTrafficLoadingFailed(params, sessionId))
   }
 
-  /**
-   * `Network.requestWillBeSent` handler, pushed into `this.requests` when it belongs to the
-   * currently active session and recording is on.
-   *
-   * @protected
-   */
   _onTrafficRequest(params, sessionId) {
     if (!this.recording || sessionId !== this.sessionId) return
     let resolveResponse
@@ -2827,12 +1918,6 @@ class CDPBrowser extends Helper {
     })
   }
 
-  /**
-   * `Network.responseReceived` handler, resolving the matching pending `response` promise pushed
-   * by `_onTrafficRequest` with a Puppeteer-`HTTPResponse`-like object.
-   *
-   * @protected
-   */
   _onTrafficResponse(params, sessionId) {
     if (sessionId !== this.sessionId) return
     const resolve = this._pendingTrafficResponses.get(params.requestId)
@@ -2854,13 +1939,6 @@ class CDPBrowser extends Helper {
     })
   }
 
-  /**
-   * `Network.loadingFailed` handler, resolving a still-pending `response` promise to `null`
-   * (matching Puppeteer's `request.response()` for a failed request) so `grabRecordedNetworkTraffics`
-   * never awaits a promise that would otherwise never settle.
-   *
-   * @protected
-   */
   _onTrafficLoadingFailed(params, sessionId) {
     if (sessionId !== this.sessionId) return
     const resolve = this._pendingTrafficResponses.get(params.requestId)
@@ -2891,14 +1969,7 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Stops recording network traffic started by `startRecordingTraffic`. Already-recorded requests
-   * in `this.requests` are kept; only new requests stop being appended.
-   *
-   * ```js
-   * I.stopRecordingTraffic();
-   * ```
-   *
-   * @returns {void}
+   * {{> stopRecordingTraffic }}
    */
   stopRecordingTraffic() {
     this.recording = false
@@ -2912,20 +1983,15 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Starts recording a CDP `Page.startScreencast` session for the current test's target: frames
-   * arrive as `Page.screencastFrame` events, are acknowledged immediately (`Page.screencastFrameAck`,
-   * required or the browser stops sending more), and buffered in `this._screencastFrames`. The
-   * underlying `Page.screencastFrame` listener is installed once (lazily) and left in place, like
-   * `startRecordingTraffic`'s listeners, since `CDPConnection` has no listener-removal API; it
-   * filters by `this.sessionId` so only the currently active test's frames are buffered. Call
-   * `stopScreencast` to end the capture and assemble the buffered frames into an APNG.
+   * Starts recording a video of the page. Stop it with `stopScreencast`.
+   * Usually enabled through the `screencast` plugin rather than called directly.
    *
    * ```js
    * I.startScreencast();
    * ```
    *
-   * @param {object} [options] {maxWidth: number, maxHeight: number, quality: number, everyNthFrame: number} — CDP `Page.startScreencast` pass-throughs. `format` is always `'png'`.
-   * @returns {Promise<void>}
+   * @param {object} [options] `{ maxWidth, maxHeight, quality, everyNthFrame }`
+   * @returns {void} automatically synchronized promise through #recorder
    */
   async startScreencast(options = {}) {
     if (!this._screencastListenerInstalled) {
@@ -2942,14 +2008,6 @@ class CDPBrowser extends Helper {
     await this.cdp.send('Page.startScreencast', params, this.sessionId)
   }
 
-  /**
-   * `Page.screencastFrame` handler: ignores frames from a session other than the currently active
-   * one (stale frames from a previous test, since the listener is never removed), acknowledges the
-   * frame so the browser keeps sending more, and buffers `{data, timestamp}` for `stopScreencast`
-   * to assemble.
-   *
-   * @protected
-   */
   _onScreencastFrame(params, sessionId) {
     if (!this._screencastActive || sessionId !== this.sessionId) return
     this._screencastFrames.push({ data: params.data, timestamp: params.metadata && params.metadata.timestamp })
@@ -2957,23 +2015,14 @@ class CDPBrowser extends Helper {
   }
 
   /**
-   * Stops the screencast started by `startScreencast` and assembles the buffered frames into a
-   * single APNG (Animated PNG) file, returned as a Buffer. Frame delays are derived from the CDP
-   * frame metadata's `timestamp` deltas (frame arrival is activity-driven — Obscura and Chrome both
-   * only emit a frame on damage — so this reproduces the actual pacing of what happened, not a
-   * fixed frame rate); the last frame is held for `options.lastFrameDelayMs` (default 1000ms) since
-   * it has no "next" frame to derive a delay from. Every frame is checked for the PNG signature
-   * before assembly — CDP's `format: 'png'` is honored by both Chrome and Obscura (verified
-   * directly), but if some other engine ever sends a different format regardless, this reports it
-   * via `debugSection` and returns `null` instead of muxing a broken file. Returns `null` if no
-   * frames were captured (screencast never started, or stopped immediately after starting).
+   * Stops the recording started by `startScreencast` and returns it as an animated PNG.
    *
    * ```js
-   * const apngBuffer = await I.stopScreencast();
+   * const video = await I.stopScreencast();
    * ```
    *
-   * @param {object} [options] {lastFrameDelayMs: number} — hold time in milliseconds for the final frame (default 1000).
-   * @returns {Promise<object>} a Buffer with the assembled APNG, or null if there was nothing to assemble.
+   * @param {object} [options] `{ lastFrameDelayMs }`: how long the last frame is shown, in milliseconds (1000 by default).
+   * @returns {Promise<Buffer|null>} APNG data, or `null` if no frames were recorded.
    */
   async stopScreencast(options = {}) {
     this._screencastActive = false