electron-playwright-helpers
Version:
Helper functions for Electron end-to-end testing using Playwright
265 lines • 8.41 kB
TypeScript
import { ElectronApplication } from 'playwright-core';
/**
* A serializable pattern for matching dialog options.
* Strings match exactly (case-sensitive), regex patterns are serialized as {source, flags}.
*/
export type StringMatcher = string | {
source: string;
flags: string;
} | undefined;
/**
* Convert a string or RegExp to a serializable StringMatcher.
* RegExp objects cannot be transferred via Playwright's evaluate(),
* so we serialize them as {source, flags}.
*/
export declare function toSerializableMatcher(pattern: string | RegExp | undefined): StringMatcher;
/**
* Check if a value matches a StringMatcher.
* Used inside app.evaluate() where the matcher is already serialized.
*/
export declare function matchesPattern(value: string | undefined, pattern: StringMatcher): boolean;
/**
* Matchable options for showMessageBox/showMessageBoxSync.
* All properties are optional - only provided properties will be matched.
*/
export type MessageBoxMatcher = {
/** Match against MessageBoxOptions.type ('none' | 'info' | 'error' | 'question' | 'warning') */
type?: string | RegExp;
/** Match against MessageBoxOptions.message */
message?: string | RegExp;
/** Match against MessageBoxOptions.title */
title?: string | RegExp;
/** Match against MessageBoxOptions.detail */
detail?: string | RegExp;
/** Match against MessageBoxOptions.checkboxLabel */
checkboxLabel?: string | RegExp;
/** Match against any button text in MessageBoxOptions.buttons array */
buttons?: string | RegExp;
};
/**
* Matchable options for showOpenDialog/showOpenDialogSync.
*/
export type OpenDialogMatcher = {
/** Match against OpenDialogOptions.title */
title?: string | RegExp;
/** Match against OpenDialogOptions.defaultPath */
defaultPath?: string | RegExp;
/** Match against OpenDialogOptions.buttonLabel */
buttonLabel?: string | RegExp;
/** Match against OpenDialogOptions.message (macOS) */
message?: string | RegExp;
};
/**
* Matchable options for showSaveDialog/showSaveDialogSync.
*/
export type SaveDialogMatcher = {
/** Match against SaveDialogOptions.title */
title?: string | RegExp;
/** Match against SaveDialogOptions.defaultPath */
defaultPath?: string | RegExp;
/** Match against SaveDialogOptions.buttonLabel */
buttonLabel?: string | RegExp;
/** Match against SaveDialogOptions.message (macOS) */
message?: string | RegExp;
/** Match against SaveDialogOptions.nameFieldLabel (macOS) */
nameFieldLabel?: string | RegExp;
};
/**
* Matchable options for showErrorBox.
*/
export type ErrorBoxMatcher = {
/** Match against the title parameter */
title?: string | RegExp;
/** Match against the content parameter */
content?: string | RegExp;
};
/**
* Matchable options for showCertificateTrustDialog.
*/
export type CertificateTrustDialogMatcher = {
/** Match against CertificateTrustDialogOptions.message */
message?: string | RegExp;
};
export type SerializedMessageBoxMatcher = {
type?: StringMatcher;
message?: StringMatcher;
title?: StringMatcher;
detail?: StringMatcher;
checkboxLabel?: StringMatcher;
buttons?: StringMatcher;
};
export type SerializedOpenDialogMatcher = {
title?: StringMatcher;
defaultPath?: StringMatcher;
buttonLabel?: StringMatcher;
message?: StringMatcher;
};
export type SerializedSaveDialogMatcher = {
title?: StringMatcher;
defaultPath?: StringMatcher;
buttonLabel?: StringMatcher;
message?: StringMatcher;
nameFieldLabel?: StringMatcher;
};
export type SerializedErrorBoxMatcher = {
title?: StringMatcher;
content?: StringMatcher;
};
export type SerializedCertificateTrustDialogMatcher = {
message?: StringMatcher;
};
/**
* Return value type for showMessageBox
*/
export type MessageBoxReturnValue = {
response: number;
checkboxChecked: boolean;
};
/**
* Return value type for showOpenDialog
*/
export type OpenDialogReturnValue = {
canceled: boolean;
filePaths: string[];
bookmarks?: string[];
};
/**
* Return value type for showSaveDialog
*/
export type SaveDialogReturnValue = {
canceled: boolean;
filePath?: string;
bookmark?: string;
};
/**
* A matcher stub for showMessageBox.
*/
export type MessageBoxMatcherStub = {
method: 'showMessageBox';
matcher: MessageBoxMatcher;
value: Partial<MessageBoxReturnValue>;
};
/**
* A matcher stub for showMessageBoxSync.
*/
export type MessageBoxSyncMatcherStub = {
method: 'showMessageBoxSync';
matcher: MessageBoxMatcher;
value: number;
};
/**
* A matcher stub for showOpenDialog.
*/
export type OpenDialogMatcherStub = {
method: 'showOpenDialog';
matcher: OpenDialogMatcher;
value: Partial<OpenDialogReturnValue>;
};
/**
* A matcher stub for showOpenDialogSync.
*/
export type OpenDialogSyncMatcherStub = {
method: 'showOpenDialogSync';
matcher: OpenDialogMatcher;
value: string[] | undefined;
};
/**
* A matcher stub for showSaveDialog.
*/
export type SaveDialogMatcherStub = {
method: 'showSaveDialog';
matcher: SaveDialogMatcher;
value: Partial<SaveDialogReturnValue>;
};
/**
* A matcher stub for showSaveDialogSync.
*/
export type SaveDialogSyncMatcherStub = {
method: 'showSaveDialogSync';
matcher: SaveDialogMatcher;
value: string | undefined;
};
/**
* A matcher stub for showErrorBox.
*/
export type ErrorBoxMatcherStub = {
method: 'showErrorBox';
matcher: ErrorBoxMatcher;
value: void;
};
/**
* A matcher stub for showCertificateTrustDialog.
*/
export type CertificateTrustDialogMatcherStub = {
method: 'showCertificateTrustDialog';
matcher: CertificateTrustDialogMatcher;
value: void;
};
/**
* Union type of all dialog matcher stubs.
*/
export type DialogMatcherStub = MessageBoxMatcherStub | MessageBoxSyncMatcherStub | OpenDialogMatcherStub | OpenDialogSyncMatcherStub | SaveDialogMatcherStub | SaveDialogSyncMatcherStub | ErrorBoxMatcherStub | CertificateTrustDialogMatcherStub;
export type StubDialogMatchersOptions = {
/**
* If true, throw an error when a dialog is shown that doesn't match any stub.
* If false (default), return the default value for that dialog method.
*/
throwOnUnmatched?: boolean;
};
/**
* Stub dialog methods with matchers that check dialog options before returning values.
* This allows you to set up multiple different return values based on the dialog's
* title, message, buttons, or other options.
*
* Matchers are checked in order - the first matching stub wins.
* If no stub matches, either an error is thrown (if throwOnUnmatched is true)
* or the default value is returned.
*
* @example
* ```ts
* // Set up multiple dialog stubs at the start of your test
* await stubDialogMatchers(app, [
* {
* method: 'showMessageBox',
* matcher: { title: /delete/i, buttons: /yes/i },
* value: { response: 1 }, // Click "Yes" for delete dialogs
* },
* {
* method: 'showMessageBox',
* matcher: { title: /save/i },
* value: { response: 0 }, // Click "Save" for save dialogs
* },
* {
* method: 'showOpenDialog',
* matcher: { title: 'Select Image' },
* value: { filePaths: ['/path/to/image.png'], canceled: false },
* },
* {
* method: 'showOpenDialog',
* matcher: {}, // Match all other open dialogs
* value: { canceled: true },
* },
* ])
* ```
*
* @category Dialog
*
* @param app - The Playwright ElectronApplication instance.
* @param stubs - Array of dialog matcher stubs to apply.
* @param options - Optional configuration.
* @returns A promise that resolves when the stubs are applied.
*/
export declare function stubDialogMatchers(app: ElectronApplication, stubs: DialogMatcherStub[], options?: StubDialogMatchersOptions): Promise<void>;
/**
* Clear all dialog matcher stubs and restore original dialog methods.
* Note: This requires the app to have stored the original methods,
* which is not done by default. You may need to restart the app
* to fully restore dialog functionality.
*
* @category Dialog
*
* @param app - The Playwright ElectronApplication instance.
* @returns A promise that resolves when the stubs are cleared.
*/
export declare function clearDialogMatchers(app: ElectronApplication): Promise<void>;
//# sourceMappingURL=dialog_matchers.d.ts.map