webdriverio/build/session/context.d.ts

Next-gen browser and mobile automation test framework for Node.js

import type { local } from 'webdriver';
import { SessionManager } from './session.js';
/**
 * Any HTTP command (Classic, Chromium, Appium, Selenium) reaches the session's
 * single focused window/frame, which concurrent tests share. An allowlist fails
 * closed for any command not explicitly vetted. Safe means: does not read or
 * mutate the focused window/frame AND does not change state shared by every
 * concurrent test.
 */
export declare const PARALLEL_SAFE_CLASSIC_COMMANDS: readonly string[];
/**
 * Per-test context override for parallel it() execution.
 *
 * When tests run in parallel (each in its own browsing context), the
 * framework sets a context ID here via `AsyncLocalStorage.run()`.
 * `getCurrentContext()` checks this first, so every command
 * (url, $, click, setValue, getText, etc.) automatically targets
 * the correct browsing context.
 *
 * Outside parallel execution (sequential mode), the store is empty
 * and behavior falls back to the session-global `#currentContext`.
 */
/** Key used to expose the parallel context store on the browser instance. */
export declare const PARALLEL_CONTEXT_STORE_KEY = "__parallelContextStore";
/** Key used to expose the set of framework-managed parallel contexts. */
export declare const PARALLEL_CONTEXTS_KEY = "__parallelContexts";
/**
 * Minimal surface of `AsyncLocalStorage<string>`. The browser bundle must not
 * import `node:async_hooks`, so the Node entry registers the real store.
 */
export interface ParallelContextStore {
    getStore(): string | undefined;
    run<T>(contextId: string, fn: () => T): T;
}
export declare function setParallelContextStore(store: ParallelContextStore): void;
export declare function registerParallelContext(contextId: string): void;
export declare function unregisterParallelContext(contextId: string): void;
export declare function isParallelContext(contextId: string): boolean;
/**
 * Returns the parallel context store. The framework uses this to
 * create per-test scopes:
 *
 *   parallelContextStore.run(contextId, async () => {
 *       await test.fn()  // all commands target contextId
 *   })
 */
export declare function getParallelContextStore(): ParallelContextStore;
export declare function getContextManager(browser: WebdriverIO.Browser): ContextManager;
export type FlatContextTree = Omit<local.BrowsingContextInfo, 'children'> & {
    children: string[];
};
/**
 * This class is responsible for managing context in a WebDriver session. Many BiDi commands
 * require to be executed in a specific context. This class is responsible for keeping track
 * of the current context and providing the current context the user is in.
 */
export declare class ContextManager extends SessionManager {
    #private;
    constructor(browser: WebdriverIO.Browser);
    removeListeners(): void;
    /**
     * set context at the start of the session
     */
    initialize(): Promise<string>;
    /**
     * Set the context that BiDi commands target. In a BiDi session this is a
     * browsing context id (window handle), never an Appium context name, so it
     * does not change the tracked Appium context.
     */
    setCurrentContext(context: string): void;
    getCurrentContext(): Promise<string>;
    /**
     * Browsing context id the emulation commands target. Several BiDi emulation
     * commands reject a call that is not aimed at a top-level traversable, and
     * a child frame id is not one. Resolve the frame the user is in to the
     * top-level context that contains it.
     */
    getCurrentTopLevelContext(): Promise<string>;
    /**
     * Sets the cached current window handle value.
     * @param handle current window handle to set
     */
    setCurrentWindowHandle(handle?: string): void;
    /**
     * Returns the cached window handle.
     *
     * @returns the current window handle, or undefined if the current window is closed.
     */
    getCurrentWindowHandle(): string | undefined;
    get isNativeContext(): boolean;
    get mobileContext(): string | undefined;
    /**
     * Get the flat context tree for the current session
     * @returns a flat list of all contexts in the current session
     */
    getFlatContextTree(): Promise<Record<string, FlatContextTree>>;
    /**
     * Find the parent context of a given context id
     * @param contextId the context id you want to find the parent of
     * @param contexts  the list of contexts to search through returned from `browsingContextGetTree`
     * @returns         the parent context of the context with the given id
     */
    findParentContext(contextId: string, contexts: local.BrowsingContextInfoList): local.BrowsingContextInfo | undefined;
    /**
     * Find a context by URL or ID
     * @param urlOrId     The URL or ID of the context to find
     * @param contexts    The list of contexts to search through returned from `browsingContextGetTree`
     * @param matcherType The type of matcher to use to find the context
     * @returns           The context with the given URL or ID
     */
    findContext(urlOrId: string, contexts: local.BrowsingContextInfoList | null, matcherType: 'byUrl' | 'byUrlContaining' | 'byContextId'): local.BrowsingContextInfo | undefined;
}
//# sourceMappingURL=context.d.ts.map