Puppeteer Navigator

A library to assist some common use cases of Puppeteer.

Features

• Automate as much as possible waiting on elements and actions
  • Automatically wait for all selectors before performing action
  • Set timed wait defaults that will be applied between all actions
  • Attempt to automatically wait for all network activity to complete
• Use simulated clicks for improved reliability in some use cases
  • Simulated clicks will work for elements that are in motion or covered up
• Some simplified API's for convenience

API

/**
 * Options generally applied to all actions
 */
export interface NavigatorOptions {
    /** wait until element is visible on selection actions.  default true. */
    waitUntilVisible?: boolean;
    /** wait until the selector is found before performing actions. default true*/
    waitOnSelectors?: boolean;
    /** wait milliseconds after all actions. default 0 */
    waitAfterAction?: number;
    /** wait milliseconds after all network activity has stopped. default 0 */
    waitIdleTime?: number;
    /** wait milliseconds after any page load. default 0 */
    waitIdleLoadTime?: number;
    /** send click event directly to element vs using mouse cursor initiated click. default true */
    useSimulatedClicks?: boolean;
}
export interface ElementAny extends Element {
    [key: string]: any;
}

export interface Navigator {
    page(): Page
    updateOptions(customOptions:NavigatorOptions) : void
    /**
     * Navigate to URL
     * @param url 
     * @param waitCondition 
     */
    goto(url:string, waitCondition?:SelectorType) : Promise<Response>
    
    /**
     * Queries an element using css selector or xpath
     * Assumes xpath expression starts with '//'
     * @param selector css selector or xpath
     */
    queryElementHandle(selector: string | ElementHandle) : Promise<ElementHandle | null>

    /**
     * Uses the selector function to find a matching element
     * If a context is passed, then the matching element must be a descendant of the context element
     */
    queryElementHandleWithFn(selectorFn: ElementMatchFn, context: ElementHandle) : Promise<Node | null>

    /**
     * Query element using selector and uses the provided function to map a return value
     * @param selector css selector
     * @param valueMapFn function to map element to return value
     */
    queryElement(selector:string, valueMapFn:ElementMapFn) : Promise<any[]> 

    /**
     * Queries elements using selector and uses the provided function to map a list of return values
     * @param selector css selector
     * @param valueMapFn function to map elements to values to be returned
     */
    queryElements(selector:string, valueMapFn:ElementMapFn): Promise<any[]> 
    
    /**
     * Queries chlldren with all descendants for a match using the descendantFn.
     * Retuns all children who matched or had a descendant match.
     * 
     * This API is used to assist identifying rows in tables, lists, grids etc where we 
     * want to find a row containing some criteria we can test for with a function
     * 
     * @param selector css selector
     * @param valueMapFn function to map elements to values to be returned
     */
    queryChildrenAsHandles(parentSelector:string, descendantFn: (element:Element) => boolean ) : Promise<ElementHandle<Element>[]>


    /**
     * Sets the default chrome puppeteer download path
     * See - https://github.com/GoogleChrome/puppeteer/issues/299
     * @param {*} downloadPath 
     */
    setDownloadPath(downloadPath:string) : Promise<void>
    scrollElementToBottom(elementSelector:string, delay:number) : Promise<void>

    /**
     * Waits for element to be visible, function to be true or timeout if number
     * @param condition css selector, xpath or function
     */
    wait(condition:SelectorType) : Promise<JSHandle | void>

    /**
     * Waits for condition to be true
     * @param selector css selector, xpath or function
     * @param condition function that receives element of selector as input.
     * @param options 'waitAfter' additinoal wait time after condition is true
     */
    waitFn(selector:string, condition: (element:ElementAny) => boolean, options?: PageFnOptions & {waitAfter?:number}) : Promise<void>

    /**
     * Wait for any network activity to complete
     */
    waitActivity(idleTime:number|undefined, idleLoadTime:number|undefined) : Promise<unknown>

    /**
     * Performs a click on a HTML field.
     * @param selector css selector or xpath
     * @param clickOptions ClickOptions
     */
    click(selector:string | ElementHandle, clickOptions?:ClickOptions) : Promise<void>

    /**
     * Types text into a HTML field
     * @param selector css selector
     * @param text type text into field
     * @param typeOptions 'delay' sets delay between each key typed
     */
    type(selector:string, text:string, typeOptions?: { delay: number }) : Promise<void>

    /**
     * Selects an option within a HTML list.
     * Filters out any control characters that might be in the list label or value before attempting to match.
     * 
     * @param selector css selector
     * @param selectOption 'value' matches the option value attribute. 'label' matches the option label attribute
     */
    select(selector:string, selectOption: {value?:string, label?:string}) : Promise<void>


    /**
     * Find a frame and return a new navigator for the frame
     * @param selector frame selector
     */
    frameNavigator(selector:string) : Promise<Navigator>
 
}