electron-playwright-helpers/dist/window_helpers.d.ts

Helper functions for Electron end-to-end testing using Playwright

import type { ElectronApplication, Page } from 'playwright-core';
import { RetryOptions } from './utilities';
/**
 * A function that evaluates a Page and returns whether it matches.
 */
export type WindowMatcher = (page: Page) => boolean | Promise<boolean>;
/**
 * Options for waiting for a window.
 */
export interface WaitForWindowOptions extends Partial<RetryOptions> {
    /** Timeout in ms (default: 10000) */
    timeout?: number;
    /** Polling interval in ms (default: 200) */
    interval?: number;
}
/**
 * Get the first window whose URL matches the given pattern.
 *
 * @category Window Helpers
 *
 * @param electronApp - The Playwright ElectronApplication
 * @param pattern - A string (substring match) or RegExp to match against the URL
 * @param options - Optional RetryOptions
 * @returns The first matching Page, or undefined if no match found
 *
 * @example
 * ```ts
 * const settingsWindow = await getWindowByUrl(app, '/settings')
 * const authWindow = await getWindowByUrl(app, /auth|login/)
 * ```
 */
export declare function getWindowByUrl(electronApp: ElectronApplication, pattern: string | RegExp, options?: Partial<RetryOptions>): Promise<Page | undefined>;
/**
 * Get all windows whose URL matches the given pattern.
 *
 * @category Window Helpers
 *
 * @param electronApp - The Playwright ElectronApplication
 * @param pattern - A string (substring match) or RegExp to match against the URL
 * @param options - Options with `all: true` to return all matches
 * @returns An array of matching Pages
 *
 * @example
 * ```ts
 * const allSettingsWindows = await getWindowByUrl(app, '/settings', { all: true })
 * ```
 */
export declare function getWindowByUrl(electronApp: ElectronApplication, pattern: string | RegExp, options: Partial<RetryOptions> & {
    all: true;
}): Promise<Page[]>;
/**
 * Get the first window whose title matches the given pattern.
 *
 * @category Window Helpers
 *
 * @param electronApp - The Playwright ElectronApplication
 * @param pattern - A string (substring match) or RegExp to match against the title
 * @param options - Optional RetryOptions
 * @returns The first matching Page, or undefined if no match found
 *
 * @example
 * ```ts
 * const prefsWindow = await getWindowByTitle(app, 'Preferences')
 * const windowN = await getWindowByTitle(app, /Window \d+/)
 * ```
 */
export declare function getWindowByTitle(electronApp: ElectronApplication, pattern: string | RegExp, options?: Partial<RetryOptions>): Promise<Page | undefined>;
/**
 * Get all windows whose title matches the given pattern.
 *
 * @category Window Helpers
 *
 * @param electronApp - The Playwright ElectronApplication
 * @param pattern - A string (substring match) or RegExp to match against the title
 * @param options - Options with `all: true` to return all matches
 * @returns An array of matching Pages
 *
 * @example
 * ```ts
 * const allNumberedWindows = await getWindowByTitle(app, /Window \d+/, { all: true })
 * ```
 */
export declare function getWindowByTitle(electronApp: ElectronApplication, pattern: string | RegExp, options: Partial<RetryOptions> & {
    all: true;
}): Promise<Page[]>;
/**
 * Get the first window that matches the provided matcher function.
 *
 * @category Window Helpers
 *
 * @param electronApp - The Playwright ElectronApplication
 * @param matcher - A function that receives a Page and returns true if it matches
 * @param options - Optional RetryOptions
 * @returns The first matching Page, or undefined if no match found
 *
 * @example
 * ```ts
 * const largeWindow = await getWindowByMatcher(app, async (page) => {
 *   const size = await page.viewportSize()
 *   return size && size.width > 1000
 * })
 * ```
 */
export declare function getWindowByMatcher(electronApp: ElectronApplication, matcher: WindowMatcher, options?: Partial<RetryOptions>): Promise<Page | undefined>;
/**
 * Get all windows that match the provided matcher function.
 *
 * @category Window Helpers
 *
 * @param electronApp - The Playwright ElectronApplication
 * @param matcher - A function that receives a Page and returns true if it matches
 * @param options - Options with `all: true` to return all matches
 * @returns An array of matching Pages
 *
 * @example
 * ```ts
 * const allLargeWindows = await getWindowByMatcher(app, async (page) => {
 *   const size = await page.viewportSize()
 *   return size && size.width > 1000
 * }, { all: true })
 * ```
 */
export declare function getWindowByMatcher(electronApp: ElectronApplication, matcher: WindowMatcher, options: Partial<RetryOptions> & {
    all: true;
}): Promise<Page[]>;
/**
 * Wait for a window whose URL matches the given pattern.
 *
 * This function checks existing windows first, then listens for new windows.
 * It uses polling to handle windows that may have their URL change after opening.
 *
 * @category Window Helpers
 *
 * @param electronApp - The Playwright ElectronApplication
 * @param pattern - A string (substring match) or RegExp to match against the URL
 * @param options - Optional timeout and interval settings
 * @returns The matching Page
 * @throws Error if timeout is reached before a matching window is found
 *
 * @example
 * ```ts
 * // Click something that opens a new window, then wait for it
 * await page.click('#open-settings')
 * const settingsWindow = await waitForWindowByUrl(app, '/settings', { timeout: 5000 })
 * ```
 */
export declare function waitForWindowByUrl(electronApp: ElectronApplication, pattern: string | RegExp, options?: WaitForWindowOptions): Promise<Page>;
/**
 * Wait for a window whose title matches the given pattern.
 *
 * This function checks existing windows first, then listens for new windows.
 * It uses polling to handle windows that may have their title change after opening.
 *
 * @category Window Helpers
 *
 * @param electronApp - The Playwright ElectronApplication
 * @param pattern - A string (substring match) or RegExp to match against the title
 * @param options - Optional timeout and interval settings
 * @returns The matching Page
 * @throws Error if timeout is reached before a matching window is found
 *
 * @example
 * ```ts
 * // Wait for a window with a specific title to appear
 * const prefsWindow = await waitForWindowByTitle(app, 'Preferences', { timeout: 5000 })
 * ```
 */
export declare function waitForWindowByTitle(electronApp: ElectronApplication, pattern: string | RegExp, options?: WaitForWindowOptions): Promise<Page>;
/**
 * Wait for a window that matches the provided matcher function.
 *
 * This function:
 * 1. Checks existing windows first
 * 2. Listens for new window events
 * 3. Polls existing windows periodically (to catch URL/title changes)
 *
 * @category Window Helpers
 *
 * @param electronApp - The Playwright ElectronApplication
 * @param matcher - A function that receives a Page and returns true if it matches
 * @param options - Optional timeout and interval settings
 * @returns The matching Page
 * @throws Error if timeout is reached before a matching window is found
 *
 * @example
 * ```ts
 * const window = await waitForWindowByMatcher(app, async (page) => {
 *   const title = await page.title()
 *   return title.startsWith('Document:')
 * }, { timeout: 10000 })
 * ```
 */
export declare function waitForWindowByMatcher(electronApp: ElectronApplication, matcher: WindowMatcher, options?: WaitForWindowOptions): Promise<Page>;
//# sourceMappingURL=window_helpers.d.ts.map