codeceptjs 4.1.0 → 4.2.0-beta.1

package/typings/types.d.ts

@@ -1186,6 +1186,1573 @@ declare namespace CodeceptJS {
          */
         waitForText(text: string, sec?: number, context?: CodeceptJS.LocatorOrString): void;
     }
+    /**
+     * ## Configuration
+     *
+     * 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.
+     */
+    type CDPBrowserConfig = {
+        url?: string;
+        endpoint?: string;
+        headers?: any;
+        input?: string;
+        xpathPolyfill?: string | boolean;
+        capabilities?: any;
+        waitForTimeout?: number;
+        waitForAction?: number;
+        pollInterval?: number;
+        getPageTimeout?: number;
+        waitForNavigation?: string;
+    };
+    /**
+     * CDPBrowser drives a browser directly over the raw Chrome DevTools Protocol, without depending
+     * on Puppeteer, Playwright, or WebDriver. It opens its own WebSocket connection (via `CDPConnection`),
+     * creates and attaches to a fresh target per test, and evaluates expressions through `Runtime.evaluate`.
+     *
+     * It is intended as the minimal, dependency-light base class for helpers that only need navigation,
+     * 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`.
+     *
+     * ## Example
+     *
+     * ```js
+     * // inside codecept.conf.js
+     * {
+     *   helpers: {
+     *     CDPBrowser: {
+     *       url: 'http://localhost',
+     *       endpoint: 'http://127.0.0.1:9222',
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * <!-- configuration -->
+     *
+     * ## Methods
+     */
+    class CDPBrowser {
+        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.
+         */
+        _init(): void;
+        /**
+         * Resolves `options.endpoint` to a raw WebSocket debugger URL. If the configured endpoint is
+         * an `http(s)://` address, this fetches `/json/version` from it and reads `webSocketDebuggerUrl`
+         * from the response, matching the discovery flow exposed by Chrome's `--remote-debugging-port`.
+         * A `ws(s)://` endpoint is returned unchanged.
+         *
+         * This is the subclass override point for helpers that connect through a different discovery
+         * mechanism (e.g. a cloud browser provider with its own session-creation API).
+         * @returns a `ws(s)://` debugger URL ready to be passed to `CDPConnection`.
+         */
+        protected _resolveEndpoint(): Promise<string>;
+        /**
+         * Resolves the CDP endpoint and opens the underlying `CDPConnection`, storing it on `this.cdp`.
+         */
+        protected _connect(): void;
+        /**
+         * 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(): void;
+        /**
+         * 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(): void;
+        /**
+         * 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): 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(): any | null;
+        /**
+         * 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(): void;
+        /**
+         * 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.
+         */
+        protected _finishTest(): void;
+        /**
+         * 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(): void;
+        /**
+         * 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): void;
+        /**
+         * 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; }[][]): boolean;
+        /**
+         * 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(): void;
+        /**
+         * 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.
+         * @returns descriptor with optional `index` and `strict` keys, or `null` when neither applies.
+         */
+        protected _selectionDescriptor(): any | null;
+        /**
+         * 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; }[]): string;
+        /**
+         * 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.
+         */
+        _withinBegin(locator: CodeceptJS.LocatorOrString): Promise<void>;
+        /**
+         * Ends the current `within` block, restoring unscoped element lookups.
+         */
+        _withinEnd(): Promise<void>;
+        /**
+         * 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`.
+         */
+        protected _poll(fn: (...params: any[]) => any, timeoutSec: number, message: string, cancelToken?: any): 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`.
+         * @returns the resolved, absolute URL.
+         */
+        protected _url(path: string): string;
+        /**
+         * Opens a web page in the current session.
+         *
+         * ```js
+         * I.amOnPage('/'); // opens main page of website
+         * I.amOnPage('https://github.com'); // opens github
+         * I.amOnPage('/login'); // opens a login page
+         * ```
+         *
+         * Navigates via `Page.navigate`, then waits (up to `options.getPageTimeout` seconds) for the page
+         * to finish loading, preferring the push-based `Page.lifecycleEvent` signal (per
+         * `options.waitForNavigation`) over polling `document.readyState`. Capabilities are (re-)probed
+         * (a no-op after the first page, since they're cached for the helper's lifetime).
+         *
+         * The in-page client is deliberately *not* eagerly (re-)installed here — navigation discards any
+         * previously injected script, but installing it is deferred to the first actual action after
+         * this call, via `_runSelected`'s sentinel-and-retry. This keeps `amOnPage` itself down to the
+         * navigate command plus the push-based wait: no `_evaluate` call is issued on this hot path,
+         * which matters most right when the page's own JavaScript may still be busy (measured directly:
+         * an `_evaluate` sent in that window can queue behind it for hundreds of ms to multiple seconds
+         * on a JS-heavy real-world page, regardless of how small the evaluated expression is).
+         * @param url - url path or global url.
+         */
+        amOnPage(url: string): Promise<void>;
+        /**
+         * Reloads 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>;
+        /**
+         * Executes a JavaScript function in the browser context and returns its result.
+         *
+         * If a function is passed, it is serialized with `Function.prototype.toString()`, so it must
+         * not reference variables from the outer (Node.js) scope — pass any needed data as arguments
+         * instead. A string is evaluated as-is.
+         *
+         * ```js
+         * let title = await I.executeScript(() => document.title);
+         * let sum = await I.executeScript((a, b) => a + b, 2, 3);
+         * ```
+         *
+         * If the function returns a promise, `executeScript` waits for it to resolve.
+         * @param 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.
+         */
+        executeScript(fn: string | ((...params: any[]) => any), ...args: any[]): Promise<any>;
+        /**
+         * Retrieves the page URL of the current page.
+         *
+         * ```js
+         * let url = await I.grabCurrentUrl();
+         * console.log(`Current URL is [${url}]`);
+         * ```
+         * @returns current URL.
+         */
+        grabCurrentUrl(): Promise<string>;
+        /**
+         * Retrieves a page title.
+         *
+         * ```js
+         * let title = await I.grabTitle();
+         * ```
+         * @returns title of the page.
+         */
+        grabTitle(): Promise<string>;
+        /**
+         * Retrieves the source code of the current page.
+         *
+         * ```js
+         * let pageSource = await I.grabSource();
+         * ```
+         * @returns source code of the current page (the outer HTML of `<html>`).
+         */
+        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.
+         * @returns candidates to pass to `_run`.
+         */
+        protected _candidates(locator: CodeceptJS.LocatorOrString, kind?: 'element' | 'clickable' | 'field' | 'checkable'): { type: 'css' | 'xpath' | 'role'; value: string | object; }[];
+        /**
+         * 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.
+         *
+         * ```js
+         * I.see('Welcome'); // text welcome on a page
+         * I.see('Welcome', '.content'); // text inside .content div
+         * I.see('Register', {css: 'form.register'}); // use strict locator
+         * ```
+         * @param 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>;
+        /**
+         * Opposite to `see`. Checks that a text is not present on a page.
+         * Use context parameter to narrow down the search.
+         *
+         * ```js
+         * I.dontSee('Login'); // assume we are already logged in.
+         * I.dontSee('Login', '.nav'); // no login inside .nav element
+         * ```
+         * @param text - which is not present.
+         * @param [context = null] - (optional) element located by CSS|XPath|strict locator in which to perform search.
+         */
+        dontSee(text: string, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        /**
+         * Checks that the current page contains the given string in its raw source code.
+         *
+         * ```js
+         * I.seeInSource('<h1>Green eggs &amp; ham</h1>');
+         * ```
+         * @param text - value to check.
+         */
+        seeInSource(text: string): Promise<void>;
+        /**
+         * Checks that the current page does not contain the given string in its raw source code.
+         * @param text - value to check.
+         */
+        dontSeeInSource(text: string): Promise<void>;
+        /**
+         * Checks that current url contains a provided fragment.
+         *
+         * ```js
+         * I.seeInCurrentUrl('/register'); // we are on registration page
+         * ```
+         * @param url - a fragment to check
+         */
+        seeInCurrentUrl(url: string): Promise<void>;
+        /**
+         * Checks that current url does not contain a provided fragment.
+         * @param url - value to check.
+         */
+        dontSeeInCurrentUrl(url: string): Promise<void>;
+        /**
+         * Checks that title contains text.
+         *
+         * ```js
+         * I.seeInTitle('Home Page');
+         * ```
+         * @param text - text value to check.
+         */
+        seeInTitle(text: string): Promise<void>;
+        /**
+         * Checks that a given Element is present in the DOM.
+         * Element is located by CSS or XPath.
+         *
+         * ```js
+         * I.seeElementInDOM('#modal');
+         * ```
+         * @param locator - element located by CSS|XPath|strict locator.
+         */
+        seeElementInDOM(locator: CodeceptJS.LocatorOrString): Promise<void>;
+        /**
+         * 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.
+         */
+        protected _assertLayoutSupported(action: string): void;
+        /**
+         * Checks that a given Element is visible.
+         * Element is located by CSS or XPath.
+         *
+         * ```js
+         * I.seeElement('#modal');
+         * ```
+         * @param locator - located by CSS|XPath|strict locator.
+         * @param [context = null] - (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+         */
+        seeElement(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        /**
+         * Opposite to `seeElement`. Checks that element is not visible.
+         *
+         * ```js
+         * I.dontSeeElement('.modal'); // modal is not shown
+         * ```
+         * @param locator - located by CSS|XPath|strict locator.
+         * @param [context = null] - (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+         */
+        dontSeeElement(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        /**
+         * Verifies that the specified checkbox is checked.
+         *
+         * ```js
+         * I.seeCheckboxIsChecked('Agree');
+         * I.seeCheckboxIsChecked('#agree'); // I suppose user agreed to terms
+         * I.seeCheckboxIsChecked({css: '#signup_form input[type=checkbox]'});
+         * ```
+         * @param locator - located by label|name|CSS|XPath|strict locator.
+         */
+        seeCheckboxIsChecked(locator: CodeceptJS.LocatorOrString): Promise<void>;
+        /**
+         * Verifies that the specified checkbox is not checked.
+         *
+         * ```js
+         * I.dontSeeCheckboxIsChecked('#agree'); // located by ID
+         * I.dontSeeCheckboxIsChecked('I agree to terms'); // located by label
+         * ```
+         * @param locator - located by label|name|CSS|XPath|strict locator.
+         */
+        dontSeeCheckboxIsChecked(locator: CodeceptJS.LocatorOrString): Promise<void>;
+        /**
+         * Retrieves a text from an element located by CSS or XPath and returns it to test.
+         * Resumes test execution, so **should be used inside async with `await`** operator.
+         *
+         * ```js
+         * let pin = await I.grabTextFrom('#pin');
+         * ```
+         * If multiple elements found returns first element.
+         * @param locator - element located by CSS|XPath|strict locator.
+         * @returns text value
+         */
+        grabTextFrom(locator: CodeceptJS.LocatorOrString): Promise<string>;
+        /**
+         * Retrieves all texts from elements located by CSS or XPath and returns it to test.
+         * Resumes test execution, so **should be used inside async with `await`** operator.
+         *
+         * ```js
+         * let pins = await I.grabTextFromAll('#pin li');
+         * ```
+         * @param locator - element located by CSS|XPath|strict locator.
+         * @returns array of text values
+         */
+        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.
+         *
+         * ```js
+         * const buttons = await I.grabWebElements({ role: 'button' });
+         * ```
+         * @param locator - element located by CSS|XPath|strict locator.
+         * @returns array of WebElement instances.
+         */
+        grabWebElements(locator: CodeceptJS.LocatorOrString): Promise<object[]>;
+        /**
+         * Retrieves the first `WebElement` matching a locator.
+         *
+         * ```js
+         * const button = await I.grabWebElement({ role: 'button', text: 'Submit' });
+         * ```
+         * @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.
+         */
+        protected _texts(candidates: { type: string; value: string | object; }[]): Promise<{ found: number; result: 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.
+         * If more than one element is found - value of first element is returned.
+         *
+         * ```js
+         * let email = await I.grabValueFrom('input[name=email]');
+         * ```
+         * @param locator - field located by label|name|CSS|XPath|strict locator.
+         * @returns attribute value
+         */
+        grabValueFrom(locator: CodeceptJS.LocatorOrString): Promise<string>;
+        /**
+         * Retrieves an array of values from fields located by CSS or XPath and returns it to test.
+         * Resumes test execution, so **should be used inside async function with `await`** operator.
+         *
+         * ```js
+         * let inputs = await I.grabValueFromAll('//form/input');
+         * ```
+         * @param locator - field located by label|name|CSS|XPath|strict locator.
+         * @returns array of attribute values
+         */
+        grabValueFromAll(locator: CodeceptJS.LocatorOrString): Promise<string[]>;
+        /**
+         * Retrieves an attribute from an element located by CSS or XPath and returns it to test.
+         * Resumes test execution, so **should be used inside async with `await`** operator.
+         * If more than one element is found - attribute of first element is returned.
+         *
+         * ```js
+         * let hint = await I.grabAttributeFrom('#tooltip', 'title');
+         * ```
+         * @param locator - element located by CSS|XPath|strict locator.
+         * @param attr - attribute name.
+         * @returns attribute value
+         */
+        grabAttributeFrom(locator: CodeceptJS.LocatorOrString, attr: string): Promise<string>;
+        /**
+         * Retrieves an array of attributes from elements located by CSS or XPath and returns it to test.
+         * Resumes test execution, so **should be used inside async with `await`** operator.
+         *
+         * ```js
+         * let hints = await I.grabAttributeFromAll('.tooltip', 'title');
+         * ```
+         * @param locator - element located by CSS|XPath|strict locator.
+         * @param attr - attribute name.
+         * @returns array of attribute values
+         */
+        grabAttributeFromAll(locator: CodeceptJS.LocatorOrString, attr: string): Promise<string[]>;
+        /**
+         * Grab number of elements by locator.
+         * Resumes test execution, so **should be used inside async function with `await`** operator.
+         *
+         * ```js
+         * let numOfElements = await I.grabNumberOfElements('p');
+         * ```
+         * @param locator - located by CSS|XPath|strict locator.
+         * @returns number of matched elements.
+         */
+        grabNumberOfElements(locator: CodeceptJS.LocatorOrString): Promise<number>;
+        /**
+         * Perform a click on a link or a button, given by a locator.
+         * If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.
+         * For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched.
+         * For images, the "alt" attribute and inner text of any parent links are searched.
+         *
+         * When `options.input` is `'cdp'`, the click is dispatched as real `Input.dispatchMouseEvent` mouse events
+         * (`mouseMoved` / `mousePressed` / `mouseReleased`) at the center of the element's bounding box, so it
+         * exercises the same input pipeline a real user would. Otherwise it delegates to `forceClick`. A matched
+         * element with a zero-size bounding box (e.g. `display: none`) has no valid coordinate to click and throws;
+         * use `forceClick` to dispatch a synthetic click on such elements instead.
+         *
+         * ```js
+         * // simple link
+         * I.click('Logout');
+         * // button of form
+         * I.click('Submit');
+         * // CSS button
+         * I.click('#form input[type=submit]');
+         * // XPath
+         * I.click('//form/*[@type=submit]');
+         * // using strict locator
+         * I.click({css: 'nav a.login'});
+         * ```
+         * @param 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.
+         */
+        click(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        /**
+         * Perform an emulated click on a link or a button, given by a locator.
+         * Unlike `click`, this always dispatches a synthetic in-page `el.click()` instead of sending native
+         * CDP input events. This works on hidden, animated or inactive elements as well.
+         *
+         * If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.
+         * For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched.
+         * For images, the "alt" attribute and inner text of any parent links are searched.
+         *
+         * ```js
+         * // simple link
+         * I.forceClick('Logout');
+         * // button of form
+         * I.forceClick('Submit');
+         * // CSS button
+         * I.forceClick('#form input[type=submit]');
+         * // XPath
+         * I.forceClick('//form/*[@type=submit]');
+         * // using strict locator
+         * I.forceClick({css: 'nav a.login'});
+         * ```
+         * @param 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>;
+        /**
+         * Fills a text field or textarea, after clearing its value, with the given string.
+         * Field is located by name, label, CSS, or XPath.
+         *
+         * ```js
+         * // by label
+         * I.fillField('Email', 'hello@world.com');
+         * // by name
+         * I.fillField('password', secret('123456'));
+         * // by CSS
+         * I.fillField('form#login input[name=username]', 'John');
+         * // or by strict locator
+         * I.fillField({css: 'form#login input[name=username]'}, 'John');
+         * ```
+         * @param 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.
+         */
+        fillField(field: CodeceptJS.LocatorOrString, value: CodeceptJS.StringOrSecret, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        /**
+         * Appends text to a input field or textarea.
+         * Field is located by name, label, CSS or XPath
+         *
+         * ```js
+         * I.appendField('#myTextField', 'appended');
+         * // typing secret
+         * I.appendField('password', secret('123456'));
+         * ```
+         * @param 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.
+         */
+        appendField(field: CodeceptJS.LocatorOrString, value: string, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        /**
+         * Clears a `<textarea>` or text `<input>` element's value.
+         *
+         * ```js
+         * I.clearField('Email');
+         * I.clearField('user[email]');
+         * I.clearField('#email');
+         * ```
+         * @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.
+         */
+        clearField(field: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        /**
+         * Selects an option in a drop-down select.
+         * Field is searched by label | name | CSS | XPath.
+         * Option is selected by visible text or by value.
+         *
+         * ```js
+         * I.selectOption('Choose Plan', 'Monthly'); // select by label
+         * I.selectOption('subscription', 'Monthly'); // match option by text
+         * I.selectOption('subscription', '0'); // or by value
+         * I.selectOption('//form/select[@name=account]','Premium');
+         * I.selectOption('form select[name=account]', 'Premium');
+         * I.selectOption({css: 'form select[name=account]'}, 'Premium');
+         * ```
+         * @param 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.
+         */
+        selectOption(select: CodeceptJS.LocatorOrString, option: string | string[], context?: CodeceptJS.LocatorOrString): Promise<void>;
+        /**
+         * Selects a checkbox or radio button.
+         * Element is located by label or name or CSS or XPath.
+         *
+         * ```js
+         * I.checkOption('#agree');
+         * I.checkOption('I Agree to Terms and Conditions');
+         * I.checkOption('agree', '//form');
+         * ```
+         * @param 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>;
+        /**
+         * Unselects a checkbox or radio button.
+         * Element is located by label or name or CSS or XPath.
+         *
+         * ```js
+         * I.uncheckOption('#agree');
+         * I.uncheckOption('I Agree to Terms and Conditions');
+         * I.uncheckOption('agree', '//form');
+         * ```
+         * @param 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>;
+        /**
+         * Attaches a file to a file input field, or drops it onto a drag-and-drop dropzone element,
+         * resolved by label|name|CSS|XPath|strict locator. `pathToFile` is resolved relative to
+         * `codecept_dir` (matching Puppeteer/WebDriver). Since `CDPBrowser` never brings element handles
+         * back to Node, the resolved element is marked with a throwaway `data-codecept-upload` attribute
+         * in-page (respecting `context`/`within`/elementIndex exactly like every other action). A real
+         * `<input type="file">` is then addressed by that attribute through the CDP `DOM` domain, which
+         * `CDPBrowser` otherwise never uses, to call `DOM.setFileInputFiles`; any other element (a
+         * drag-and-drop dropzone) instead gets a synthetic `dragenter`/`dragover`/`drop` sequence with a
+         * `DataTransfer` built from the file's contents, entirely in-page. The marker is removed again in
+         * a `finally`.
+         *
+         * ```js
+         * I.attachFile('Avatar', 'data/avatar.jpg');
+         * I.attachFile('#file', 'data/avatar.jpg');
+         * I.attachFile('#dropzone', 'data/avatar.jpg');
+         * ```
+         * @param 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.
+         */
+        attachFile(field: CodeceptJS.LocatorOrString, pathToFile: string, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        /**
+         * Waits for element to be present on page (by default waits for `options.waitForTimeout` seconds).
+         * Element can be located by CSS or XPath.
+         *
+         * ```js
+         * I.waitForElement('.btn.continue');
+         * I.waitForElement('.btn.continue', 5); // wait for 5 secs
+         * ```
+         * @param locator - element located by CSS|XPath|strict locator.
+         * @param [sec = null] - (optional, `options.waitForTimeout` by default) time in seconds to wait
+         */
+        waitForElement(locator: CodeceptJS.LocatorOrString, sec?: number): Promise<void>;
+        /**
+         * Waits for a text to appear (by default waits for `options.waitForTimeout` seconds).
+         * Element can be located by CSS or XPath.
+         * Narrow down search results by providing context.
+         *
+         * ```js
+         * I.waitForText('Thank you, form has been submitted');
+         * I.waitForText('Thank you, form has been submitted', 5, '#modal');
+         * ```
+         * @param text - to wait for.
+         * @param [sec = null] - (optional, `options.waitForTimeout` 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>;
+        /**
+         * Waiting for the part of the URL to match the expected. Useful for SPA to understand that page was changed.
+         *
+         * ```js
+         * I.waitInUrl('/info', 2);
+         * ```
+         * @param urlPart - value to check.
+         * @param [sec = null] - (optional, `options.waitForTimeout` by default) time in seconds to wait
+         */
+        waitInUrl(urlPart: string, sec?: number): Promise<void>;
+        /**
+         * Waits for a function to return true (waits for `options.waitForTimeout` seconds by default).
+         * Running in browser context.
+         *
+         * ```js
+         * I.waitForFunction(() => window.requests == 0);
+         * I.waitForFunction(() => window.requests == 0, 5); // waits for 5 sec
+         * I.waitForFunction((count) => window.requests == count, [3], 5) // pass args and wait for 5 sec
+         * ```
+         * @param 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
+         */
+        waitForFunction(fn: string | ((...params: any[]) => any), argsOrSec?: any[] | number, sec?: number): Promise<void>;
+        /**
+         * Sets cookie(s).
+         *
+         * Can be a single cookie object or an array of cookies:
+         *
+         * ```js
+         * I.setCookie({name: 'auth', value: true});
+         *
+         * // as array
+         * I.setCookie([
+         *   {name: 'auth', value: true},
+         *   {name: 'agree', value: true}
+         * ]);
+         * ```
+         * @param cookie - a cookie object or array of cookie objects.
+         */
+        setCookie(cookie: CodeceptJS.Cookie | CodeceptJS.Cookie[]): Promise<void>;
+        /**
+         * Retrieves all cookies visible to the current page.
+         * Resumes test execution, so **should be used inside async function with `await`** operator.
+         *
+         * ```js
+         * let cookies = await I.grabCookies();
+         * ```
+         * @returns array of cookie objects.
+         */
+        grabCookies(): Promise<CodeceptJS.Cookie[]>;
+        /**
+         * Gets a cookie object by name.
+         * If none provided gets all cookies.
+         * Resumes test execution, so **should be used inside async function with `await`** operator.
+         *
+         * ```js
+         * let cookie = await I.grabCookie('auth');
+         * assert(cookie.value, '123456');
+         * ```
+         * @param [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[]>;
+        /**
+         * Clears a cookie by name,
+         * if none provided clears all cookies.
+         *
+         * ```js
+         * I.clearCookie();
+         * I.clearCookie('test');
+         * ```
+         * @param [name = null] - (optional, `null` by default) cookie name
+         */
+        clearCookie(name?: string | null): Promise<void>;
+        /**
+         * Saves a screenshot to the output folder (set in codecept.conf.ts or codecept.conf.js).
+         * Filename is relative to the output folder.
+         *
+         * ```js
+         * I.saveScreenshot('debug.png');
+         * ```
+         * @param fileName - file name to save.
+         */
+        saveScreenshot(fileName: string): Promise<void>;
+        /**
+         * Saves a screenshot of a single element to the output folder.
+         *
+         * ```js
+         * I.saveElementScreenshot('#logo', 'logo.png');
+         * ```
+         * @param locator - element located by CSS|XPath|strict locator.
+         * @param fileName - file name to save.
+         */
+        saveElementScreenshot(locator: CodeceptJS.LocatorOrString, fileName: string): Promise<void>;
+        /**
+         * Pauses execution for a number of seconds.
+         *
+         * ```js
+         * I.wait(2); // waits 2 secs
+         * ```
+         * @param sec - number of seconds to wait.
+         */
+        wait(sec: number): Promise<void>;
+        /**
+         * Checks that title does not contain text.
+         * @param text - value to check.
+         */
+        dontSeeInTitle(text: string): Promise<void>;
+        /**
+         * Checks that current url is equal to provided one.
+         * Unlike `seeInCurrentUrl` performs a strict comparison.
+         *
+         * ```js
+         * I.seeCurrentUrlEquals('/register');
+         * ```
+         * @param url - value to check.
+         */
+        seeCurrentUrlEquals(url: string): Promise<void>;
+        /**
+         * Checks that current url is not equal to provided one.
+         * Unlike `dontSeeInCurrentUrl` performs a strict comparison.
+         * @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>;
+        /**
+         * Checks that current url path (ignoring query string and hash) equals to provided one.
+         *
+         * ```js
+         * I.seeCurrentPathEquals('/info');
+         * ```
+         * @param path - value to check.
+         */
+        seeCurrentPathEquals(path: string): Promise<void>;
+        /**
+         * Opposite to `seeCurrentPathEquals`.
+         * @param path - value to check.
+         */
+        dontSeeCurrentPathEquals(path: string): Promise<void>;
+        /**
+         * Waits for the entire URL to match the expected (by default waits for `options.waitForTimeout` seconds).
+         *
+         * ```js
+         * I.waitUrlEquals('/info', 2);
+         * ```
+         * @param urlPart - value to check.
+         * @param [sec = null] - (optional, `options.waitForTimeout` by default) time in seconds to wait
+         */
+        waitUrlEquals(urlPart: string, sec?: number): Promise<void>;
+        /**
+         * Waits for current url path (ignoring query string and hash) to equal to the expected.
+         *
+         * ```js
+         * I.waitCurrentPathEquals('/info', 2);
+         * ```
+         * @param path - value to check.
+         * @param [sec = null] - (optional, `options.waitForTimeout` by default) time in seconds to wait
+         */
+        waitCurrentPathEquals(path: string, sec?: number): Promise<void>;
+        /**
+         * Checks that the given input field or textarea equals (contains) the given value.
+         * For fuzzy locators, the field is searched by label|name|CSS|XPath|strict locator.
+         *
+         * ```js
+         * I.seeInField('Username', 'davert');
+         * ```
+         * @param 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.
+         */
+        seeInField(field: CodeceptJS.LocatorOrString, value: CodeceptJS.StringOrSecret, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        /**
+         * Opposite to `seeInField`.
+         * @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`.
+         */
+        protected _seeInField(assertType: 'assert' | 'negate', field: CodeceptJS.LocatorOrString, value: CodeceptJS.StringOrSecret, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        /**
+         * Grab number of visible elements by locator.
+         *
+         * ```js
+         * let numOfVisibleElements = await I.grabNumberOfVisibleElements('p');
+         * ```
+         * @param locator - located by CSS|XPath|strict locator.
+         * @returns number of visible matched 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.
+         *
+         * ```js
+         * I.seeNumberOfVisibleElements('.buttons', 3);
+         * ```
+         * @param locator - located by CSS|XPath|strict locator.
+         * @param num - expected number of elements.
+         */
+        seeNumberOfVisibleElements(locator: CodeceptJS.LocatorOrString, num: number): Promise<void>;
+        /**
+         * Retrieves the current page scroll position.
+         *
+         * ```js
+         * let { x, y } = await I.grabPageScrollPosition();
+         * ```
+         * @returns scroll position.
+         */
+        grabPageScrollPosition(): Promise<{ x: number; y: number; }>;
+        /**
+         * Scrolls to the top of the page.
+         *
+         * ```js
+         * I.scrollPageToTop();
+         * ```
+         */
+        scrollPageToTop(): Promise<void>;
+        /**
+         * Scrolls to the bottom of the page.
+         *
+         * ```js
+         * I.scrollPageToBottom();
+         * ```
+         */
+        scrollPageToBottom(): Promise<void>;
+        /**
+         * Scrolls to the element matched by locator, or to given coordinates.
+         *
+         * ```js
+         * I.scrollTo('#submit');
+         * I.scrollTo(100, 200);
+         * ```
+         * @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.
+         */
+        scrollTo(locator: CodeceptJS.LocatorOrString | number, offsetX?: number, offsetY?: number): Promise<void>;
+        /**
+         * Retrieves a CSS property from an element located by CSS or XPath.
+         * If more than one element is found - value of first element is returned.
+         *
+         * ```js
+         * const value = await I.grabCssPropertyFrom('h3', 'font-weight');
+         * ```
+         * @param locator - element located by CSS|XPath|strict locator.
+         * @param cssProperty - CSS property name.
+         * @returns CSS value
+         */
+        grabCssPropertyFrom(locator: CodeceptJS.LocatorOrString, cssProperty: string): Promise<string>;
+        /**
+         * Retrieves an array of CSS properties from elements located by CSS or XPath.
+         *
+         * ```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
+         */
+        grabCssPropertyFromAll(locator: CodeceptJS.LocatorOrString, cssProperty: string): Promise<string[]>;
+        /**
+         * Checks that all elements matched by locator have the given CSS properties.
+         *
+         * ```js
+         * I.seeCssPropertiesOnElements('h3', { 'font-weight': 'bold', display: 'block' });
+         * ```
+         * @param locator - element 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>;
+        /**
+         * Checks that all elements matched by locator have the given attribute values.
+         * An expected value is matched either as an exact match or as a regular expression against the actual value.
+         *
+         * ```js
+         * I.seeAttributesOnElements('//form', { method: 'post' });
+         * ```
+         * @param locator - element located by CSS|XPath|strict locator.
+         * @param attributes - object with attribute names and expected values.
+         */
+        seeAttributesOnElements(locator: CodeceptJS.LocatorOrString, attributes: any): Promise<void>;
+        /**
+         * Focuses a given element.
+         *
+         * ```js
+         * I.focus('#name');
+         * ```
+         * @param locator - element located by CSS|XPath|strict locator.
+         */
+        focus(locator: CodeceptJS.LocatorOrString): Promise<void>;
+        /**
+         * Removes focus from a given element.
+         *
+         * ```js
+         * I.blur('#name');
+         * ```
+         * @param locator - element located by CSS|XPath|strict locator.
+         */
+        blur(locator: CodeceptJS.LocatorOrString): Promise<void>;
+        /**
+         * Types characters into the currently focused element (as set by `click`, `focus`, etc). Each
+         * character dispatches a real `keydown` → `keypress` → (value mutated) → `input` → `keyup`
+         * sequence, and mutates a `contenteditable` host's `textContent` instead of `.value`, so this
+         * works on rich-text/contenteditable targets as well as `input`/`textarea`. Mirrors Puppeteer's
+         * `type(text, options)` semantics.
+         *
+         * Without a `delay`, every character is dispatched in a single round-trip to the page. With a
+         * `delay`, characters are dispatched one round-trip at a time so the requested pause actually
+         * elapses between key presses.
+         *
+         * ```js
+         * I.click('Name');
+         * I.type('CodeceptJS');
+         * I.type(['C', 'o', 'd', 'e']);
+         * ```
+         * @param keys - characters to type, either as a string or an array of characters.
+         * @param [delay = null] - (optional) delay in milliseconds between key presses.
+         */
+        type(keys: string | string[], delay?: number): Promise<void>;
+        /**
+         * 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.
+         *
+         * ```js
+         * I.pressKey('Enter');
+         * I.pressKey(['Control', 'a']);
+         * ```
+         * @param key - a key or an array of keys to combine (modifiers first).
+         */
+        pressKey(key: string | string[]): Promise<void>;
+        /**
+         * Resizes the browser viewport.
+         *
+         * ```js
+         * I.resizeWindow(1024, 768);
+         * ```
+         * @param width - window width, or `'maximize'`.
+         * @param [height] - window height.
+         */
+        resizeWindow(width: number | 'maximize', height?: number): Promise<void>;
+        /**
+         * Performs a double-click on an element matched by locator.
+         *
+         * ```js
+         * I.doubleClick('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).
+         */
+        doubleClick(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        /**
+         * Performs a right-click on an element matched by locator.
+         *
+         * ```js
+         * I.rightClick('Menu');
+         * ```
+         * @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).
+         */
+        rightClick(locator: CodeceptJS.LocatorOrString, context?: CodeceptJS.LocatorOrString): Promise<void>;
+        /**
+         * 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.
+         *
+         * ```js
+         * I.clickXY(100, 200); // global 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.
+         */
+        clickXY(locator: CodeceptJS.LocatorOrString | number, x?: number, y?: number): Promise<void>;
+        /**
+         * Waits for an element to become visible (by default waits for `options.waitForTimeout` seconds).
+         *
+         * ```js
+         * I.waitForVisible('#popup', 5);
+         * ```
+         * @param locator - element located by CSS|XPath|strict locator.
+         * @param [sec = null] - (optional, `options.waitForTimeout` by default) time in seconds to wait
+         */
+        waitForVisible(locator: CodeceptJS.LocatorOrString, sec?: number): Promise<void>;
+        /**
+         * Waits for an element to become invisible (by default waits for `options.waitForTimeout` seconds).
+         *
+         * ```js
+         * I.waitForInvisible('#popup', 5);
+         * ```
+         * @param locator - element located by CSS|XPath|strict locator.
+         * @param [sec = null] - (optional, `options.waitForTimeout` by default) time in seconds to wait
+         */
+        waitForInvisible(locator: CodeceptJS.LocatorOrString, sec?: number): Promise<void>;
+        /**
+         * Waits for an element to be hidden. Alias of `waitForInvisible`.
+         * @param locator - element located by CSS|XPath|strict locator.
+         * @param [sec = null] - (optional, `options.waitForTimeout` by default) time in seconds to wait
+         */
+        waitToHide(locator: CodeceptJS.LocatorOrString, sec?: number): Promise<void>;
+        /**
+         * Waits for an element to be removed from the DOM (by default waits for `options.waitForTimeout` seconds).
+         *
+         * ```js
+         * I.waitForDetached('#popup', 5);
+         * ```
+         * @param locator - element located by CSS|XPath|strict locator.
+         * @param [sec = null] - (optional, `options.waitForTimeout` by default) time in seconds to wait
+         */
+        waitForDetached(locator: CodeceptJS.LocatorOrString, sec?: number): Promise<void>;
+        /**
+         * Checks that a cookie with the given name is set.
+         * @param name - cookie name.
+         */
+        seeCookie(name: string): Promise<void>;
+        /**
+         * Checks that a cookie with the given name is not set.
+         * @param name - cookie name.
+         */
+        dontSeeCookie(name: string): Promise<void>;
+        /**
+         * Waits for a cookie with the given name to be set (by default waits for `options.waitForTimeout` seconds).
+         *
+         * ```js
+         * I.waitForCookie('auth', 5);
+         * ```
+         * @param name - cookie name.
+         * @param [sec = null] - (optional, `options.waitForTimeout` by default) time in seconds to wait
+         */
+        waitForCookie(name: string, sec?: number): Promise<void>;
+        /**
+         * Retrieves the inner HTML from an element located by CSS or XPath.
+         * If more than one element is found - HTML of first element is returned.
+         *
+         * ```js
+         * let postHTML = await I.grabHTMLFrom('#post');
+         * ```
+         * @param locator - element located by CSS|XPath|strict locator.
+         * @returns HTML code for an element
+         */
+        grabHTMLFrom(locator: CodeceptJS.LocatorOrString): Promise<string>;
+        /**
+         * Retrieves the inner HTML from elements located by CSS or XPath.
+         *
+         * ```js
+         * let postHTMLs = await I.grabHTMLFromAll('.post');
+         * ```
+         * @param locator - element located by CSS|XPath|strict locator.
+         * @returns HTML code for matched elements
+         */
+        grabHTMLFromAll(locator: 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`.
+         *
+         * ```js
+         * const val = await I.executeAsyncScript(function(val, done) {
+         *   setTimeout(() => done(val + 1), 100)
+         * }, 5)
+         * ```
+         * @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`.
+         */
+        executeAsyncScript(fn: (...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.
+         *
+         * ```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(): void;
+        /**
+         * `Network.responseReceived` handler, resolving the matching pending `response` promise pushed
+         * by `_onTrafficRequest` with a Puppeteer-`HTTPResponse`-like object.
+         */
+        protected _onTrafficResponse(): void;
+        /**
+         * `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(): void;
+        /**
+         * Grab the recording network traffics
+         *
+         * ```js
+         * const traffics = await I.grabRecordedNetworkTraffics();
+         * expect(traffics[0].url).to.equal('https://reqres.in/api/comments/1');
+         * expect(traffics[0].response.status).to.equal(200);
+         * expect(traffics[0].response.body).to.contain({ name: 'this was mocked' });
+         * ```
+         * @returns recorded network traffics
+         */
+        grabRecordedNetworkTraffics(): any[];
+        /**
+         * Verifies that a certain request is part of network traffic.
+         *
+         * ```js
+         * // checking the request url contains certain query strings
+         * I.amOnPage('https://openai.com/blog/chatgpt');
+         * I.startRecordingTraffic();
+         * await I.seeTraffic({
+         *     name: 'sentry event',
+         *     url: 'https://images.openai.com/blob/cf717bdb-0c8c-428a-b82b-3c3add87a600',
+         *     parameters: {
+         *     width: '1919',
+         *     height: '1138',
+         *     },
+         *   });
+         * ```
+         *
+         * ```js
+         * // checking the request url contains certain post data
+         * I.amOnPage('https://openai.com/blog/chatgpt');
+         * I.startRecordingTraffic();
+         * await I.seeTraffic({
+         *     name: 'event',
+         *     url: 'https://cloudflareinsights.com/cdn-cgi/rum',
+         *     requestPostData: {
+         *     st: 2,
+         *     },
+         *   });
+         * ```
+         * @param opts - options when checking the traffic network.
+         * @param opts.name - A name of that request. Can be any value. Only relevant to have a more meaningful error message in case of fail.
+         * @param opts.url - Expected URL of request in network traffic
+         * @param [opts.parameters] - Expected parameters of that request in network traffic
+         * @param [opts.requestPostData] - Expected that request contains post data in network traffic
+         * @param [opts.timeout] - Timeout to wait for request in seconds. Default is 10 seconds.
+         * @returns automatically synchronized promise through #recorder
+         */
+        seeTraffic(opts: {
+            name: string;
+            url: string;
+            parameters?: any;
+            requestPostData?: any;
+            timeout?: number;
+        }): void;
+        /**
+         * Verifies that a certain request is not part of network traffic.
+         *
+         * Examples:
+         *
+         * ```js
+         * I.dontSeeTraffic({ name: 'Unexpected API Call', url: 'https://api.example.com' });
+         * I.dontSeeTraffic({ name: 'Unexpected API Call of "user" endpoint', url: /api.example.com.*user/ });
+         * ```
+         * @param opts - options when checking the traffic network.
+         * @param opts.name - A name of that request. Can be any value. Only relevant to have a more meaningful error message in case of fail.
+         * @param opts.url - Expected URL of request in network traffic. Can be a string or a regular expression.
+         * @returns automatically synchronized promise through #recorder
+         */
+        dontSeeTraffic(opts: {
+            name: string;
+            url: string | RegExp;
+        }): void;
+        /**
+         * Stops recording network traffic started by `startRecordingTraffic`. Already-recorded requests
+         * in `this.requests` are kept; only new requests stop being appended.
+         *
+         * ```js
+         * I.stopRecordingTraffic();
+         * ```
+         */
+        stopRecordingTraffic(): void;
+        /**
+         * Resets all recorded network requests.
+         *
+         * ```js
+         * I.flushNetworkTraffics();
+         * ```
+         */
+        flushNetworkTraffics(): void;
+        /**
+         * 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.
+         *
+         * ```js
+         * I.startScreencast();
+         * ```
+         * @param [options] - {maxWidth: number, maxHeight: number, quality: number, everyNthFrame: number} — CDP `Page.startScreencast` pass-throughs. `format` is always `'png'`.
+         */
+        startScreencast(options?: any): Promise<void>;
+        /**
+         * `Page.screencastFrame` handler: ignores frames from a session other than the currently active
+         * one (stale frames from a previous test, since the listener is never removed), acknowledges the
+         * frame so the browser keeps sending more, and buffers `{data, timestamp}` for `stopScreencast`
+         * to assemble.
+         */
+        protected _onScreencastFrame(): void;
+        /**
+         * 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).
+         *
+         * ```js
+         * const apngBuffer = await I.stopScreencast();
+         * ```
+         * @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.
+         */
+        stopScreencast(options?: any): Promise<object>;
+    }
     /**
      * Helper for testing filesystem.
      * Can be easily used to check file structures:
@@ -1761,6 +3328,279 @@ declare namespace CodeceptJS {
          */
         seeResponseMatchesJsonSchema(fnOrSchema: any): void;
     }
+    /**
+     * ## Configuration
+     *
+     * This helper should be configured in codecept.conf.js. It accepts everything `CDPBrowser`
+     * accepts (see its config table), plus:
+     * @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 }
+     */
+    type KitesurfConfig = {
+        url?: string;
+        accountId?: string;
+        apiToken?: string;
+        keepAlive?: number;
+        apiBase?: string;
+        input?: string;
+        capabilities?: any;
+    };
+    /**
+     * Kitesurf is a cloud browser helper that extends CDPBrowser to run tests against
+     * Cloudflare's Browser Run service (Kitesurf browser). It automates real browser
+     * sessions in Cloudflare's cloud infrastructure, eliminating the need to manage
+     * local browser instances.
+     *
+     * **Status:** Beta
+     *
+     * ## Requirements
+     *
+     * - Cloudflare account with Browser Run enabled
+     * - API token with **Browser Rendering Edit** permission
+     *
+     * ## Setup
+     *
+     * To create an API token with Browser Rendering Edit permission:
+     * 1. Log in to your Cloudflare dashboard
+     * 2. Go to My Profile > API Tokens
+     * 3. Click "Create Token"
+     * 4. Use the "Custom token" template
+     * 5. Under "Permissions", select "Browser Rendering" > "Edit"
+     * 6. Set the account scope to your target account
+     * 7. Copy the token and set it as `CF_API_TOKEN` environment variable
+     *
+     * For more details, see:
+     * - [Cloudflare Browser Run Developers Docs](https://developers.cloudflare.com/browser-run/)
+     * - [Cloudflare Blog - Kitesurf Announcement](https://blog.cloudflare.com/kitesurf/)
+     *
+     * ## Example
+     *
+     * ```js
+     * // codecept.conf.js
+     * {
+     *   helpers: {
+     *     Kitesurf: {
+     *       url: 'https://example.com',
+     *       accountId: process.env.CF_ACCOUNT_ID,
+     *       apiToken: process.env.CF_API_TOKEN,
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * Or set environment variables and rely on defaults:
+     *
+     * ```bash
+     * export CF_ACCOUNT_ID="your-account-id"
+     * export CF_API_TOKEN="your-api-token"
+     * ```
+     *
+     * <!-- configuration -->
+     *
+     * ## Methods
+     */
+    class Kitesurf {
+        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(): void;
+    }
+    /**
+     * ## Configuration
+     *
+     * This helper should be configured in codecept.conf.js. It accepts everything `CDPBrowser`
+     * accepts (see its config table), plus:
+     * @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
+     * 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`
+     * to answer `/json/version` before `_connect` gives up.
+     */
+    type ObscuraConfig = {
+        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.
+     *
+     * 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.
+     *
+     * ## 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 `OBSCURA_PATH` environment variable, then `obscura` on `PATH`. The helper
+     *   spawns `obscura serve --port <port> --allow-private-network` (`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. `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
+     *   helper's process to kill. If neither a binary nor a running server on :9222 can be found, the
+     *   helper throws a loud, actionable error.
+     *
+     * ## Install
+     *
+     * Download a release binary and put it on your `PATH` (or point `binaryPath`/`OBSCURA_PATH` at
+     * it directly) and the helper launches and tears it down for you automatically:
+     *
+     * ```sh
+     * curl -sL https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.0/obscura-x86_64-linux.tar.gz | tar xz
+     * ```
+     *
+     * `--allow-private-network` is always passed by this helper (it's required to reach apps running
+     * on `localhost`/private IPs, e.g. a dev server on `127.0.0.1:8000` — Obscura blocks
+     * private-network requests by default).
+     *
+     * ## Config presets
+     *
+     * These are set automatically and only need overriding for unusual setups:
+     *
+     * | 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 |
+     *
+     * `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.
+     *
+     * ## Limitations
+     *
+     * - `input` is always `synthetic`, even on rendering builds — see `input` above.
+     * - No frames, popups, or file uploads.
+     * - On `-no-render` builds and v0.1.x: no screenshots, no visibility assertions
+     *   (`seeElement`/`dontSeeElement` always throw) — only DOM presence
+     *   (`seeElementInDOM`/`dontSeeElementInDOM`) is meaningful without a layout engine.
+     * - On v0.2.0+ default (rendering) builds: layout, screenshots, and CSS work, but it's a new,
+     *   independently implemented rendering/CSS engine — expect edge cases and gaps versus a real browser.
+     * - Single V8 isolate: heavy or long-running pages, or many pages in parallel against one
+     *   `obscura serve` process, compete for the same isolate.
+     *
+     * <!-- configuration -->
+     *
+     * ## Example
+     *
+     * ```js
+     * // inside codecept.conf.js — SELF-LAUNCH mode (recommended): the helper finds/starts/stops
+     * // obscura serve on its own, on a free port. Ideal for run-workers: every worker gets its own
+     * // instance with no config.
+     * {
+     *   helpers: {
+     *     Obscura: {
+     *       url: 'http://localhost',
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * ```js
+     * // ATTACH mode — connect to an Obscura instance you manage yourself (remote host, container, etc.)
+     * {
+     *   helpers: {
+     *     Obscura: {
+     *       url: 'http://localhost',
+     *       endpoint: 'http://127.0.0.1:9222',
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * ## Methods
+     */
+    class Obscura {
+        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(): void;
+        /**
+         * 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(): void;
+        /**
+         * 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.
+         * @returns an absolute or relative path to the binary, or null if none resolved.
+         */
+        protected _resolveBinary(): string | null;
+        /**
+         * Picks a free TCP port on 127.0.0.1 by briefly listening on port 0 and reading back the OS-assigned
+         * port. Used 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(): void;
+        /**
+         * 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(): void;
+    }
     /**
      * ## Configuration
      *