feat: getElement function (#163)

Author: bvandercar-vt

README.md

@@ -115,7 +115,7 @@ Toggles random mouse movements on or off.
 Simulates a mouse click at the specified selector or element.
 
 - **selector (optional):** CSS selector or ElementHandle to identify the target element.
-- **options (optional):** Additional options for clicking. **Extends the `options` of the `move` and `scrollIntoView` functions (below)**
+- **options (optional):** Additional options for clicking. **Extends the `options` of the `move`, `scrollIntoView`, and `getElement` functions (below)**
   - `hesitate (number):` Delay before initiating the click action in milliseconds. Default is `0`.
   - `waitForClick (number):` Delay between mousedown and mouseup in milliseconds. Default is `0`.
   - `moveDelay (number):` Delay after moving the mouse in milliseconds. Default is `2000`. If `randomizeMoveDelay=true`, delay is randomized from 0 to `moveDelay`.
@@ -125,10 +125,9 @@ Simulates a mouse click at the specified selector or element.
 Moves the mouse to the specified selector or element.
 
 - **selector:** CSS selector or ElementHandle to identify the target element.
-- **options (optional):** Additional options for moving. **Extends the `options` of the `scrollIntoView` function (below)**
+- **options (optional):** Additional options for moving. **Extends the `options` of the `scrollIntoView` and `getElement` functions (below)**
   - `paddingPercentage (number):` Percentage of padding to be added inside the element when determining the target point. Default is `0` (may move to anywhere within the element). `100` will always move to center of element.
   - `destination (Vector):` Destination to move the cursor to, relative to the top-left corner of the element. If specified, `paddingPercentage` is not used. If not specified (default), destination is random point within the `paddingPercentage`.
-  - `waitForSelector (number):` Time to wait for the selector to appear in milliseconds. Default is to not wait for selector.
   - `moveDelay (number):` Delay after moving the mouse in milliseconds. Default is `0`. If `randomizeMoveDelay=true`, delay is randomized from 0 to `moveDelay`.
   - `randomizeMoveDelay (boolean):` Randomize delay between actions from `0` to `moveDelay`. Default is `true`.
   - `maxTries (number):` Maximum number of attempts to mouse-over the element. Default is `10`.
@@ -145,16 +144,24 @@ Moves the mouse to the specified destination point.
   - `moveDelay (number):` Delay after moving the mouse in milliseconds. Default is `0`. If `randomizeMoveDelay=true`, delay is randomized from 0 to `moveDelay`.
   - `randomizeMoveDelay (boolean):` Randomize delay between actions from `0` to `moveDelay`. Default is `true`.
 
-#### `scrollIntoView(element: ElementHandle, options?: ScrollOptions) => Promise<void>`
+#### `scrollIntoView(selector: string | ElementHandle, options?: ScrollOptions) => Promise<void>`
 
 Scrolls the element into view. If already in view, no scroll occurs.
 
-- **element:** ElementHandle to identify the target element.
-- **options (optional):** Additional options for scrolling.
+- **selector:** CSS selector or ElementHandle to identify the target element.
+- **options (optional):** Additional options for scrolling. **Extends the `options` of the `getElement` function (below)**
   - `scrollSpeed (number):` Scroll speed (when scrolling occurs). 0 to 100. 100 is instant. Default is `100`.
   - `scrollDelay (number):` Time to wait after scrolling (when scrolling occurs). Default is `200`.
   - `inViewportMargin (number):` Margin (in px) to add around the element when ensuring it is in the viewport. Default is `0`.
 
+#### `getElement(selector: string | ElementHandle, options?: GetElementOptions) => Promise<void>`
+
+Gets the element via a selector. Can use an XPath.
+
+- **selector:** CSS selector or ElementHandle to identify the target element.
+- **options (optional):** Additional options.
+  - `waitForSelector (number):` Time to wait for the selector to appear in milliseconds. Default is to not wait for selector.
+
 #### `getLocation(): Vector`
 
 Get current location of the cursor.

src/spoof.ts

@@ -35,7 +35,15 @@ export interface BoxOptions {
   readonly destination?: Vector
 }
 
-export interface ScrollOptions {
+export interface GetElementOptions {
+  /**
+   * Time to wait for the selector to appear in milliseconds.
+   * Default is to not wait for selector.
+   */
+  readonly waitForSelector?: number
+}
+
+export interface ScrollOptions extends GetElementOptions {
   /**
    * Scroll speed (when scrolling occurs). 0 to 100. 100 is instant.
    * @default 100
@@ -55,11 +63,6 @@ export interface ScrollOptions {
 }
 
 export interface MoveOptions extends BoxOptions, ScrollOptions, Pick<PathOptions, 'moveSpeed'> {
-  /**
-   * Time to wait for the selector to appear in milliseconds.
-   * Default is to not wait for selector.
-   */
-  readonly waitForSelector?: number
   /**
    * Delay after moving the mouse in milliseconds. If `randomizeMoveDelay=true`, delay is randomized from 0 to `moveDelay`.
    * @default 0
@@ -141,8 +144,15 @@ export interface GhostCursor {
     selector: string | ElementHandle,
     options?: MoveOptions
   ) => Promise<void>
-  moveTo: (destination: Vector, options?: MoveToOptions) => Promise<void>
-  scrollIntoView: (selector: ElementHandle, options?: ScrollOptions) => Promise<void>
+  moveTo: (
+    destination: Vector,
+    options?: MoveToOptions) => Promise<void>
+  scrollIntoView: (
+    selector: string | ElementHandle,
+    options?: ScrollOptions) => Promise<void>
+  getElement: (
+    selector: string | ElementHandle,
+    options?: GetElementOptions) => Promise<ElementHandle<Element>>
   getLocation: () => Vector
 }
 
@@ -378,6 +388,16 @@ export const createCursor = (
      * @default ClickOptions
      */
     click?: ClickOptions
+    /**
+    * Default options for the `scrollIntoView` function
+    * @default ScrollOptions
+    */
+    scrollIntoView?: ScrollOptions
+    /**
+     * Default options for the `getElement` function
+     * @default GetElementOptions
+     */
+    getElement?: GetElementOptions
   } = {}
 ): GhostCursor => {
   // this is kind of arbitrary, not a big fan but it seems to work
@@ -521,34 +541,8 @@ export const createCursor = (
         }
 
         actions.toggleRandomMove(false)
-        let elem: ElementHandle<Element> | null = null
-        if (typeof selector === 'string') {
-          if (selector.startsWith('//') || selector.startsWith('(//')) {
-            selector = `xpath/.${selector}`
-            if (optionsResolved.waitForSelector !== undefined) {
-              await page.waitForSelector(selector, {
-                timeout: optionsResolved.waitForSelector
-              })
-            }
-            const [handle] = await page.$$(selector)
-            elem = handle.asElement() as ElementHandle<Element>
-          } else {
-            if (optionsResolved.waitForSelector !== undefined) {
-              await page.waitForSelector(selector, {
-                timeout: optionsResolved.waitForSelector
-              })
-            }
-            elem = await page.$(selector)
-          }
-          if (elem === null) {
-            throw new Error(
-              `Could not find element with selector "${selector}", make sure you're waiting for the elements by specifying "waitForSelector"`
-            )
-          }
-        } else {
-          // ElementHandle
-          elem = selector
-        }
+
+        const elem = await this.getElement(selector, optionsResolved)
 
         // Make sure the object is in view
         await this.scrollIntoView(elem, optionsResolved)
@@ -615,14 +609,17 @@ export const createCursor = (
       await delay(optionsResolved.moveDelay * (optionsResolved.randomizeMoveDelay ? Math.random() : 1))
     },
 
-    async scrollIntoView (elem: ElementHandle, options?: ScrollOptions): Promise<void> {
+    async scrollIntoView (selector: string | ElementHandle, options?: ScrollOptions): Promise<void> {
       const optionsResolved = {
         scrollSpeed: 100,
         scrollDelay: 200,
         inViewportMargin: 0,
+        ...defaultOptions?.scrollIntoView,
         ...options
       } satisfies ScrollOptions
 
+      const elem = await this.getElement(selector, optionsResolved)
+
       const {
         viewportWidth,
         viewportHeight,
@@ -679,9 +676,9 @@ export const createCursor = (
       const { top, left, bottom, right } = targetBox
 
       const isInViewport = top >= 0 &&
-          left >= 0 &&
-          bottom <= viewportHeight &&
-          right <= viewportWidth
+        left >= 0 &&
+        bottom <= viewportHeight &&
+        right <= viewportWidth
 
       if (isInViewport) return
 
@@ -771,6 +768,39 @@ export const createCursor = (
       }
 
       await delay(optionsResolved.scrollDelay)
+    },
+
+    async getElement (selector: string | ElementHandle, options?: GetElementOptions): Promise<ElementHandle<Element>> {
+      const optionsResolved = {
+        ...defaultOptions?.getElement,
+        ...options
+      } satisfies GetElementOptions
+
+      let elem: ElementHandle<Element> | null = null
+      if (typeof selector === 'string') {
+        if (selector.startsWith('//') || selector.startsWith('(//')) {
+          selector = `xpath/.${selector}`
+          if (optionsResolved.waitForSelector !== undefined) {
+            await page.waitForSelector(selector, { timeout: optionsResolved.waitForSelector })
+          }
+          const [handle] = await page.$$(selector)
+          elem = handle.asElement() as ElementHandle<Element> | null
+        } else {
+          if (optionsResolved.waitForSelector !== undefined) {
+            await page.waitForSelector(selector, { timeout: optionsResolved.waitForSelector })
+          }
+          elem = await page.$(selector)
+        }
+        if (elem === null) {
+          throw new Error(
+            `Could not find element with selector "${selector}", make sure you're waiting for the elements by specifying "waitForSelector"`
+          )
+        }
+      } else {
+        // ElementHandle
+        elem = selector
+      }
+      return elem
     }
   }