codeceptjs 4.2.0 → 4.2.1-beta.1

package/typings/promiseBasedTypes.d.ts

@@ -1193,16 +1193,16 @@ declare namespace CodeceptJS {
      *
      * This helper should be configured in codecept.conf.js
      * @property [url = http://localhost] - base url of website to be tested.
-     * @property [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.
-     * @property [headers = {}] - headers sent with the endpoint resolution request and the WebSocket handshake. Useful for authenticated remote browser providers.
-     * @property [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`.
-     * @property [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.
-     * @property [capabilities = {}] - pre-seed detected browser capabilities (`layout`, `xpath`, `screenshot`, `innerText`) to skip runtime probing. Values set here are never overwritten by `_probeCapabilities`/`_ensureClient`.
-     * @property [waitForTimeout = 5] - default wait* timeout in seconds, used by helpers built on top of this class.
-     * @property [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.
-     * @property [pollInterval = 25] - interval in milliseconds between retries while polling for a condition (e.g. page ready state, `waitFor*`). Distinct from `waitForAction`.
-     * @property [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).
-     * @property [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.
+     * @property [endpoint = http://127.0.0.1:9222] - Chrome DevTools Protocol endpoint: an `http(s)://` address or a `ws(s)://` debugger URL.
+     * @property [headers = {}] - headers sent when connecting to the endpoint, e.g. for authenticated remote browsers.
+     * @property [input = auto] - how actions are dispatched: `cdp` (real mouse and keyboard events) or `synthetic` (DOM events). `auto` picks `cdp` when the browser renders layout.
+     * @property [xpathPolyfill = auto] - inject an XPath polyfill for browsers with incomplete XPath support. `auto` detects when it is needed.
+     * @property [capabilities = {}] - browser capabilities (`layout`, `xpath`, `screenshot`, `innerText`) to use instead of detecting them at runtime.
+     * @property [waitForTimeout = 5] - default timeout for wait* actions, in seconds.
+     * @property [waitForAction] - fixed delay after each action, in milliseconds. When unset, actions wait only for the navigation they trigger.
+     * @property [pollInterval = 25] - interval between checks while waiting, in milliseconds.
+     * @property [getPageTimeout = 30] - maximum time to wait for a page to load, in seconds.
+     * @property [waitForNavigation = load] - when a navigation is considered finished: `load`, `domcontentloaded`, or `networkidle`.
      */
     type CDPBrowserConfig = {
         url?: string;
@@ -1226,6 +1226,8 @@ declare namespace CodeceptJS {
      * 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
      *
@@ -1248,416 +1250,160 @@ declare namespace CodeceptJS {
     class CDPBrowserTs {
         constructor(config: CDPBrowserConfig);
         /**
-         * 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.
+         * 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 config - the config object the helper was constructed with.
+         * @param server - the server descriptor described above.
          */
-        _init(): Promise<any>;
+        protected _manageServer(config: any, server: any): Promise<any>;
         /**
-         * 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.
+         * 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.
          *
-         * 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 a `ws(s)://` debugger URL ready to be passed to `CDPConnection`.
+         * 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 _resolveEndpoint(): Promise<string>;
+        protected _resolveSelfManaged(): Promise<any>;
         /**
-         * Resolves the CDP endpoint and opens the underlying `CDPConnection`, storing it on `this.cdp`.
+         * 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.
          */
-        protected _connect(): Promise<any>;
-        /**
-         * 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`.
-         *
-         * 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.
-         */
-        protected _before(): Promise<any>;
-        /**
-         * 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(): Promise<any>;
-        /**
-         * 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 loaderId - the loader id of the navigation to wait for, from `Page.navigate`'s response.
-         * @param eventName - the `Page.lifecycleEvent` name to wait for (e.g. `load`, `DOMContentLoaded`, `networkIdle`).
-         * @param timeoutSec - maximum time to wait, in seconds.
-         */
-        protected _waitForLoadEvent(loaderId: string, eventName: string, timeoutSec: number): Promise<any>;
-        /**
-         * 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.
-         */
-        protected _armActionSettle(): Promise<any>;
-        /**
-         * 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 loaderId - loader id from the triggering `Page.navigate` response, if any.
-         * @param timeoutMessage - error message used if the readyState poll times out.
-         */
-        protected _waitForPageLoad(loaderId: string | null, timeoutMessage: string): Promise<void>;
-        /**
-         * 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 _after(): Promise<any>;
+        protected _resolveBinary(): Promise<any>;
         /**
-         * 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.
+         * 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 a free port.
          */
-        protected _finishTest(): Promise<any>;
+        protected _findFreePort(): Promise<number>;
         /**
-         * 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 expression - a JavaScript expression (or IIFE) to run in the page context.
-         * @returns the evaluated value, or `undefined` if the expression has no result.
-         */
-        protected _evaluate(expression: string): Promise<any>;
-        /**
-         * 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 _ensureClient(): Promise<any>;
-        /**
-         * 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.
-         */
-        protected _installClient(needsXPath?: boolean): Promise<any>;
-        /**
-         * 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.
-         */
-        protected _candidatesNeedXPath(candidates: { type: string; value: string; }[], layers: { type: string; value: string; }[][]): Promise<any>;
-        /**
-         * 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 `true` if the polyfill should be injected.
-         */
-        protected _needsXPathPolyfill(): Promise<boolean>;
-        /**
-         * 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 `true` if the `visibleText()` fallback should be used.
-         */
-        protected _needsVisibleTextFallback(): Promise<boolean>;
-        /**
-         * 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 _probeCapabilities(): Promise<any>;
-        /**
-         * 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 candidates - locator strategies to try, in order, until one matches at least one element.
-         * @param action - name of the action to run against the matched elements (e.g. `count`, `click`, `fill`).
-         * @param [payload] - extra data the action needs (e.g. `{ value }` for `fill`).
-         * @param [context = null] - element to search in, narrowing the candidates below it.
-         * @returns number of matched elements and the action's result.
-         */
-        protected _run(candidates: { type: 'css' | 'xpath'; value: string; }[], action: string, payload?: any, context?: CodeceptJS.LocatorOrString): Promise<{ found: number; result: any; }>;
-        /**
-         * 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 selection - `{index}` or `{strict: true}`, mirroring `_selectionDescriptor`.
-         */
-        protected _runSelected(candidates: { type: 'css' | 'xpath'; value: string; }[], action: string, payload: any | null, selection: any | null, context?: CodeceptJS.LocatorOrString): Promise<{ found: number; result: any; }>;
-        /**
-         * 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.
-         */
-        protected _selectionDescriptor(): Promise<any>;
-        /**
-         * A short, human-readable label built from `candidates`, used in `_run`'s elementIndex/strict
-         * error messages when no locator string is otherwise available.
-         */
-        protected _candidatesLabel(candidates: { type: 'css' | 'xpath'; value: string; }[]): Promise<any>;
-        /**
-         * 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 locator - element located by CSS|XPath|strict locator.
+         * Probes a `/json/version`-style URL with a short timeout, used for the courtesy-attach check.
+         * @returns true if the URL answered.
          */
-        _withinBegin(locator: CodeceptJS.LocatorOrString): Promise<void>;
+        protected _probeUp(url: string): Promise<boolean>;
         /**
-         * Ends the current `within` block, restoring unscoped element lookups.
+         * 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.
          */
-        _withinEnd(): Promise<void>;
+        protected _waitForServer(): Promise<any>;
         /**
-         * Repeatedly calls `fn` until it returns a truthy value or `timeoutSec` elapses, checking
-         * immediately and waiting `options.pollInterval` milliseconds between subsequent attempts.
-         * @param fn - the condition to poll; should resolve to a truthy value once satisfied.
-         * @param timeoutSec - maximum time to poll, in seconds.
-         * @param message - error message used when the timeout is reached.
-         * @param [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 the truthy value returned by `fn`.
+         * 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 _poll(fn: (...params: any[]) => any, timeoutSec: number, message: string, cancelToken?: any): Promise<any>;
+        protected _connect(): Promise<any>;
         /**
-         * 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 path - an absolute URL or a path relative to `options.url`.
+         * Hook executed after all tests are run. Closes the underlying `CDPConnection` (and its
+         * 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 _url(path: string): Promise<any>;
+        protected _finishTest(): Promise<any>;
         /**
-         * Opens a web page in the current session.
+         * Opens a web page in a browser. Requires relative or absolute url.
+         * If url starts with `/`, opens a web page of a site defined in `url` config parameter.
          *
          * ```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 url - url path or global url.
          */
-        amOnPage(url: string): Promise<void>;
+        amOnPage(url: string): Promise<any>;
         /**
-         * Reloads the current page.
+         * Reload the current page.
          *
          * ```js
          * I.refreshPage();
          * ```
-         *
-         * Triggers `Page.reload` and waits (up to `options.getPageTimeout` seconds) for
-         * `document.readyState` to reach `'complete'`.
          */
-        refreshPage(): Promise<void>;
+        refreshPage(): Promise<any>;
         /**
-         * Executes a JavaScript function in the browser context and returns its result.
+         * Executes sync script on a page.
+         * Pass arguments to function as additional parameters.
+         * Will return execution result to a test.
+         * In this case you should use async function and await to receive results.
          *
-         * 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.
+         * Example with jQuery DatePicker:
          *
          * ```js
-         * let title = await I.executeScript(() => document.title);
-         * let sum = await I.executeScript((a, b) => a + b, 2, 3);
+         * // change date of jQuery DatePicker
+         * I.executeScript(function() {
+         *   // now we are inside browser context
+         *   $('date').datetimepicker('setDate', new Date());
+         * });
          * ```
+         * Can return values. Don't forget to use `await` to get them.
          *
-         * If the function returns a promise, `executeScript` waits for it to resolve.
-         * @param fn - a JavaScript function to be executed in the browser context, or a string expression.
-         * @param args - arguments to pass into the function.
-         * @returns the value returned (or resolved) by the function.
+         * ```js
+         * let date = await I.executeScript(function(el) {
+         *   // only basic types can be returned
+         *   return $(el).datetimepicker('getDate').toString();
+         * }, '#date'); // passing jquery selector
+         * ```
+         * @param fn - function to be executed in browser context.
+         * @param args - to be passed to function.
+         * @returns script return value
          */
         executeScript(fn: string | ((...params: any[]) => any), ...args: any[]): Promise<any>;
         /**
-         * Retrieves the page URL of the current page.
+         * Get current URL from browser.
+         * Resumes test execution, so should be used inside an async function.
          *
          * ```js
          * let url = await I.grabCurrentUrl();
          * console.log(`Current URL is [${url}]`);
          * ```
-         * @returns current URL.
+         * @returns current URL
          */
         grabCurrentUrl(): Promise<string>;
         /**
-         * Retrieves a page title.
+         * Retrieves a page title and returns it to test.
+         * Resumes test execution, so **should be used inside async with `await`** operator.
          *
          * ```js
          * let title = await I.grabTitle();
          * ```
-         * @returns title of the page.
+         * @returns title
          */
         grabTitle(): Promise<string>;
         /**
-         * Retrieves the source code of the current page.
+         * Retrieves page source and returns it to test.
+         * Resumes test execution, so **should be used inside async function with `await`** operator.
          *
          * ```js
          * let pageSource = await I.grabSource();
          * ```
-         * @returns source code of the current page (the outer HTML of `<html>`).
+         * @returns source code
          */
         grabSource(): Promise<string>;
-        /**
-         * 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 locator - element located by CSS|XPath|strict locator, or plain fuzzy text.
-         * @param [kind = 'element'] - matching strategy to use when `locator` is fuzzy.
-         */
-        protected _candidates(locator: CodeceptJS.LocatorOrString, kind?: 'element' | 'clickable' | 'field' | 'checkable'): Promise<any>;
-        /**
-         * 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.
-         */
-        protected _textSource(context: CodeceptJS.LocatorOrString): Promise<string>;
-        /**
-         * 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.
-         */
-        protected _runTextCheck(text: string, opts: any): Promise<{ found: boolean; snippet: string | null; }>;
-        /**
-         * 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.
-         */
-        protected _checkText(text: string, context: CodeceptJS.LocatorOrString, negate: boolean): Promise<void>;
         /**
          * Checks that a page contains a visible text.
          * Use context parameter to narrow down the search.
@@ -1670,7 +1416,7 @@ declare namespace CodeceptJS {
          * @param text - expected on page.
          * @param [context = null] - (optional, `null` by default) element located by CSS|Xpath|strict locator in which to search for text.
          */
-        see(text: string, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        see(text: string, context?: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Opposite to `see`. Checks that a text is not present on a page.
          * Use context parameter to narrow down the search.
@@ -1680,9 +1426,9 @@ declare namespace CodeceptJS {
          * I.dontSee('Login', '.nav'); // no login inside .nav element
          * ```
          * @param text - which is not present.
-         * @param [context = null] - (optional) element located by CSS|XPath|strict locator in which to perform search.
+         * @param [context = null] - (optional) element located by CSS|XPath|strict locator in which to perfrom search.
          */
-        dontSee(text: string, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        dontSee(text: string, context?: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Checks that the current page contains the given string in its raw source code.
          *
@@ -1691,12 +1437,16 @@ declare namespace CodeceptJS {
          * ```
          * @param text - value to check.
          */
-        seeInSource(text: string): Promise<void>;
+        seeInSource(text: string): Promise<any>;
         /**
-         * Checks that the current page does not contain the given string in its raw source code.
-         * @param text - value to check.
+         * Checks that the current page does not contains the given string in its raw source code.
+         *
+         * ```js
+         * I.dontSeeInSource('<!--'); // no comments in source
+         * ```
+         * @param value - to check.
          */
-        dontSeeInSource(text: string): Promise<void>;
+        dontSeeInSource(value: string): Promise<any>;
         /**
          * Checks that current url contains a provided fragment.
          *
@@ -1705,12 +1455,12 @@ declare namespace CodeceptJS {
          * ```
          * @param url - a fragment to check
          */
-        seeInCurrentUrl(url: string): Promise<void>;
+        seeInCurrentUrl(url: string): Promise<any>;
         /**
          * Checks that current url does not contain a provided fragment.
          * @param url - value to check.
          */
-        dontSeeInCurrentUrl(url: string): Promise<void>;
+        dontSeeInCurrentUrl(url: string): Promise<any>;
         /**
          * Checks that title contains text.
          *
@@ -1719,9 +1469,9 @@ declare namespace CodeceptJS {
          * ```
          * @param text - text value to check.
          */
-        seeInTitle(text: string): Promise<void>;
+        seeInTitle(text: string): Promise<any>;
         /**
-         * Checks that a given Element is present in the DOM.
+         * Checks that a given Element is present in the DOM
          * Element is located by CSS or XPath.
          *
          * ```js
@@ -1729,43 +1479,47 @@ declare namespace CodeceptJS {
          * ```
          * @param locator - element located by CSS|XPath|strict locator.
          */
-        seeElementInDOM(locator: CodeceptJS.LocatorOrString): Promise<void>;
+        seeElementInDOM(locator: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * 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 locator - located by CSS|XPath|strict locator.
-         */
-        dontSeeElementInDOM(locator: CodeceptJS.LocatorOrString): Promise<void>;
-        /**
-         * 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 action - name of the calling assertion, used in the error message.
+         * @param locator - located by CSS|XPath|Strict locator.
          */
-        protected _assertLayoutSupported(action: string): Promise<any>;
+        dontSeeElementInDOM(locator: CodeceptJS.LocatorOrString): Promise<any>;
         /**
-         * Checks that a given Element is visible.
+         * Checks that a given Element is visible
          * Element is located by CSS or XPath.
          *
+         * The second parameter is a context (CSS or XPath locator) to narrow the search.
+         *
          * ```js
          * I.seeElement('#modal');
+         * I.seeElement('#modal', '#container');
+         * // using ARIA role locator
+         * I.seeElement({role: 'dialog'});
          * ```
+         *
+         * > ℹ️ ARIA role locators (`{role, name}`) match elements the way assistive technology does and survive markup refactors. See [Locators](/locators#aria-locators).
          * @param locator - located by CSS|XPath|strict locator.
-         * @param [context = null] - (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+         * @param [context = null] - (optional, `null` by default) element located by CSS | XPath | strict locator.
          */
-        seeElement(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        seeElement(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<any>;
         /**
-         * Opposite to `seeElement`. Checks that element is not visible.
+         * Opposite to `seeElement`. Checks that element is not visible (or in DOM)
+         *
+         * The second parameter is a context (CSS or XPath locator) to narrow the search.
          *
          * ```js
          * I.dontSeeElement('.modal'); // modal is not shown
+         * I.dontSeeElement('.modal', '#container');
          * ```
-         * @param locator - located by CSS|XPath|strict locator.
-         * @param [context = null] - (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+         * @param locator - located by CSS|XPath|Strict locator.
+         * @param [context = null] - (optional, `null` by default) element located by CSS | XPath | strict locator.
          */
-        dontSeeElement(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        dontSeeElement(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Verifies that the specified checkbox is checked.
          *
@@ -1774,19 +1528,20 @@ declare namespace CodeceptJS {
          * I.seeCheckboxIsChecked('#agree'); // I suppose user agreed to terms
          * I.seeCheckboxIsChecked({css: '#signup_form input[type=checkbox]'});
          * ```
-         * @param locator - located by label|name|CSS|XPath|strict locator.
+         * @param field - located by label|name|CSS|XPath|strict locator.
          */
-        seeCheckboxIsChecked(locator: CodeceptJS.LocatorOrString): Promise<void>;
+        seeCheckboxIsChecked(field: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Verifies that the specified checkbox is not checked.
          *
          * ```js
          * I.dontSeeCheckboxIsChecked('#agree'); // located by ID
          * I.dontSeeCheckboxIsChecked('I agree to terms'); // located by label
+         * I.dontSeeCheckboxIsChecked('agree'); // located by name
          * ```
-         * @param locator - located by label|name|CSS|XPath|strict locator.
+         * @param field - located by label|name|CSS|XPath|strict locator.
          */
-        dontSeeCheckboxIsChecked(locator: CodeceptJS.LocatorOrString): Promise<void>;
+        dontSeeCheckboxIsChecked(field: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * 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.
@@ -1796,49 +1551,42 @@ declare namespace CodeceptJS {
          * ```
          * If multiple elements found returns first element.
          * @param locator - element located by CSS|XPath|strict locator.
-         * @returns text value
+         * @returns attribute value
          */
         grabTextFrom(locator: CodeceptJS.LocatorOrString): Promise<string>;
         /**
-         * Retrieves all texts from elements located by CSS or XPath and returns it to test.
+         * Retrieves all texts 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 pins = await I.grabTextFromAll('#pin li');
          * ```
          * @param locator - element located by CSS|XPath|strict locator.
-         * @returns array of text values
+         * @returns attribute value
          */
         grabTextFromAll(locator: CodeceptJS.LocatorOrString): Promise<string[]>;
         /**
-         * 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.
+         * Grab WebElements for given locator
+         * Resumes test execution, so **should be used inside an async function with `await`** operator.
          *
          * ```js
-         * const buttons = await I.grabWebElements({ role: 'button' });
+         * const webElements = await I.grabWebElements('#button');
          * ```
          * @param locator - element located by CSS|XPath|strict locator.
-         * @returns array of WebElement instances.
+         * @returns WebElement of being used Web helper
          */
-        grabWebElements(locator: CodeceptJS.LocatorOrString): Promise<object[]>;
+        grabWebElements(locator: CodeceptJS.LocatorOrString): Promise<any>;
         /**
-         * Retrieves the first `WebElement` matching a locator.
+         * Grab WebElement for given locator
+         * Resumes test execution, so **should be used inside an async function with `await`** operator.
          *
          * ```js
-         * const button = await I.grabWebElement({ role: 'button', text: 'Submit' });
+         * const webElement = await I.grabWebElement('#button');
          * ```
          * @param locator - element located by CSS|XPath|strict locator.
-         * @returns a WebElement instance.
-         */
-        grabWebElement(locator: CodeceptJS.LocatorOrString): Promise<object>;
-        /**
-         * 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.
+         * @returns WebElement of being used Web helper
          */
-        protected _texts(candidates: { type: string; value: string | object; }[]): Promise<{ found: number; result: any; }>;
+        grabWebElement(locator: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * 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.
@@ -1852,14 +1600,14 @@ declare namespace CodeceptJS {
          */
         grabValueFrom(locator: CodeceptJS.LocatorOrString): Promise<string>;
         /**
-         * Retrieves an array of values from fields located by CSS or XPath and returns it to test.
+         * Retrieves an array of value from a form 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 locator - field located by label|name|CSS|XPath|strict locator.
-         * @returns array of attribute values
+         * @returns attribute value
          */
         grabValueFromAll(locator: CodeceptJS.LocatorOrString): Promise<string[]>;
         /**
@@ -1884,7 +1632,7 @@ declare namespace CodeceptJS {
          * ```
          * @param locator - element located by CSS|XPath|strict locator.
          * @param attr - attribute name.
-         * @returns array of attribute values
+         * @returns attribute value
          */
         grabAttributeFromAll(locator: CodeceptJS.LocatorOrString, attr: string): Promise<string[]>;
         /**
@@ -1904,13 +1652,13 @@ declare namespace CodeceptJS {
          * 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.
+         * If no locator is provided, defaults to clicking the body element (`'//body'`).
+         *
+         * The second parameter is a context (CSS or XPath locator) to narrow the search.
          *
          * ```js
+         * // click body element (default)
+         * I.click();
          * // simple link
          * I.click('Logout');
          * // button of form
@@ -1919,22 +1667,30 @@ declare namespace CodeceptJS {
          * I.click('#form input[type=submit]');
          * // XPath
          * I.click('//form/*[@type=submit]');
+         * // link in context
+         * I.click('Logout', '#nav');
          * // using strict locator
          * I.click({css: 'nav a.login'});
+         * // using ARIA role locator
+         * I.click({role: 'button', name: 'Submit'});
          * ```
-         * @param locator - clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+         *
+         * > ℹ️ ARIA role locators (`{role, name}`) match elements the way assistive technology does and survive markup refactors. See [Locators](/locators#aria-locators).
+         * @param [locator = '//body'] - (optional, `'//body'` by default) clickable link or button located by text, or any element located by CSS|XPath|strict locator.
          * @param [context = null] - (optional, `null` by default) element to search in CSS|XPath|Strict locator.
          */
-        click(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        click(locator?: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString | null): Promise<any>;
         /**
          * 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.
+         * Unlike normal click instead of sending native event, emulates a click with JavaScript.
+         * 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.
          *
+         * The second parameter is a context (CSS or XPath locator) to narrow the search.
+         *
          * ```js
          * // simple link
          * I.forceClick('Logout');
@@ -1944,46 +1700,21 @@ declare namespace CodeceptJS {
          * I.forceClick('#form input[type=submit]');
          * // XPath
          * I.forceClick('//form/*[@type=submit]');
+         * // link in context
+         * I.forceClick('Logout', '#nav');
          * // using strict locator
          * I.forceClick({css: 'nav a.login'});
          * ```
          * @param locator - clickable link or button located by text, or any element located by CSS|XPath|strict locator.
          * @param [context = null] - (optional, `null` by default) element to search in CSS|XPath|Strict locator.
          */
-        forceClick(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<void>;
-        /**
-         * 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 [armed] - from `_armActionSettle`, called before the action.
-         */
-        protected _waitForAction(armed?: any | null): Promise<void>;
+        forceClick(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Fills a text field or textarea, after clearing its value, with the given string.
          * Field is located by name, label, CSS, or XPath.
          *
+         * The third parameter is an optional context (CSS or XPath locator) to narrow the search.
+         *
          * ```js
          * // by label
          * I.fillField('Email', 'hello@world.com');
@@ -1993,43 +1724,59 @@ declare namespace CodeceptJS {
          * I.fillField('form#login input[name=username]', 'John');
          * // or by strict locator
          * I.fillField({css: 'form#login input[name=username]'}, 'John');
+         * // by ARIA role locator
+         * I.fillField({role: 'textbox', name: 'Email'}, 'hello@world.com');
+         * // within a context
+         * I.fillField('Name', 'John', '#section2');
          * ```
+         *
+         * > ℹ️ ARIA role locators (`{role, name}`) match fields by their accessible name and survive markup refactors. See [Locators](/locators#aria-locators).
          * @param field - located by label|name|CSS|XPath|strict locator.
          * @param value - text value to fill.
-         * @param [context = null] - (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+         * @param [context = null] - (optional, `null` by default) element located by CSS | XPath | strict locator.
          */
-        fillField(field: CodeceptJS.LocatorOrString, value: CodeceptJS.StringOrSecret, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        fillField(field: CodeceptJS.LocatorOrString, value: CodeceptJS.StringOrSecret, context?: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Appends text to a input field or textarea.
          * Field is located by name, label, CSS or XPath
          *
+         * The third parameter is an optional context (CSS or XPath locator) to narrow the search.
+         *
          * ```js
          * I.appendField('#myTextField', 'appended');
          * // typing secret
          * I.appendField('password', secret('123456'));
+         * // within a context
+         * I.appendField('name', 'John', '.form-container');
          * ```
          * @param field - located by label|name|CSS|XPath|strict locator
          * @param value - text value to append.
-         * @param [context = null] - (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+         * @param [context = null] - (optional, `null` by default) element located by CSS | XPath | strict locator.
          */
-        appendField(field: CodeceptJS.LocatorOrString, value: string, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        appendField(field: CodeceptJS.LocatorOrString, value: string, context?: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Clears a `<textarea>` or text `<input>` element's value.
          *
+         * The second parameter is an optional context (CSS or XPath locator) to narrow the search.
+         *
          * ```js
          * I.clearField('Email');
          * I.clearField('user[email]');
          * I.clearField('#email');
+         * // within a context
+         * I.clearField('Email', '.form-container');
          * ```
-         * @param field - editable field located by label|name|CSS|XPath|strict locator.
-         * @param [context = null] - (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+         * @param editable - field located by label|name|CSS|XPath|strict locator.
+         * @param [context = null] - (optional, `null` by default) element located by CSS | XPath | strict locator.
          */
-        clearField(field: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        clearField(editable: LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * 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.
          *
+         * The third parameter is an optional context (CSS or XPath locator) to narrow the search.
+         *
          * ```js
          * I.selectOption('Choose Plan', 'Monthly'); // select by label
          * I.selectOption('subscription', 'Monthly'); // match option by text
@@ -2037,16 +1784,26 @@ declare namespace CodeceptJS {
          * I.selectOption('//form/select[@name=account]','Premium');
          * I.selectOption('form select[name=account]', 'Premium');
          * I.selectOption({css: 'form select[name=account]'}, 'Premium');
+         * // within a context
+         * I.selectOption('age', '21-60', '#section2');
+         * ```
+         *
+         * Provide an array for the second argument to select multiple options.
+         *
+         * ```js
+         * I.selectOption('Which OS do you use?', ['Android', 'iOS']);
          * ```
          * @param select - field located by label|name|CSS|XPath|strict locator.
-         * @param option - visible text or value of option, or an array of them for a multi-select.
-         * @param [context = null] - (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+         * @param option - visible text or value of option.
+         * @param [context = null] - (optional, `null` by default) element located by CSS | XPath | strict locator.
          */
-        selectOption(select: CodeceptJS.LocatorOrString, option: string | string[], context?: CodeceptJS.LocatorOrString): Promise<void>;
+        selectOption(select: LocatorOrString, option: string | any[], context?: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Selects a checkbox or radio button.
          * Element is located by label or name or CSS or XPath.
          *
+         * The second parameter is an optional context (CSS or XPath locator) to narrow the search.
+         *
          * ```js
          * I.checkOption('#agree');
          * I.checkOption('I Agree to Terms and Conditions');
@@ -2055,11 +1812,13 @@ declare namespace CodeceptJS {
          * @param field - checkbox located by label | name | CSS | XPath | strict locator.
          * @param [context = null] - (optional, `null` by default) element located by CSS | XPath | strict locator.
          */
-        checkOption(field: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        checkOption(field: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Unselects a checkbox or radio button.
          * Element is located by label or name or CSS or XPath.
          *
+         * The second parameter is an optional context (CSS or XPath locator) to narrow the search.
+         *
          * ```js
          * I.uncheckOption('#agree');
          * I.uncheckOption('I Agree to Terms and Conditions');
@@ -2068,31 +1827,34 @@ declare namespace CodeceptJS {
          * @param field - checkbox located by label | name | CSS | XPath | strict locator.
          * @param [context = null] - (optional, `null` by default) element located by CSS | XPath | strict locator.
          */
-        uncheckOption(field: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        uncheckOption(field: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<any>;
         /**
-         * 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`.
+         * Attaches a file to element located by label, name, CSS or XPath
+         * Path to file is relative current codecept directory (where codecept.conf.ts or codecept.conf.js is located).
+         * File will be uploaded to remote system (if tests are running remotely).
+         *
+         * The third parameter is an optional context (CSS or XPath locator) to narrow the search.
          *
          * ```js
          * I.attachFile('Avatar', 'data/avatar.jpg');
-         * I.attachFile('#file', 'data/avatar.jpg');
+         * I.attachFile('form input[name=avatar]', 'data/avatar.jpg');
+         * // within a context
+         * I.attachFile('Avatar', 'data/avatar.jpg', '.form-container');
+         * ```
+         *
+         * If the locator points to a non-file-input element (e.g., a dropzone area),
+         * the file will be dropped onto that element using drag-and-drop events.
+         *
+         * ```js
          * I.attachFile('#dropzone', 'data/avatar.jpg');
          * ```
-         * @param field - located by label|name|CSS|XPath|strict locator.
-         * @param pathToFile - path to file, relative to `codecept_dir`.
-         * @param [context = null] - (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+         * @param locator - field located by label|name|CSS|XPath|strict locator.
+         * @param pathToFile - local file path relative to codecept.conf.ts or codecept.conf.js config file.
+         * @param [context = null] - (optional, `null` by default) element located by CSS | XPath | strict locator.
          */
-        attachFile(field: CodeceptJS.LocatorOrString, pathToFile: string, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        attachFile(locator: CodeceptJS.LocatorOrString, pathToFile: string, context?: CodeceptJS.LocatorOrString): Promise<any>;
         /**
-         * Waits for element to be present on page (by default waits for `options.waitForTimeout` seconds).
+         * Waits for element to be present on page (by default waits for 1sec).
          * Element can be located by CSS or XPath.
          *
          * ```js
@@ -2100,11 +1862,11 @@ declare namespace CodeceptJS {
          * I.waitForElement('.btn.continue', 5); // wait for 5 secs
          * ```
          * @param locator - element located by CSS|XPath|strict locator.
-         * @param [sec = null] - (optional, `options.waitForTimeout` by default) time in seconds to wait
+         * @param [sec = null] - (optional, `1` by default) time in seconds to wait
          */
-        waitForElement(locator: CodeceptJS.LocatorOrString, sec?: number): Promise<void>;
+        waitForElement(locator: CodeceptJS.LocatorOrString, sec?: number): Promise<any>;
         /**
-         * Waits for a text to appear (by default waits for `options.waitForTimeout` seconds).
+         * Waits for a text to appear (by default waits for 1sec).
          * Element can be located by CSS or XPath.
          * Narrow down search results by providing context.
          *
@@ -2113,10 +1875,10 @@ declare namespace CodeceptJS {
          * I.waitForText('Thank you, form has been submitted', 5, '#modal');
          * ```
          * @param text - to wait for.
-         * @param [sec = null] - (optional, `options.waitForTimeout` by default) time in seconds to wait
+         * @param [sec = 1] - (optional, `1` by default) time in seconds to wait
          * @param [context = null] - (optional) element located by CSS|XPath|strict locator.
          */
-        waitForText(text: string, sec?: number, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        waitForText(text: string, sec?: number, context?: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Waiting for the part of the URL to match the expected. Useful for SPA to understand that page was changed.
          *
@@ -2124,23 +1886,27 @@ declare namespace CodeceptJS {
          * I.waitInUrl('/info', 2);
          * ```
          * @param urlPart - value to check.
-         * @param [sec = null] - (optional, `options.waitForTimeout` by default) time in seconds to wait
+         * @param [sec = 1] - (optional, `1` by default) time in seconds to wait
          */
-        waitInUrl(urlPart: string, sec?: number): Promise<void>;
+        waitInUrl(urlPart: string, sec?: number): Promise<any>;
         /**
-         * Waits for a function to return true (waits for `options.waitForTimeout` seconds by default).
+         * Waits for a function to return true (waits for 1 sec by default).
          * Running in browser context.
          *
          * ```js
+         * I.waitForFunction(fn[, [args[, timeout]])
+         * ```
+         *
+         * ```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 fn - to be executed in browser context.
-         * @param [argsOrSec = null] - (optional) arguments for function or, if a number, seconds to wait.
-         * @param [sec = null] - (optional, `options.waitForTimeout` by default) time in seconds to wait
+         * @param [argsOrSec = null] - (optional, `1` by default) arguments for function or seconds.
+         * @param [sec = null] - (optional, `1` by default) time in seconds to wait
          */
-        waitForFunction(fn: string | ((...params: any[]) => any), argsOrSec?: any[] | number, sec?: number): Promise<void>;
+        waitForFunction(fn: string | ((...params: any[]) => any), argsOrSec?: any[] | number, sec?: number): Promise<any>;
         /**
          * Sets cookie(s).
          *
@@ -2157,7 +1923,7 @@ declare namespace CodeceptJS {
          * ```
          * @param cookie - a cookie object or array of cookie objects.
          */
-        setCookie(cookie: CodeceptJS.Cookie | CodeceptJS.Cookie[]): Promise<void>;
+        setCookie(cookie: Cookie | Cookie[]): Promise<any>;
         /**
          * Retrieves all cookies visible to the current page.
          * Resumes test execution, so **should be used inside async function with `await`** operator.
@@ -2178,9 +1944,8 @@ declare namespace CodeceptJS {
          * assert(cookie.value, '123456');
          * ```
          * @param [name = null] - cookie name.
-         * @returns a cookie object, or an array of all cookies when `name` is not provided.
          */
-        grabCookie(name?: string | null): Promise<CodeceptJS.Cookie | CodeceptJS.Cookie[]>;
+        grabCookie(name?: string): Promise<any>;
         /**
          * Clears a cookie by name,
          * if none provided clears all cookies.
@@ -2189,9 +1954,9 @@ declare namespace CodeceptJS {
          * I.clearCookie();
          * I.clearCookie('test');
          * ```
-         * @param [name = null] - (optional, `null` by default) cookie name
+         * @param [cookie = null] - (optional, `null` by default) cookie name
          */
-        clearCookie(name?: string | null): Promise<void>;
+        clearCookie(cookie?: string): Promise<any>;
         /**
          * Checks that the system clipboard contains the given text.
          *
@@ -2200,10 +1965,11 @@ declare namespace CodeceptJS {
          * I.seeInClipboard('https://codecept.io');
          * ```
          *
-         * Reading the clipboard requires a secure context (`https` or `localhost`).
+         * Reading the clipboard requires a secure context (`https` or `localhost`) and is supported
+         * in Chromium-based browsers, where read access is granted automatically.
          * @param text - value to check.
          */
-        seeInClipboard(text: string): Promise<void>;
+        seeInClipboard(text: string): Promise<any>;
         /**
          * Checks that the system clipboard is equal to the given text.
          *
@@ -2212,10 +1978,11 @@ declare namespace CodeceptJS {
          * I.seeClipboardEquals('https://codecept.io');
          * ```
          *
-         * Reading the clipboard requires a secure context (`https` or `localhost`).
+         * Reading the clipboard requires a secure context (`https` or `localhost`) and is supported
+         * in Chromium-based browsers, where read access is granted automatically.
          * @param text - value to check.
          */
-        seeClipboardEquals(text: string): Promise<void>;
+        seeClipboardEquals(text: string): Promise<any>;
         /**
          * Clears the system clipboard.
          *
@@ -2224,24 +1991,21 @@ declare namespace CodeceptJS {
          * I.seeClipboardEquals('');
          * ```
          */
-        clearClipboard(): Promise<void>;
+        clearClipboard(): Promise<any>;
         /**
-         * Grabs the text content of the system clipboard.
+         * Grabs the text content of the system clipboard and returns it to test.
          * Resumes test execution, so **should be used inside async function with `await`** operator.
          *
          * ```js
          * I.click('Copy to clipboard');
-         * const url = await I.grabFromClipboard();
+         * let url = await I.grabFromClipboard();
          * ```
+         *
+         * Reading the clipboard requires a secure context (`https` or `localhost`) and is supported
+         * in Chromium-based browsers, where read access is granted automatically.
          * @returns the system clipboard contents.
          */
         grabFromClipboard(): Promise<string>;
-        /**
-         * Brings the current target to front and grants it clipboard read/write access, so
-         * `navigator.clipboard` does not reject with a permission or focus error. Failures are ignored:
-         * a browser without `Browser.grantPermissions` surfaces its own error from the read instead.
-         */
-        protected _grantClipboardAccess(): Promise<any>;
         /**
          * Saves a screenshot to the output folder (set in codecept.conf.ts or codecept.conf.js).
          * Filename is relative to the output folder.
@@ -2251,168 +2015,203 @@ declare namespace CodeceptJS {
          * ```
          * @param fileName - file name to save.
          */
-        saveScreenshot(fileName: string): Promise<void>;
+        saveScreenshot(fileName: string): Promise<any>;
         /**
-         * Saves a screenshot of a single element to the output folder.
+         * Saves screenshot of the specified locator to ouput folder (set in codecept.conf.ts or codecept.conf.js).
+         * Filename is relative to output folder.
          *
          * ```js
-         * I.saveElementScreenshot('#logo', 'logo.png');
+         * I.saveElementScreenshot(`#submit`,'debug.png');
          * ```
          * @param locator - element located by CSS|XPath|strict locator.
          * @param fileName - file name to save.
          */
-        saveElementScreenshot(locator: CodeceptJS.LocatorOrString, fileName: string): Promise<void>;
+        saveElementScreenshot(locator: CodeceptJS.LocatorOrString, fileName: string): Promise<any>;
         /**
          * Pauses execution for a number of seconds.
          *
          * ```js
-         * I.wait(2); // waits 2 secs
+         * I.wait(2); // wait 2 secs
          * ```
-         * @param sec - number of seconds to wait.
+         * @param sec - number of second to wait.
          */
-        wait(sec: number): Promise<void>;
+        wait(sec: number): Promise<any>;
         /**
          * Checks that title does not contain text.
+         *
+         * ```js
+         * I.dontSeeInTitle('Error');
+         * ```
          * @param text - value to check.
          */
-        dontSeeInTitle(text: string): Promise<void>;
+        dontSeeInTitle(text: string): Promise<any>;
         /**
          * Checks that current url is equal to provided one.
-         * Unlike `seeInCurrentUrl` performs a strict comparison.
+         * If a relative url provided, a configured url will be prepended to it.
+         * So both examples will work:
          *
          * ```js
          * I.seeCurrentUrlEquals('/register');
+         * I.seeCurrentUrlEquals('http://my.site.com/register');
          * ```
          * @param url - value to check.
          */
-        seeCurrentUrlEquals(url: string): Promise<void>;
+        seeCurrentUrlEquals(url: string): Promise<any>;
         /**
          * Checks that current url is not equal to provided one.
-         * Unlike `dontSeeInCurrentUrl` performs a strict comparison.
+         * If a relative url provided, a configured url will be prepended to it.
+         *
+         * ```js
+         * I.dontSeeCurrentUrlEquals('/login'); // relative url are ok
+         * I.dontSeeCurrentUrlEquals('http://mysite.com/login'); // absolute urls are also ok
+         * ```
          * @param url - value to check.
          */
-        dontSeeCurrentUrlEquals(url: string): Promise<void>;
-        /**
-         * Resolves the current page URL to a `pathname`, ignoring the origin, query string, and hash.
-         * @returns the pathname of the current page.
-         */
-        protected _grabCurrentPath(): Promise<string>;
+        dontSeeCurrentUrlEquals(url: string): Promise<any>;
         /**
-         * Checks that current url path (ignoring query string and hash) equals to provided one.
+         * Checks that current URL path matches the expected path.
+         * Query strings and URL fragments are ignored.
          *
          * ```js
-         * I.seeCurrentPathEquals('/info');
+         * I.seeCurrentPathEquals('/info'); // passes for '/info', '/info?user=1', '/info#section'
+         * I.seeCurrentPathEquals('/'); // passes for '/', '/?user=ok', '/#top'
          * ```
          * @param path - value to check.
          */
-        seeCurrentPathEquals(path: string): Promise<void>;
+        seeCurrentPathEquals(path: string): Promise<any>;
         /**
-         * Opposite to `seeCurrentPathEquals`.
+         * Checks that current URL path does NOT match the expected path.
+         * Query strings and URL fragments are ignored.
+         *
+         * ```js
+         * I.dontSeeCurrentPathEquals('/form'); // fails for '/form', '/form?user=1', '/form#section'
+         * I.dontSeeCurrentPathEquals('/'); // fails for '/', '/?user=ok', '/#top'
+         * ```
          * @param path - value to check.
          */
-        dontSeeCurrentPathEquals(path: string): Promise<void>;
+        dontSeeCurrentPathEquals(path: string): Promise<any>;
         /**
-         * Waits for the entire URL to match the expected (by default waits for `options.waitForTimeout` seconds).
+         * Waits for the entire URL to match the expected
          *
          * ```js
          * I.waitUrlEquals('/info', 2);
+         * I.waitUrlEquals('http://127.0.0.1:8000/info');
          * ```
          * @param urlPart - value to check.
-         * @param [sec = null] - (optional, `options.waitForTimeout` by default) time in seconds to wait
+         * @param [sec = 1] - (optional, `1` by default) time in seconds to wait
          */
-        waitUrlEquals(urlPart: string, sec?: number): Promise<void>;
+        waitUrlEquals(urlPart: string, sec?: number): Promise<any>;
         /**
-         * 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 path - value to check.
-         * @param [sec = null] - (optional, `options.waitForTimeout` by default) time in seconds to wait
+         * @param [sec = null] - (optional, `waitForTimeout` by default) time in seconds to wait
          */
-        waitCurrentPathEquals(path: string, sec?: number): Promise<void>;
+        waitCurrentPathEquals(path: string, sec?: number): Promise<any>;
         /**
-         * 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.
+         * Checks that the given input field or textarea equals to given value.
+         * For fuzzy locators, fields are matched by label text, the "name" attribute, CSS, and XPath.
+         *
+         * The third parameter is an optional context (CSS or XPath locator) to narrow the search.
          *
          * ```js
          * I.seeInField('Username', 'davert');
+         * I.seeInField({css: 'form textarea'},'Type your comment here');
+         * I.seeInField('form input[type=hidden]','hidden_value');
+         * I.seeInField('#searchform input','Search');
+         * // within a context
+         * I.seeInField('Name', 'John', '.form-container');
          * ```
          * @param field - located by label|name|CSS|XPath|strict locator.
          * @param value - value to check.
-         * @param [context = null] - (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+         * @param [context = null] - (optional, `null` by default) element located by CSS | XPath | strict locator.
          */
-        seeInField(field: CodeceptJS.LocatorOrString, value: CodeceptJS.StringOrSecret, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        seeInField(field: CodeceptJS.LocatorOrString, value: CodeceptJS.StringOrSecret, context?: CodeceptJS.LocatorOrString): Promise<any>;
         /**
+         * Checks that value of input field or textarea doesn't equal to given value
          * Opposite to `seeInField`.
+         *
+         * The third parameter is an optional context (CSS or XPath locator) to narrow the search.
+         *
+         * ```js
+         * I.dontSeeInField('email', 'user@user.com'); // field by name
+         * I.dontSeeInField({ css: 'form input.email' }, 'user@user.com'); // field by CSS
+         * // within a context
+         * I.dontSeeInField('Name', 'old_value', '.form-container');
+         * ```
          * @param field - located by label|name|CSS|XPath|strict locator.
          * @param value - value to check.
-         * @param [context = null] - (optional, `null` by default) element to search in CSS|XPath|Strict locator.
-         */
-        dontSeeInField(field: CodeceptJS.LocatorOrString, value: CodeceptJS.StringOrSecret, context?: CodeceptJS.LocatorOrString): Promise<void>;
-        /**
-         * Shared implementation for `seeInField`/`dontSeeInField`.
+         * @param [context = null] - (optional, `null` by default) element located by CSS | XPath | strict locator.
          */
-        protected _seeInField(assertType: 'assert' | 'negate', field: CodeceptJS.LocatorOrString, value: CodeceptJS.StringOrSecret, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        dontSeeInField(field: CodeceptJS.LocatorOrString, value: CodeceptJS.StringOrSecret, context?: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Grab number of visible elements by locator.
+         * Resumes test execution, so **should be used inside async function with `await`** operator.
          *
          * ```js
-         * let numOfVisibleElements = await I.grabNumberOfVisibleElements('p');
+         * let numOfElements = await I.grabNumberOfVisibleElements('p');
          * ```
          * @param locator - located by CSS|XPath|strict locator.
-         * @returns number of visible matched elements.
+         * @returns number of visible elements
          */
         grabNumberOfVisibleElements(locator: CodeceptJS.LocatorOrString): Promise<number>;
         /**
-         * Asserts that an element appears a given number of times on the page, and that all matching elements are visible.
+         * Asserts that an element is visible a given number of times.
+         * Element is located by CSS or XPath.
          *
          * ```js
          * I.seeNumberOfVisibleElements('.buttons', 3);
          * ```
-         * @param locator - located by CSS|XPath|strict locator.
-         * @param num - expected number of elements.
+         * @param locator - element located by CSS|XPath|strict locator.
+         * @param num - number of elements.
          */
-        seeNumberOfVisibleElements(locator: CodeceptJS.LocatorOrString, num: number): Promise<void>;
+        seeNumberOfVisibleElements(locator: CodeceptJS.LocatorOrString, num: number): Promise<any>;
         /**
-         * Retrieves the current page scroll position.
+         * Retrieves a page scroll position and returns it to test.
+         * Resumes test execution, so **should be used inside an async function with `await`** operator.
          *
          * ```js
          * let { x, y } = await I.grabPageScrollPosition();
          * ```
-         * @returns scroll position.
+         * @returns scroll position
          */
-        grabPageScrollPosition(): Promise<{ x: number; y: number; }>;
+        grabPageScrollPosition(): Promise<PageScrollPosition>;
         /**
-         * Scrolls to the top of the page.
+         * Scroll page to the top.
          *
          * ```js
          * I.scrollPageToTop();
          * ```
          */
-        scrollPageToTop(): Promise<void>;
+        scrollPageToTop(): Promise<any>;
         /**
-         * Scrolls to the bottom of the page.
+         * Scroll page to the bottom.
          *
          * ```js
          * I.scrollPageToBottom();
          * ```
          */
-        scrollPageToBottom(): Promise<void>;
+        scrollPageToBottom(): Promise<any>;
         /**
-         * Scrolls to the element matched by locator, or to given coordinates.
+         * Scrolls to element matched by locator.
+         * Extra shift can be set with offsetX and offsetY options.
          *
          * ```js
-         * I.scrollTo('#submit');
-         * I.scrollTo(100, 200);
+         * I.scrollTo('footer');
+         * I.scrollTo('#submit', 5, 5);
          * ```
-         * @param locator - element to scroll to, or an X coordinate if no element.
-         * @param [offsetX = 0] - X offset, or Y coordinate if `locator` is a number.
-         * @param [offsetY = 0] - Y offset applied when scrolling to an element.
+         * @param locator - located by CSS|XPath|strict locator.
+         * @param [offsetX = 0] - (optional, `0` by default) X-axis offset.
+         * @param [offsetY = 0] - (optional, `0` by default) Y-axis offset.
          */
-        scrollTo(locator: CodeceptJS.LocatorOrString | number, offsetX?: number, offsetY?: number): Promise<void>;
+        scrollTo(locator: CodeceptJS.LocatorOrString, offsetX?: number, offsetY?: number): Promise<any>;
         /**
-         * Retrieves a CSS property from an element located by CSS or XPath.
+         * Grab CSS property for given locator
+         * Resumes test execution, so **should be used inside an async function with `await`** operator.
          * If more than one element is found - value of first element is returned.
          *
          * ```js
@@ -2424,79 +2223,94 @@ declare namespace CodeceptJS {
          */
         grabCssPropertyFrom(locator: CodeceptJS.LocatorOrString, cssProperty: string): Promise<string>;
         /**
-         * Retrieves an array of CSS properties from elements located by CSS or XPath.
+         * Grab array of CSS properties for given locator
+         * Resumes test execution, so **should be used inside an async function with `await`** operator.
          *
          * ```js
          * const values = await I.grabCssPropertyFromAll('h3', 'font-weight');
          * ```
          * @param locator - element located by CSS|XPath|strict locator.
          * @param cssProperty - CSS property name.
-         * @returns array of CSS values
+         * @returns CSS value
          */
         grabCssPropertyFromAll(locator: CodeceptJS.LocatorOrString, cssProperty: string): Promise<string[]>;
         /**
-         * Checks that all elements matched by locator have the given CSS properties.
+         * Checks that all elements with given locator have given CSS properties.
          *
          * ```js
-         * I.seeCssPropertiesOnElements('h3', { 'font-weight': 'bold', display: 'block' });
+         * I.seeCssPropertiesOnElements('h3', { 'font-weight': "bold"});
          * ```
-         * @param locator - element located by CSS|XPath|strict locator.
+         * @param locator - located by CSS|XPath|strict locator.
          * @param cssProperties - object with CSS properties and their values to check.
          */
-        seeCssPropertiesOnElements(locator: CodeceptJS.LocatorOrString, cssProperties: any): Promise<void>;
+        seeCssPropertiesOnElements(locator: CodeceptJS.LocatorOrString, cssProperties: any): Promise<any>;
         /**
-         * 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.
+         * Checks that all elements with given locator have given attributes.
          *
          * ```js
-         * I.seeAttributesOnElements('//form', { method: 'post' });
+         * I.seeAttributesOnElements('//form', { method: "post"});
          * ```
-         * @param locator - element located by CSS|XPath|strict locator.
-         * @param attributes - object with attribute names and expected values.
+         * @param locator - located by CSS|XPath|strict locator.
+         * @param attributes - attributes and their values to check.
          */
-        seeAttributesOnElements(locator: CodeceptJS.LocatorOrString, attributes: any): Promise<void>;
+        seeAttributesOnElements(locator: CodeceptJS.LocatorOrString, attributes: any): Promise<any>;
         /**
-         * Focuses a given element.
+         * Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the matching element.
+         *
+         * Examples:
          *
          * ```js
-         * I.focus('#name');
+         * I.dontSee('#add-to-cart-btn');
+         * I.focus('#product-tile')
+         * I.see('#add-to-cart-bnt');
          * ```
-         * @param locator - element located by CSS|XPath|strict locator.
+         * @param locator - field located by label|name|CSS|XPath|strict locator.
+         * @param [options] - Playwright only: [Additional options](https://playwright.dev/docs/api/class-locator#locator-focus) for available options object as 2nd argument.
          */
-        focus(locator: CodeceptJS.LocatorOrString): Promise<void>;
+        focus(locator: CodeceptJS.LocatorOrString, options?: any): Promise<any>;
         /**
-         * Removes focus from a given element.
+         * Remove focus from a text input, button, etc.
+         * Calls [blur](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
+         *
+         * Examples:
          *
          * ```js
-         * I.blur('#name');
+         * I.blur('.text-area')
          * ```
-         * @param locator - element located by CSS|XPath|strict locator.
+         * ```js
+         * //element `#product-tile` is focused
+         * I.see('#add-to-cart-btn');
+         * I.blur('#product-tile')
+         * I.dontSee('#add-to-cart-btn');
+         * ```
+         * @param locator - field located by label|name|CSS|XPath|strict locator.
+         * @param [options] - Playwright only: [Additional options](https://playwright.dev/docs/api/class-locator#locator-blur) for available options object as 2nd argument.
          */
-        blur(locator: CodeceptJS.LocatorOrString): Promise<void>;
+        blur(locator: CodeceptJS.LocatorOrString, options?: any): Promise<any>;
         /**
-         * 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.
+         * Types out the given text into an active field.
+         * To slow down typing use a second parameter, to set interval between key presses.
+         * _Note:_ Should be used when [`fillField`](#fillfield) is not an option.
          *
          * ```js
-         * I.click('Name');
-         * I.type('CodeceptJS');
-         * I.type(['C', 'o', 'd', 'e']);
+         * // passing in a string
+         * I.type('Type this out.');
+         *
+         * // typing values with a 100ms interval
+         * I.type('4141555311111111', 100);
+         *
+         * // passing in an array
+         * I.type(['T', 'E', 'X', 'T']);
+         *
+         * // passing a secret
+         * I.type(secret('123456'));
          * ```
-         * @param keys - characters to type, either as a string or an array of characters.
-         * @param [delay = null] - (optional) delay in milliseconds between key presses.
+         * @param key - or array of keys to type.
+         * @param [delay = null] - (optional) delay in ms between key presses
          */
-        type(keys: string | string[], delay?: number): Promise<void>;
+        type(key: string | string[], delay?: number): Promise<any>;
         /**
-         * 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');
@@ -2504,171 +2318,186 @@ declare namespace CodeceptJS {
          * ```
          * @param key - a key or an array of keys to combine (modifiers first).
          */
-        pressKey(key: string | string[]): Promise<void>;
+        pressKey(key: string | string[]): Promise<any>;
         /**
-         * Resizes the browser viewport.
-         *
-         * ```js
-         * I.resizeWindow(1024, 768);
-         * ```
-         * @param width - window width, or `'maximize'`.
-         * @param [height] - window height.
+         * Resize the current window to provided width and height.
+         * First parameter can be set to `maximize`.
+         * @param width - width in pixels or `maximize`.
+         * @param height - height in pixels.
          */
-        resizeWindow(width: number | 'maximize', height?: number): Promise<void>;
+        resizeWindow(width: number, height: number): Promise<any>;
         /**
-         * Performs a double-click on an element matched by locator.
+         * Performs a double-click on an element matched by link|button|label|CSS or XPath.
+         * Context can be specified as second parameter to narrow search.
          *
          * ```js
          * I.doubleClick('Edit');
+         * I.doubleClick('Edit', '.actions');
+         * I.doubleClick({css: 'button.accept'});
+         * I.doubleClick('.btn.edit');
          * ```
-         * @param locator - clickable element located by text, or any element located by CSS|XPath|strict locator.
-         * @param [context = null] - (optional, `null` by default, currently ignored by this helper).
+         * @param locator - clickable link or button located by text, or any element located by CSS|XPath|strict locator.
+         * @param [context = null] - (optional, `null` by default) element to search in CSS|XPath|Strict locator.
          */
-        doubleClick(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        doubleClick(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<any>;
         /**
-         * Performs a right-click on an element matched by locator.
+         * Performs right click on a clickable element matched by semantic locator, CSS or XPath.
          *
          * ```js
-         * I.rightClick('Menu');
+         * // right click element with id el
+         * I.rightClick('#el');
+         * // right click link or button with text "Click me"
+         * I.rightClick('Click me');
+         * // right click button with text "Click me" inside .context
+         * I.rightClick('Click me', '.context');
          * ```
-         * @param locator - clickable element located by text, or any element located by CSS|XPath|strict locator.
-         * @param [context = null] - (optional, `null` by default, currently ignored by this helper).
+         * @param locator - clickable element located by CSS|XPath|strict locator.
+         * @param [context = null] - (optional, `null` by default) element located by CSS|XPath|strict locator.
          */
-        rightClick(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        rightClick(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<any>;
         /**
-         * 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 locator - element to click relative to, or a global X coordinate.
-         * @param [x] - X coordinate relative to element, or global Y coordinate if `locator` is a number.
-         * @param [y] - Y coordinate relative to element.
+         * @param locator - element to click relative to, or the X page coordinate.
+         * @param [x] - X coordinate relative to the element, or the Y page coordinate if `locator` is a number.
+         * @param [y] - Y coordinate relative to the element.
          */
-        clickXY(locator: CodeceptJS.LocatorOrString | number, x?: number, y?: number): Promise<void>;
+        clickXY(locator: CodeceptJS.LocatorOrString | number, x?: number, y?: number): Promise<any>;
         /**
-         * Waits for an element to become visible (by default waits for `options.waitForTimeout` seconds).
+         * Waits for an element to become visible on a page (by default waits for 1sec).
+         * Element can be located by CSS or XPath.
          *
          * ```js
-         * I.waitForVisible('#popup', 5);
+         * I.waitForVisible('#popup');
          * ```
          * @param locator - element located by CSS|XPath|strict locator.
-         * @param [sec = null] - (optional, `options.waitForTimeout` by default) time in seconds to wait
+         * @param [sec = 1] - (optional, `1` by default) time in seconds to wait
          */
-        waitForVisible(locator: CodeceptJS.LocatorOrString, sec?: number): Promise<void>;
+        waitForVisible(locator: CodeceptJS.LocatorOrString, sec?: number): Promise<any>;
         /**
-         * Waits for an element to become invisible (by default waits for `options.waitForTimeout` seconds).
+         * Waits for an element to be removed or become invisible on a page (by default waits for 1sec).
+         * Element can be located by CSS or XPath.
          *
          * ```js
-         * I.waitForInvisible('#popup', 5);
+         * I.waitForInvisible('#popup');
          * ```
          * @param locator - element located by CSS|XPath|strict locator.
-         * @param [sec = null] - (optional, `options.waitForTimeout` by default) time in seconds to wait
+         * @param [sec = 1] - (optional, `1` by default) time in seconds to wait
          */
-        waitForInvisible(locator: CodeceptJS.LocatorOrString, sec?: number): Promise<void>;
+        waitForInvisible(locator: CodeceptJS.LocatorOrString, sec?: number): Promise<any>;
         /**
-         * Waits for an element to be hidden. Alias of `waitForInvisible`.
+         * Waits for an element to hide (by default waits for 1sec).
+         * Element can be located by CSS or XPath.
+         *
+         * ```js
+         * I.waitToHide('#popup');
+         * ```
          * @param locator - element located by CSS|XPath|strict locator.
-         * @param [sec = null] - (optional, `options.waitForTimeout` by default) time in seconds to wait
+         * @param [sec = 1] - (optional, `1` by default) time in seconds to wait
          */
-        waitToHide(locator: CodeceptJS.LocatorOrString, sec?: number): Promise<void>;
+        waitToHide(locator: CodeceptJS.LocatorOrString, sec?: number): Promise<any>;
         /**
-         * Waits for an element to be removed from the DOM (by default waits for `options.waitForTimeout` seconds).
+         * Waits for an element to become not attached to the DOM on a page (by default waits for 1sec).
+         * Element can be located by CSS or XPath.
          *
          * ```js
-         * I.waitForDetached('#popup', 5);
+         * I.waitForDetached('#popup');
          * ```
          * @param locator - element located by CSS|XPath|strict locator.
-         * @param [sec = null] - (optional, `options.waitForTimeout` by default) time in seconds to wait
+         * @param [sec = 1] - (optional, `1` by default) time in seconds to wait
          */
-        waitForDetached(locator: CodeceptJS.LocatorOrString, sec?: number): Promise<void>;
+        waitForDetached(locator: CodeceptJS.LocatorOrString, sec?: number): Promise<any>;
         /**
-         * Checks that a cookie with the given name is set.
+         * Checks that cookie with given name exists.
+         *
+         * ```js
+         * I.seeCookie('Auth');
+         * ```
          * @param name - cookie name.
          */
-        seeCookie(name: string): Promise<void>;
+        seeCookie(name: string): Promise<any>;
         /**
-         * Checks that a cookie with the given name is not set.
+         * Checks that cookie with given name does not exist.
+         *
+         * ```js
+         * I.dontSeeCookie('auth'); // no auth cookie
+         * ```
          * @param name - cookie name.
          */
-        dontSeeCookie(name: string): Promise<void>;
+        dontSeeCookie(name: string): Promise<any>;
         /**
-         * Waits for a cookie with the given name to be set (by default waits for `options.waitForTimeout` seconds).
+         * Waits for the specified cookie in the cookies.
          *
          * ```js
-         * I.waitForCookie('auth', 5);
+         * I.waitForCookie("token");
          * ```
-         * @param name - cookie name.
-         * @param [sec = null] - (optional, `options.waitForTimeout` by default) time in seconds to wait
+         * @param name - expected cookie name.
+         * @param [sec = 3] - (optional, `3` by default) time in seconds to wait
          */
-        waitForCookie(name: string, sec?: number): Promise<void>;
+        waitForCookie(name: string, sec?: number): Promise<any>;
         /**
-         * Retrieves the inner HTML from an element located by CSS or XPath.
+         * Retrieves the innerHTML from an 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 - HTML of first element is returned.
          *
          * ```js
          * let postHTML = await I.grabHTMLFrom('#post');
          * ```
-         * @param locator - element located by CSS|XPath|strict locator.
+         * @param element - located by CSS|XPath|strict locator.
          * @returns HTML code for an element
          */
-        grabHTMLFrom(locator: CodeceptJS.LocatorOrString): Promise<string>;
+        grabHTMLFrom(element: CodeceptJS.LocatorOrString): Promise<string>;
         /**
-         * Retrieves the inner HTML from elements located by CSS or XPath.
+         * Retrieves all the innerHTML from elements 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 postHTMLs = await I.grabHTMLFromAll('.post');
          * ```
-         * @param locator - element located by CSS|XPath|strict locator.
-         * @returns HTML code for matched elements
+         * @param element - located by CSS|XPath|strict locator.
+         * @returns HTML code for an element
          */
-        grabHTMLFromAll(locator: CodeceptJS.LocatorOrString): Promise<string[]>;
+        grabHTMLFromAll(element: CodeceptJS.LocatorOrString): Promise<string[]>;
         /**
-         * Executes an asynchronous script (callback-style, in the same way `window.setTimeout` works)
-         * in the browser context and returns the value passed to `done`.
+         * Executes async script on page.
+         * Provided function should execute a passed callback (as first argument) to signal it is finished.
+         *
+         * Example: In Vue.js to make components completely rendered we are waiting for [nextTick](https://vuejs.org/v2/api/#Vue-nextTick).
+         *
+         * ```js
+         * I.executeAsyncScript(function(done) {
+         *   Vue.nextTick(done); // waiting for next tick
+         * });
+         * ```
+         *
+         * By passing value to `done()` function you can return values.
+         * Additional arguments can be passed as well, while `done` function is always last parameter in arguments list.
          *
          * ```js
-         * const val = await I.executeAsyncScript(function(val, done) {
-         *   setTimeout(() => done(val + 1), 100)
-         * }, 5)
+         * let val = await I.executeAsyncScript(function(url, done) {
+         *   // in browser context
+         *   $.ajax(url, { success: (data) => done(data); }
+         * }, 'http://ajax.callback.url/');
          * ```
-         * @param fn - an asynchronous function to be executed in the browser context; its last argument is a `done` callback.
-         * @param args - arguments to pass into the function (before `done`).
-         * @returns the value passed to `done`.
+         * @param fn - function to be executed in browser context.
+         * @param args - to be passed to function.
+         * @returns script return value
          */
-        executeAsyncScript(fn: (...params: any[]) => any, ...args: any[]): Promise<any>;
+        executeAsyncScript(fn: string | ((...params: any[]) => any), ...args: any[]): Promise<any>;
         /**
-         * 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.
+         * Starts recording the network traffics.
+         * This also resets recorded network requests.
          *
          * ```js
          * I.startRecordingTraffic();
          * ```
          */
-        startRecordingTraffic(): Promise<void>;
-        /**
-         * `Network.requestWillBeSent` handler, pushed into `this.requests` when it belongs to the
-         * currently active session and recording is on.
-         */
-        protected _onTrafficRequest(): Promise<any>;
-        /**
-         * `Network.responseReceived` handler, resolving the matching pending `response` promise pushed
-         * by `_onTrafficRequest` with a Puppeteer-`HTTPResponse`-like object.
-         */
-        protected _onTrafficResponse(): Promise<any>;
-        /**
-         * `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(): Promise<any>;
+        startRecordingTraffic(): Promise<any>;
         /**
          * Grab the recording network traffics
          *
@@ -2741,8 +2570,7 @@ declare namespace CodeceptJS {
             url: string | RegExp;
         }): Promise<any>;
         /**
-         * Stops recording network traffic started by `startRecordingTraffic`. Already-recorded requests
-         * in `this.requests` are kept; only new requests stop being appended.
+         * Stops recording of network traffic. Recorded traffic is not flashed.
          *
          * ```js
          * I.stopRecordingTraffic();
@@ -2758,46 +2586,134 @@ declare namespace CodeceptJS {
          */
         flushNetworkTraffics(): Promise<any>;
         /**
-         * 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 [options] - {maxWidth: number, maxHeight: number, quality: number, everyNthFrame: number} — CDP `Page.startScreencast` pass-throughs. `format` is always `'png'`.
+         * @param [options] - `{ maxWidth, maxHeight, quality, everyNthFrame }`
+         */
+        startScreencast(options?: any): Promise<any>;
+        /**
+         * Stops the recording started by `startScreencast` and returns it as an animated PNG.
+         *
+         * ```js
+         * const video = await I.stopScreencast();
+         * ```
+         * @param [options] - `{ lastFrameDelayMs }`: how long the last frame is shown, in milliseconds (1000 by default).
+         * @returns APNG data, or `null` if no frames were recorded.
          */
-        startScreencast(options?: any): Promise<void>;
+        stopScreencast(options?: any): Promise<Buffer | null>;
+    }
+    /**
+     * Asserts statements about the current page with a decision model.
+     *
+     * Decision models (like [Jev](https://openrouter.ai/typesafe/jev-1.13) or [Clef](https://openrouter.ai/cloudflare/clef))
+     * do not generate text. They read the page state and return the probability that a statement is true.
+     * A statement passes when its probability reaches the configured `confidence`.
+     *
+     * ```js
+     * I.decide('top level navigation is available');
+     * I.decide([
+     *   'checkout form has all required fields',
+     *   'success message is shown',
+     *   'submit button enabled',
+     *   'cancel button present',
+     * ]);
+     * I.decideVisually('sidebar is shown');
+     * ```
+     *
+     * The model receives the page URL, title and ARIA snapshot.
+     * Helpers without ARIA snapshots (anything but Playwright) send minified HTML instead.
+     * `decideVisually` also sends a screenshot, so it requires a model with image input.
+     *
+     * This helper must be enabled together with a web helper (Playwright, Puppeteer, WebDriver).
+     *
+     * ## Configuration
+     *
+     * Decision model is created with the OpenRouter provider from `@openrouter/ai-sdk-provider`
+     * and configured in the `ai.decisionModel` section of the config:
+     *
+     * ```js
+     * import { createOpenRouter } from '@openrouter/ai-sdk-provider'
+     *
+     * const openrouter = createOpenRouter({
+     *   apiKey: process.env.OPENROUTER_API_KEY,
+     * })
+     *
+     * export default {
+     *   ai: {
+     *     decisionModel: {
+     *       model: openrouter.evaluationModel('typesafe/jev-1.13'),
+     *       confidence: 0.8,
+     *     },
+     *   },
+     *   helpers: {
+     *     Playwright: { url: 'http://localhost' },
+     *     Decision: {},
+     *   },
+     * }
+     * ```
+     *
+     * * `model` - decision model used by `decide`.
+     * * `confidence` (default: `0.7`) - minimal probability, between 0 and 1, for a statement to pass.
+     * * `timeout` (default: `15000`) - request timeout in ms.
+     * * `maxLength` (default: `12000`) - maximal length of ARIA snapshot or HTML sent to the model.
+     *
+     * `decideVisually` uses a separate decision model with image input, configured as `visualModel`:
+     *
+     * ```js
+     * decisionModel: {
+     *   model: openrouter.evaluationModel('typesafe/jev-1.13'),
+     *   visualModel: openrouter.evaluationModel('cloudflare/clef'),
+     * },
+     * ```
+     *
+     * The helper has one option:
+     *
+     * * `mode` (default: `assert`) - how decisions are executed:
+     *   * `assert` - request the model and fail the step when a statement is not confirmed.
+     *   * `report` - request the model but never fail, even on API errors. Results and errors are added to the step as a comment.
+     *   * `skip` - do not request the model, every decision passes.
+     *
+     * ```js
+     * Decision: { mode: process.env.CI ? 'assert' : 'skip' }
+     * ```
+     *
+     * Decisions work without the `--ai` flag.
+     * Browse all decision models at [OpenRouter](https://openrouter.ai/models?output_modalities=decisions).
+     *
+     * ## Methods
+     */
+    class DecisionTs {
         /**
-         * `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.
+         * Asserts that a statement (or each of statements) is true for the current page.
+         * The decision model receives page URL, title and ARIA snapshot.
+         * Multiple statements are checked in a single request and all of them must pass.
+         *
+         * ```js
+         * I.decide('user is logged in');
+         * I.decide(['submit button enabled', 'cancel button present']);
+         * const probability = await I.decide('cart is empty');
+         * ```
+         * @param statements - statement or list of statements to verify.
+         * @returns probability of each statement, `undefined` in `skip` mode.
          */
-        protected _onScreencastFrame(): Promise<any>;
+        decide(statements: string | string[]): Promise<number | number[] | undefined>;
         /**
-         * 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).
+         * Asserts that a statement (or each of statements) is true for the current page using a screenshot.
+         * The decision model receives page URL, title, ARIA snapshot and a screenshot.
+         * Requires `visualModel` with image input. Experimental.
          *
          * ```js
-         * const apngBuffer = await I.stopScreencast();
+         * I.decideVisually('sidebar is shown');
+         * I.decideVisually(['logo is in the header', 'page uses dark theme']);
          * ```
-         * @param [options] - {lastFrameDelayMs: number} — hold time in milliseconds for the final frame (default 1000).
-         * @returns a Buffer with the assembled APNG, or null if there was nothing to assemble.
+         * @param statements - statement or list of statements to verify.
+         * @returns probability of each statement, `undefined` in `skip` mode.
          */
-        stopScreencast(options?: any): Promise<object>;
+        decideVisually(statements: string | string[]): Promise<number | number[] | undefined>;
     }
     /**
      * Helper for testing filesystem.
@@ -3374,15 +3290,14 @@ declare namespace CodeceptJS {
     /**
      * ## Configuration
      *
-     * This helper should be configured in codecept.conf.js. It accepts everything `CDPBrowser`
-     * accepts (see its config table), plus:
+     * This helper should be configured in codecept.conf.js
      * @property [url = http://localhost] - base URL for tests
      * @property [accountId] - Cloudflare account ID; defaults to CF_ACCOUNT_ID env var
      * @property [apiToken] - Cloudflare API token; defaults to CF_API_TOKEN env var
      * @property [keepAlive = 240000] - session keep-alive time in milliseconds
      * @property [apiBase = https://api.cloudflare.com/client/v4] - Cloudflare API base URL
-     * @property [input = cdp] - input method for user actions; defaults to 'cdp' for Kitesurf's real layout engine, but can be overridden
-     * @property [capabilities] - pre-configured capabilities; Kitesurf uses { layout: 'real', screenshot: true }
+     * @property [input = cdp] - how actions are dispatched: `cdp` (real mouse and keyboard events) or `synthetic` (DOM events).
+     * @property [capabilities] - browser capabilities; Kitesurf sets `{ layout: 'real', screenshot: true }`.
      */
     type KitesurfConfig = {
         url?: string;
@@ -3449,55 +3364,146 @@ declare namespace CodeceptJS {
      */
     class KitesurfTs {
         constructor(config: KitesurfConfig);
-        /**
-         * Acquires a Kitesurf browser session from the Cloudflare Browser Run API and resolves it to
-         * the `wss://` debugger URL `CDPConnection` connects to. Overrides `CDPBrowser._resolveEndpoint`,
-         * which resolves a fixed local endpoint instead of provisioning a cloud session per test.
-         * @returns a `wss://` debugger URL ready to be passed to `CDPConnection`.
-         */
-        protected _resolveEndpoint(): Promise<string>;
-        /**
-         * Closes the target as `CDPBrowser._finishTest` does, then releases the cloud session acquired
-         * in `_resolveEndpoint` via the Cloudflare API so it does not linger for the full `keepAlive`
-         * window. The release runs in a `finally` so a rejection while closing the CDP connection still
-         * frees the cloud session instead of leaving the browser alive until `keepAlive` expires; the
-         * session id is cleared before the request, so a repeated call never releases it twice.
-         */
-        protected _finishTest(): Promise<any>;
     }
     /**
      * ## Configuration
      *
-     * This helper should be configured in codecept.conf.js. It accepts everything `CDPBrowser`
-     * accepts (see its config table), plus:
+     * This helper should be configured in codecept.conf.js
      * @property [endpoint] - explicit CDP endpoint. Setting this switches the helper to ATTACH
      * mode: it only connects, and never spawns or kills a process, no matter what else is configured.
      * Leave it unset for SELF-MANAGED mode (see below).
-     * @property [binaryPath] - path to the `obscura` executable, used in SELF-MANAGED mode
-     * (`endpoint` unset). Checked before `OBSCURA_PATH` and `PATH`.
-     * @property [port] - port `obscura serve` listens on, in SELF-MANAGED mode. When unset, a
+     * @property [binaryPath] - path to the `lightpanda` executable, used in SELF-MANAGED mode
+     * (`endpoint` unset). Checked before `LIGHTPANDA_PATH` and `PATH`.
+     * @property [port] - port `lightpanda serve` listens on, in SELF-MANAGED mode. When unset, a
      * free port is picked automatically, which is what makes `run-workers` collision-free — every
      * worker gets its own instance on its own port with zero config.
-     * @property [serverStartTimeout = 15000] - milliseconds to wait for a spawned `obscura serve`
+     * @property [serverStartTimeout = 15000] - milliseconds to wait for a spawned `lightpanda serve`
      * to answer `/json/version` before `_connect` gives up.
      */
-    type ObscuraConfig = {
+    type LightpandaConfig = {
         endpoint?: string;
         binaryPath?: string;
         port?: number;
         serverStartTimeout?: number;
     };
     /**
-     * Obscura drives [Obscura](https://github.com/h4ckf0r0day/obscura), a minimal headless
-     * browser exposed over the Chrome DevTools Protocol. From v0.2.0, default release builds ship a
-     * real rendering engine (layout, paint, screenshots); `-no-render` variants and v0.1.x builds keep
-     * the original single-V8-isolate, nothing-rendered mode. This helper does not hardcode which mode a
-     * given binary is in — `CDPBrowser._probeCapabilities` detects `layout`/`screenshot` per binary at
-     * runtime, so the same helper works against either.
+     * Lightpanda drives [Lightpanda](https://lightpanda.io), a headless browser written from scratch
+     * for automation, exposed over the Chrome DevTools Protocol. It executes real JavaScript in V8 and
+     * implements the DOM and Web APIs, but has no graphical rendering engine: nothing is ever painted,
+     * so there are no screenshots.
      *
      * This helper is a thin `CDPBrowser` subclass: it changes nothing about how locating or acting on
-     * elements works, it only pins the config presets Obscura requires and manages the `obscura serve`
-     * process lifecycle, the same way Playwright manages its own browser process.
+     * elements works, it only pins the config presets Lightpanda requires and manages the
+     * `lightpanda serve` process lifecycle, the same way Playwright manages its own browser process.
+     *
+     * > Lightpanda support is experimental. Pin the browser version in CI and keep a
+     * > Playwright/WebDriver job for browser-compatibility coverage.
+     *
+     * ## Modes
+     *
+     * - **ATTACH** — `endpoint` is set explicitly in the config. The helper only connects to it; it
+     *   never spawns or kills anything, no matter what `binaryPath`/`port` are set to.
+     * - **SELF-LAUNCH** — `endpoint` is unset and a binary can be resolved, in order: `binaryPath` in
+     *   the config, then the `LIGHTPANDA_PATH` environment variable, then `lightpanda` on `PATH`. The
+     *   helper spawns `lightpanda serve --host 127.0.0.1 --port <port>` (`port` from the config, or a
+     *   free port picked automatically), waits for it to answer, connects, and kills it in
+     *   `_finishTest`.
+     * - **COURTESY-ATTACH** — `endpoint` is unset and no binary can be resolved, but something already
+     *   answers `http://127.0.0.1:9222/json/version` (e.g. `lightpanda serve` started by hand, or the
+     *   `lightpanda/browser` Docker image). The helper attaches to it and never kills it. If neither a
+     *   binary nor a running server on :9222 can be found, the helper throws a loud, actionable error.
+     *
+     * ## Install
+     *
+     * Follow the [official installation instructions](https://lightpanda.io/docs/open-source/installation),
+     * then put `lightpanda` on your `PATH`, or point `binaryPath`/`LIGHTPANDA_PATH` at it. The helper
+     * then launches and tears it down automatically.
+     *
+     * Lightpanda sends usage telemetry by default. This helper always spawns it with
+     * `LIGHTPANDA_DISABLE_TELEMETRY=true`; set that variable yourself when you start the server by hand.
+     *
+     * Lightpanda is licensed under AGPL-3.0. It runs as a separate process that CodeceptJS talks to
+     * over a WebSocket, so it does not change the license of CodeceptJS or of your tests.
+     *
+     * ## Config presets
+     *
+     * These are set automatically and only need overriding for unusual setups:
+     *
+     * | option | value | why |
+     * | --- | --- | --- |
+     * | `input` | `synthetic` | nothing is painted, so coordinates are not hit-tested; `click` always takes the `forceClick` path |
+     * | `xpathPolyfill` | `auto` | probed per binary/page |
+     * | `capabilities.layout` | `real` | Lightpanda computes visibility-related styles and element boxes without painting, which is enough for `seeElement` and the `waitForVisible` family; it is pinned because the runtime layout probe cannot run on Lightpanda's `about:blank` |
+     * | `capabilities.screenshot` | `false` | there is no rendering engine |
+     *
+     * ## Limitations
+     *
+     * - No screenshots and no screencast: `saveScreenshot` throws.
+     * - No frames or popups.
+     * - No scrolling: scroll positions always stay at 0.
+     * - Computed styles cover what visibility checks need (`display`, `visibility`, `opacity`,
+     *   `pointer-events`); `grabCssPropertyFrom` and `seeCssPropertiesOnElements` are unreliable for
+     *   other properties.
+     * - No coordinate-based input (`clickXY`).
+     * - No clipboard access.
+     * - Some rich text editors (TinyMCE, Trix, Monaco) never finish initialising.
+     *
+     * <!-- configuration -->
+     *
+     * ## Example
+     *
+     * ```js
+     * // inside codecept.conf.js — SELF-LAUNCH mode (recommended): the helper finds/starts/stops
+     * // lightpanda serve on its own, on a free port. Ideal for run-workers: every worker gets its
+     * // own instance with no config.
+     * {
+     *   helpers: {
+     *     Lightpanda: {
+     *       url: 'http://localhost',
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * ```js
+     * // ATTACH mode — connect to a Lightpanda instance you manage yourself (remote host, container, etc.)
+     * {
+     *   helpers: {
+     *     Lightpanda: {
+     *       url: 'http://localhost',
+     *       endpoint: 'http://127.0.0.1:9222',
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * ## Methods
+     */
+    class LightpandaTs {
+        constructor(config: LightpandaConfig);
+    }
+    /**
+     * ## Configuration
+     *
+     * This helper should be configured in codecept.conf.js
+     * @property [endpoint] - connect to a running Obscura instead of starting one (ATTACH mode).
+     * @property [binaryPath] - path to the `obscura` executable. Checked before `OBSCURA_PATH` and `PATH`.
+     * @property [port] - port for `obscura serve`. A free port is picked when unset, so parallel workers never collide.
+     * @property [serverStartTimeout = 15000] - how long to wait for `obscura serve` to start, in milliseconds.
+     */
+    type ObscuraConfig = {
+        endpoint?: string;
+        binaryPath?: string;
+        port?: number;
+        serverStartTimeout?: number;
+    };
+    /**
+     * Obscura drives [Obscura](https://github.com/h4ckf0r0day/obscura), a lightweight headless
+     * browser controlled over the Chrome DevTools Protocol. Default builds from v0.2.0 render pages
+     * (layout, screenshots); `-no-render` builds and v0.1.x run JavaScript and the DOM only. The helper
+     * detects which build it runs against, so the same config works for both.
+     *
+     * The helper starts and stops `obscura serve` for you, the same way Playwright manages its browser.
      *
      * > Obscura support is experimental in CodeceptJS 4.2. Pin the browser version in CI and keep a
      * > Playwright/WebDriver job for browser-compatibility coverage.
@@ -3517,8 +3523,8 @@ declare namespace CodeceptJS {
      * - **SELF-LAUNCH** — `endpoint` is unset and a binary can be resolved, in order: `binaryPath` in
      *   the config, then the `OBSCURA_PATH` environment variable, then `obscura` on `PATH`. The helper
      *   spawns `obscura serve --port <port> --allow-private-network --allow-file-access` (`port` from
-     *   the config, or a free port picked automatically), waits for it to answer, connects, and kills
-     *   it in `_finishTest`.
+     *   the config, or a free port picked automatically), waits for it to answer, connects, and stops
+     *   it when tests finish.
      * - **COURTESY-ATTACH** — `endpoint` is unset and no binary can be resolved, but something already
      *   answers `http://127.0.0.1:9222/json/version` (e.g. `obscura serve` started by hand, or by CI
      *   before this process ever ran). The helper attaches to it and never kills it — it isn't the
@@ -3557,13 +3563,11 @@ declare namespace CodeceptJS {
      *
      * | option | value | why |
      * | --- | --- | --- |
-     * | `input` | `synthetic` | coordinate-click navigation is unreliable over CDP on Obscura even on rendering builds (no `frameNavigated` event, stale `page.url()`); `click` always takes the `forceClick` path — on Obscura, `click` and `forceClick` are the same thing |
-     * | `xpathPolyfill` | `auto` | probed per binary/page: Obscura's native `document.evaluate` still doesn't support attribute selection or `not()`, so the polyfill is used until that lands |
+     * | `input` | `synthetic` | clicks that navigate are unreliable in Obscura, so `click` behaves like `forceClick` |
+     * | `xpathPolyfill` | `auto` | Obscura's XPath lacks attribute selection and `not()`, so the polyfill is used when needed |
      *
-     * `capabilities.layout`/`capabilities.screenshot`/`capabilities.xpath` are intentionally left
-     * unset here — `CDPBrowser._probeCapabilities` detects them at runtime from the actual binary
-     * (`'real'`/`true` on v0.2.0+ default builds, `'none'`/`false` on `-no-render` builds and v0.1.x).
-     * Set them explicitly in your own config to skip probing or to force a mode.
+     * `capabilities` are detected at runtime from the Obscura build. Set them in your config to skip
+     * detection or to force a mode.
      *
      * ## Limitations
      *
@@ -3610,62 +3614,6 @@ declare namespace CodeceptJS {
      */
     class ObscuraTs {
         constructor(config: ObscuraConfig);
-        /**
-         * In ATTACH mode, connects exactly as `CDPBrowser._connect` would. In SELF-MANAGED mode,
-         * resolves and spawns `obscura serve` (or courtesy-attaches to an already-running one on
-         * :9222) exactly once via `_resolveSelfManaged`, then connects.
-         *
-         * 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 _connect(): Promise<any>;
-        /**
-         * Resolves how to reach Obscura when no explicit `endpoint` was configured, trying, in order:
-         * spawn a binary (`binaryPath` config, then `OBSCURA_PATH` env, then `obscura` on `PATH`),
-         * courtesy-attach to `http://127.0.0.1:9222` if something already answers there, or throw a
-         * loud, actionable error. Sets `this.options.endpoint` as a side effect.
-         */
-        protected _resolveSelfManaged(): Promise<any>;
-        /**
-         * Resolves the `obscura` binary to spawn, in priority order: `options.binaryPath`, then the
-         * `OBSCURA_PATH` environment variable, then `obscura` 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 an `obscura.exe` on `PATH` is found too.
-         */
-        protected _resolveBinary(): Promise<any>;
-        /**
-         * Picks a free TCP port on 127.0.0.1 by briefly listening on port 0 and reading back the OS-assigned
-         * port. Used as the SELF-LAUNCH default when `options.port` isn't explicitly set, so multiple
-         * `run-workers` workers never collide on the same port.
-         * @returns a free port.
-         */
-        protected _findFreePort(): Promise<number>;
-        /**
-         * Probes a `/json/version`-style URL with a short timeout, used for the COURTESY-ATTACH check.
-         * @returns true if the URL answered.
-         */
-        protected _probeUp(url: string): Promise<boolean>;
-        /**
-         * Polls `http://127.0.0.1:<port>/json/version` until `obscura serve` responds, `this.serverError`
-         * is set by the spawned process' `error` event, or `options.serverStartTimeout` elapses. The
-         * process typically comes up within tens of milliseconds — a 20ms retry interval (down from a
-         * previous 200ms) 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 _waitForServer(): Promise<any>;
-        /**
-         * Closes the CDP connection (via `CDPBrowser._finishTest`), then kills the `obscura serve`
-         * process spawned by `_connect`, if any (never runs in ATTACH or COURTESY-ATTACH mode, since
-         * `this.serverProcess` is only ever set in SELF-LAUNCH mode). Runs in a `finally` so the process
-         * is always reaped even if closing the CDP connection throws. 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 _finishTest(): Promise<any>;
     }
     /**
      * ## Configuration