browser-automator
Version:
Puppeteer alternative for Chrome extensions. A module for Chrome extensions that functions similarly to Puppeteer.
375 lines (374 loc) • 17.9 kB
TypeScript
import Browser from './browser';
import RemoteElement from './element';
import { PageConfigurations } from './others';
/**
* Represents a Page instance for interacting with Chrome browser pages.
*/
export default class Page {
/**
* @type {Browser} - The Browser instance associated with this Page instance.
**/
browser: Browser;
/**
* @type {number} - The ID of the Chrome tab.
*/
tabId: number;
/**
* @type {number} - The ID of the Chrome window.
*/
windowId: number;
/**
* @type {number} - The ID of the tab's origin window. If supplied the tab will be moved in that window when closing the browser-automator instance instead of closing the tab.
*/
originWindowId: number;
/**
* @type {number} - Whether the page/tab should be active in the origin window when moved to the origin window.
*/
activeInOrigin: number;
/**
* @type {Function} - Callback function to be executed before closing the page.
*/
onBeforeClose?: Function;
/**
* @type {Object} - Represents the configurations for the Page instance.
*/
configurations: PageConfigurations;
/**
* Function to be called when the Page instance encounters a glitch.
*/
handleGlitch(glitch: any): Promise<string>;
/**
* Configures the Page instance with the specified configurations.
*
* @param {Object} configurations - An object represents configurations for the Page instance.
* @param {number} [configurations.tryLimit] - The maximum number of attempts for waiting operations.
* @param {number} [configurations.delay] - The delay between attempts in milliseconds.
* @param {boolean} [configurations.scrollToElementBeforeAction] - Scroll to the element before an action (`click`, `execPaste`, `triggerEvent`, `input`, `uploadFiles`).
* @param {Object} [configurations.scrollIntoViewOptions] - Options for the `scrollIntoView` method to scroll to elements.
*/
configure(configurations: Partial<PageConfigurations>): void;
/**
* Creates a new Page instance for a specific Chrome tab with the given tabId and windowId.
*
* @param {{ tabId: number; windowId: number }} options - An object containing tabId and windowId properties.
* @param {number} options.tabId - The unique identifier of the Chrome tab associated with this Page instance.
* @param {number} options.windowId - The unique identifier of the Chrome window containing the tab.
* @param {number} options.originWindowId - The ID of the tab's origin window. If supplied the tab will be moved in that window when closing the browser-automator instance instead of closing the tab.
* @param {number} options.activeInOrigin - Whether the page/tab should be active in the origin window when moved to the origin window.
*/
constructor({ tabId, windowId, originWindowId, activeInOrigin, browser }: {
tabId: number;
windowId: number;
originWindowId?: number;
activeInOrigin?: number;
browser: Browser;
});
/**
* Navigate to the specified URL.
*
* @param {string} url - The URL to navigate to.
* @param {object} [options] - Navigation options.
* @param {string} [options.waitUntil='domcontentloaded'] - When to consider navigation as complete ('load' or 'domcontentloaded').
* @returns {Promise<void>} - Resolves when the navigation is complete.
*/
goto(url: string, { waitUntil }?: {
waitUntil?: 'load' | 'domcontentloaded' | 'bodyloaded';
}): Promise<void>;
/**
* Reloads the current page.
*
* @returns A promise that resolves when the page is reloaded.
*/
reload(): Promise<void>;
/**
* Get the current URL of the page.
*
* @returns A promise that resolves to the current URL as a string.
*/
url(): Promise<string>;
/**
* Close the current page.
*
* @returns A promise that resolves when the page is closed.
*/
close(): Promise<void>;
/**
* Zoom the current page.
*
* @param {number} zoomFactor - The new zoom factor. Use a value of 0 here to set the tab to its current default zoom factor. Values greater than zero specify a (possibly non-default) zoom factor for the tab.
* @returns A promise that resolves when the zoom is applied.
*/
zoom(zoomFactor: number): Promise<void>;
/**
* Brings the Chrome browser window associated with the page to the front.
*
* @returns A promise that resolves when the window is brought to the front.
*/
bringToFront(): Promise<void>;
/**
* Hides the Chrome browser window associated with the page.
*
* @returns A promise that resolves when the window is hidden.
*/
hideFromFront(): Promise<void>;
/**
* Evaluates a function on the page.
*
* @param {Function} func - The function to evaluate.
* @param {any[]} [args] - Arguments to pass to the function.
* @param {Object} [options] - Optional evaluation options.
* @param {'ISOLATED' | 'MAIN'} [options.world] - The world context for evaluation (default is 'MAIN').
* @param {boolean} [options.allFrames] - Indicates whether to evaluate in all frames (default is false).
* @param {number[]} [options.frameIds] - An array of frame identifiers where the evaluation should take place.
* @param {string[]} [options.documentIds] - An array of document identifiers for the frames to evaluate in.
* @returns {Promise<any>} - The result of the evaluation.
*/
evaluate<T extends (...args: any[]) => any>(func: T, args: Parameters<T>, options?: {
world?: 'ISOLATED' | 'MAIN';
allFrames?: boolean;
frameIds?: number[];
documentIds?: string[];
}): Promise<ReturnType<T>>;
/**
* Evaluates a function on the page.
*
* @param {Function} func - The function to evaluate.
* @param {Object} [options] - Optional evaluation options.
* @param {'ISOLATED' | 'MAIN'} [options.world] - The world context for evaluation (default is 'MAIN').
* @param {boolean} [options.allFrames] - Indicates whether to evaluate in all frames (default is false).
* @param {number[]} [options.frameIds] - An array of frame identifiers where the evaluation should take place.
* @param {string[]} [options.documentIds] - An array of document identifiers for the frames to evaluate in.
* @returns {Promise<any>} - The result of the evaluation.
*/
evaluate<T extends () => any>(func: T, options?: {
world?: 'ISOLATED' | 'MAIN';
allFrames?: boolean;
frameIds?: number[];
documentIds?: string[];
}): Promise<ReturnType<T>>;
/**
* Evaluates JavaScript function on the page.
*
* @param {Object} options - An object specifying evaluation options.
* @param {Function} [options.func] - The function to evaluate.
* @param {any[]} [options.args] - Arguments to pass to the evaluated function.
* @param {'ISOLATED' | 'MAIN'} [options.world] - The world context for evaluation (default is 'MAIN').
* @param {boolean} [options.allFrames] - Indicates whether to evaluate in all frames (default is false).
* @param {number[]} [options.frameIds] - An array of frame identifiers where the evaluation should take place.
* @param {string[]} [options.documentIds] - An array of document identifiers for the frames to evaluate in.
* @returns {Promise<any>} - The result of the evaluation.
*/
evaluate<T extends (...args: any[]) => any>(options: {
func: T;
args?: Parameters<T>;
world?: 'ISOLATED' | 'MAIN';
allFrames?: boolean;
frameIds?: number[];
documentIds?: string[];
}): Promise<ReturnType<T>>;
/**
* Evaluates JS files on the page.
*
* @param {string[]} files - An array of script file paths to evaluate.
* @param {Object} [options] - Optional evaluation options.
* @param {'ISOLATED' | 'MAIN'} [options.world] - The world context for evaluation (default is 'MAIN').
* @param {boolean} [options.allFrames] - Indicates whether to evaluate in all frames (default is false).
* @param {number[]} [options.frameIds] - An array of frame identifiers where the evaluation should take place.
* @param {string[]} [options.documentIds] - An array of document identifiers for the frames to evaluate in.
* @returns {Promise<any>} - The result of the evaluation.
*/
evaluate(files: string[], options?: {
world?: 'ISOLATED' | 'MAIN';
allFrames?: boolean;
frameIds?: number[];
documentIds?: string[];
}): Promise<any>;
/**
* Waits for a function to return a truthy value.
*
* @param {Function} func - The function representing the condition to wait for.
* @param {any[]} args - Arguments to pass to the function.
* @param {Object} [options] - Optional wait options.
* @param {number} [options.tryLimit] - The maximum number of attempts to wait for the condition (default is this.tryLimit).
* @param {number} [options.delay] - The delay in milliseconds between attempts (default is this.delay).
* @returns {Promise<any>} - The result of the evaluated condition.
*/
waitFor(func: Function, args: any[], options?: {
tryLimit?: number;
delay?: number;
}): Promise<any>;
/**
* Waits for the page to navigate to a new URL.
*
* @param {Object} [options] - An object specifying waiting options.
* @param {number} [options.tryLimit] - The maximum number of attempts to wait for navigation (default is 50).
* @param {number} [options.delay] - The delay between each attempt in milliseconds (default is 750).
* @returns {Promise<void>}
*/
waitForNavigation(options?: {
tryLimit?: number;
delay?: number;
}): Promise<void>;
/**
* Waits for an element matching the given CSS selector to become available.
*
* @param {string} selectors - The CSS selector to wait for.
* @param {Object} [options] - Optional wait options.
* @param {number} [options.tryLimit] - The maximum number of attempts to find the element (default is 1000).
* @param {number} [options.delay] - The delay between attempts in milliseconds (default is 750).
* @param {number} [index = -1] - The index of the element if multiple elements match the selector.
* @returns {Promise<void>}
*/
waitForSelector(selectors: string, options?: {
tryLimit?: number;
delay?: number;
}, index?: number): Promise<void>;
/**
* Waits for an element matching the given XPath expression to appear in the page.
*
* @param {any} expression - The XPath expression to wait for.
* @param {{ tryLimit?: number; delay?: number }} [options] - Optional waiting options.
* @param {number} [options.tryLimit] - The maximum number of attempts to find the element (default is 1000).
* @param {number} [options.delay] - The delay in milliseconds between attempts (default is 750ms).
* @param {number} [index] - The index of the element to interact with.
* @returns {Promise<void>}
*/
waitForXPath(expression: string, options?: {
tryLimit?: number;
delay?: number;
}, index?: number): Promise<void>;
/**
* Waits for an element matching the given CSS Selectors or XPath expression to become available and returns the RemoteElement.
*
* @param {string} selectors - The CSS Selectors or XPath expression of the element to wait for.
* @param {Object} [options] - Optional options for waiting.
* @param {number} [options.tryLimit] - The maximum number of attempts (default is 1000).
* @param {number} [options.delay] - The delay in milliseconds between attempts (default is 750ms).
* @param {number} [index = -1] - The index of the element if there are multiple matches.
* @returns {Promise<RemoteElement>}
*/
waitForElement(selectors: string, options?: {
tryLimit?: number;
delay?: number;
}, index?: number): Promise<RemoteElement | undefined>;
/**
* Waits for an element matching the given XPath expression or CSS Selectors to disappear from the page.
*
* @param {string} selectors - The CSS Selectors or XPath expression to check for element absence.
* @param {Object} [options] - Optional options for waiting.
* @param {number} [options.tryLimit] - The maximum number of attempts (default is 1000).
* @param {number} [options.delay] - The delay in milliseconds between attempts (default is 750ms).
* @param {number} [index = -1] - The index of the element if there are multiple matches.
* @returns {Promise<boolean>}
*/
waitForElementMiss(selectors: string, options?: {
tryLimit?: number;
delay?: number;
}, index?: number): Promise<boolean>;
/**
* Gets element as RemoteElement for the given XPath expression or CSS Selectors. It doesn't check if the existance of the element.
* @param {string} selectors - The CSS selector or XPath expression.
* @param {number} index - The index of the element to check.
* @returns {RemoteElement}
*/
element(selectors: string, index?: number): RemoteElement;
/**
* Gets element as RemoteElement matching the given XPath expression or CSS Selectors.
*
* @param {string} selectors - The CSS selector or XPath expression.
* @param {number} index - The index of the element to check.
* @returns {Promise<RemoteElement>}
*/
getElement(selectors: string, index?: number, context?: string): Promise<RemoteElement | undefined>;
/**
* Gets all the elements as RemoteElement[] matching the given XPath expression or CSS Selectors.
*
* @param {string} selectors - The CSS selector or XPath expression.
* @returns {Promise<RemoteElement[]>}
*/
getElements(selectors: string, context?: string): Promise<RemoteElement[] | undefined>;
/**
* Checks if an element specified by the CSS selector or XPath expression exists on the page.
*
* @param {string} selectors - The CSS selector or XPath expression to check for existence.
* @param {number} index - The index of the element to check.
* @returns {Promise<boolean>}
*/
elementExists(selectors: string, index?: number): Promise<boolean>;
/**
* Clicks on the element specified by the CSS selector or XPath expression.
*
* @param {string} selectors - The CSS selector or XPath expression to click on.
* @param {number} index - The index of the element to interact with.
* @returns {Promise<void>}
*/
click(selectors: string, index?: number): Promise<void>;
/**
* Copies text to the clipboard.
*
* @param {string} text - The text to copy to the clipboard.
*/
execCopy(text: string): void;
/**
* Pastes text from the clipboard to an element specified by the CSS selector or XPath expression.
*
* @param {string} selectors - The CSS selector or XPath expression of the target element.
* @param {number} index - The index of the element to interact with (default is -1).
* @returns {Promise<void>}
*/
execPasteTo(selectors: string, index?: number): Promise<void>;
/**
* Triggers an event on the element specified by the CSS selector or XPath expression.
*
* @param {string} selectors - The CSS selector or XPath expression of the target element.
* @param {string} type - The type of event to trigger.
* @param {number} index - The index of the element to interact with.
* @returns {Promise<void>}
*/
triggerEvent(selectors: string, type: 'click' | 'input' | 'submit' | 'keydown' | 'keyup' | 'keypress' | 'change' | 'mouseover' | 'mouseout' | 'focus' | 'blur' | 'load' | string, index?: number): Promise<void>;
/**
* Inputs a value into the element specified by the CSS selector or XPath expression.
*
* @param {string} selectors - The CSS selector or XPath expression of the target element.
* @param {any} value - The value to input.
* @param {number} index - The index of the element to interact with.
* @returns {Promise<void>}
*/
input(selectors: string, value: any, index?: number): Promise<void>;
/**
* Uploads files to an input element specified by the CSS selector or XPath expression.
*
* @param {string} selectors - The CSS selector or XPath expression of the input element.
* @param {(File | { name: string, blob: Blob, dataUrl?: string, blobUrl?: string })[]} files - An array of files to upload, where each file can be a File object or an object with name, blob, dataUrl, and blobUrl properties.
* @param {number} caughtElementIndex - The index of the element to interact with (default is -1).
* @returns {Promise<void>}
*/
uploadFiles(selectors: string, files: (File | {
name: string;
blob: Blob;
dataUrl?: string;
blobUrl?: string;
} | any)[], caughtElementIndex: number): Promise<void>;
/**
* Takes a screenshot of the visible area of the page.
*
* @param {{ clip?: { x: number; y: number; width: number; height: number }}} options - Optional clipping parameters.
* @returns {Promise<string>} - The data URL of the screenshot.
*/
screenshot({ clip }: {
clip?: {
x: number;
y: number;
width: number;
height: number;
};
}): Promise<string>;
elementCatcher: {
catch: (tagNames: string[]) => Promise<void>;
terminate: () => Promise<void>;
};
manualClick: {
enable: () => Promise<void>;
disable: () => Promise<void>;
};
}