Merge branch 'master' into path

Author: regseb

src/math.ts

@@ -22,7 +22,6 @@ export const mult = (a: Vector, b: number): Vector => ({ x: a.x * b, y: a.y * b
 export const add = (a: Vector, b: Vector): Vector => ({ x: a.x + b.x, y: a.y + b.y })
 
 export const extrapolate = (a: Vector, b: Vector): Vector => add(b, sub(b, a))
-
 export const scale = (value: number, range1: [number, number], range2: [number, number]): number =>
   (value - range1[0]) * (range2[1] - range2[0]) / (range1[1] - range1[0]) + range2[0]
 

src/spoof.ts

@@ -51,9 +51,9 @@ export interface ScrollOptions {
    */
   readonly scrollSpeed?: number
   /**
- * Time to wait after scrolling.
- * @default 200
- */
+   * Time to wait after scrolling.
+   * @default 200
+   */
   readonly scrollDelay?: number
 }
 
@@ -142,36 +142,44 @@ export interface MoveToOptions extends PathOptions, Pick<MoveOptions, 'moveDelay
 export type ScrollToDestination = Partial<Vector> | 'top' | 'bottom' | 'left' | 'right'
 
 export interface GhostCursor {
+  /** Toggles random mouse movements on or off. */
   toggleRandomMove: (random: boolean) => void
+  /** Simulates a mouse click at the specified selector or element. */
   click: (
     selector?: string | ElementHandle,
     options?: ClickOptions
   ) => Promise<void>
+  /** Moves the mouse to the specified selector or element. */
   move: (
     selector: string | ElementHandle,
     options?: MoveOptions
   ) => Promise<void>
+  /** Moves the mouse to the specified destination point. */
   moveTo: (
     destination: Vector,
     options?: MoveToOptions) => Promise<void>
+  /** Scrolls the element into view. If already in view, no scroll occurs. */
   scrollIntoView: (
     selector: ElementHandle,
     options?: ScrollIntoViewOptions) => Promise<void>
+  /** Scrolls to the specified destination point. */
   scrollTo: (
     destination: ScrollToDestination,
     options?: ScrollOptions) => Promise<void>
+  /** Scrolls the page the distance set by `delta`. */
   scroll: (
     delta: Partial<Vector>,
     options?: ScrollOptions) => Promise<void>
+  /** Gets the element via a selector. Can use an XPath. */
   getElement: (
     selector: string | ElementHandle,
     options?: GetElementOptions) => Promise<ElementHandle<Element>>
+  /** Get current location of the cursor. */
   getLocation: () => Vector
   /**
-   * Defined only if `visible=true` is passed.
-   *
-   * NOTE: Must be a promise, since we can't `await` in the constructor.
-   */
+    * Make the cursor no longer visible.
+    * Defined only if `visible=true` was passed.
+    */
   removeMouseHelper?: Promise<() => Promise<void>>
 }
 
@@ -222,50 +230,55 @@ export const getRandomPagePoint = async (page: Page): Promise<Vector> => {
   })
 }
 
-/** Using this method to get correct position of Inline elements (elements like `<a>`) */
-const getElementBox = async (
+/** Get correct position of Inline elements (elements like `<a>`). Has fallback. */
+export const getElementBox = async (
   page: Page,
   element: ElementHandle,
-  relativeToMainFrame: boolean = true
-): Promise<BoundingBox | null> => {
-  const objectId = element.remoteObject().objectId
-  if (objectId === undefined) {
-    return null
-  }
-
+  relativeToMainFrame: boolean = true): Promise<BoundingBox> => {
   try {
+    const objectId = element.remoteObject().objectId
+    if (objectId === undefined) throw new Error('Element objectId is undefined, falling back to alternative methods')
+
     const quads = await getCDPClient(page).send('DOM.getContentQuads', { objectId })
-    const elementBox = {
+    const elementBox: BoundingBox = {
       x: quads.quads[0][0],
       y: quads.quads[0][1],
       width: quads.quads[0][4] - quads.quads[0][0],
       height: quads.quads[0][5] - quads.quads[0][1]
     }
     if (!relativeToMainFrame) {
       const elementFrame = await element.contentFrame()
-      const iframes =
-        elementFrame != null
-          ? await elementFrame.parentFrame()?.$$('xpath/.//iframe')
-          : null
-      let frame: ElementHandle<Node> | undefined
-      if (iframes != null) {
+      const iframes = await elementFrame?.parentFrame()?.$$('xpath/.//iframe')
+      if (iframes !== undefined && iframes !== null) {
+        let frame: ElementHandle<Node> | undefined
         for (const iframe of iframes) {
-          if ((await iframe.contentFrame()) === elementFrame) frame = iframe
+          if ((await iframe.contentFrame()) === elementFrame) {
+            frame = iframe
+          }
+        }
+        if (frame !== undefined && frame != null) {
+          const frameBox = await frame.boundingBox()
+          if (frameBox !== null) {
+            elementBox.x -= frameBox.x
+            elementBox.y -= frameBox.y
+          }
         }
-      }
-      if (frame != null) {
-        const boundingBox = await frame.boundingBox()
-        elementBox.x =
-          boundingBox !== null ? elementBox.x - boundingBox.x : elementBox.x
-        elementBox.y =
-          boundingBox !== null ? elementBox.y - boundingBox.y : elementBox.y
       }
     }
 
     return elementBox
-  } catch (_) {
-    log('Quads not found, trying regular boundingBox')
-    return await element.boundingBox()
+  } catch {
+    try {
+      log('Quads not found, trying regular boundingBox')
+      const elementBox = await element.boundingBox()
+      if (elementBox === null) throw new Error('Element boundingBox is null, falling back to getBoundingClientRect')
+      return elementBox
+    } catch {
+      log('BoundingBox null, using getBoundingClientRect')
+      return await element.evaluate((el) =>
+        el.getBoundingClientRect() as BoundingBox
+      )
+    }
   }
 }
 
@@ -281,20 +294,6 @@ const intersectsElement = (vec: Vector, box: BoundingBox): boolean => {
   )
 }
 
-const boundingBoxWithFallback = async (
-  page: Page,
-  elem: ElementHandle<Element>
-): Promise<BoundingBox> => {
-  let box = await getElementBox(page, elem)
-  if (box == null) {
-    box = (await elem.evaluate((el: Element) =>
-      el.getBoundingClientRect()
-    )) as BoundingBox
-  }
-
-  return box
-}
-
 export const createCursor = (
   page: Page,
   /**
@@ -350,7 +349,7 @@ export const createCursor = (
   // Initial state: mouse is not moving
   let moving: boolean = false
 
-  // Move the mouse over a number of vectors
+  /** Move the mouse over a number of vectors */
   const tracePath = async (
     vectors: Iterable<Vector | TimedVector>,
     abortOnMove: boolean = false
@@ -383,7 +382,7 @@ export const createCursor = (
       }
     }
   }
-  // Start random mouse movements. Function recursively calls itself
+  /** Start random mouse movements. Function recursively calls itself. */
   const randomMove = async (options?: RandomMoveOptions): Promise<void> => {
     const optionsResolved = {
       moveDelay: 2000,
@@ -409,14 +408,17 @@ export const createCursor = (
   }
 
   const actions: GhostCursor = {
+    /** Toggles random mouse movements on or off. */
     toggleRandomMove (random: boolean): void {
       moving = !random
     },
 
+    /** Get current location of the cursor. */
     getLocation (): Vector {
       return previous
     },
 
+    /** Simulates a mouse click at the specified selector or element. */
     async click (
       selector?: string | ElementHandle,
       options?: ClickOptions
@@ -465,6 +467,7 @@ export const createCursor = (
       actions.toggleRandomMove(wasRandom)
     },
 
+    /** Moves the mouse to the specified selector or element. */
     async move (
       selector: string | ElementHandle,
       options?: MoveOptions
@@ -492,7 +495,7 @@ export const createCursor = (
         // Make sure the object is in view
         await this.scrollIntoView(elem, optionsResolved)
 
-        const box = await boundingBoxWithFallback(page, elem)
+        const box = await getElementBox(page, elem)
         const { height, width } = box
         const destination = (optionsResolved.destination !== undefined)
           ? add(box, optionsResolved.destination)
@@ -522,7 +525,7 @@ export const createCursor = (
 
         actions.toggleRandomMove(true)
 
-        const newBoundingBox = await boundingBoxWithFallback(page, elem)
+        const newBoundingBox = await getElementBox(page, elem)
 
         // It's possible that the element that is being moved towards
         // has moved to a different location by the time
@@ -538,6 +541,7 @@ export const createCursor = (
       await delay(optionsResolved.moveDelay * (optionsResolved.randomizeMoveDelay ? Math.random() : 1))
     },
 
+    /** Moves the mouse to the specified destination point. */
     async moveTo (destination: Vector, options?: MoveToOptions): Promise<void> {
       const optionsResolved = {
         moveDelay: 0,
@@ -554,6 +558,7 @@ export const createCursor = (
       await delay(optionsResolved.moveDelay * (optionsResolved.randomizeMoveDelay ? Math.random() : 1))
     },
 
+    /** Scrolls the element into view. If already in view, no scroll occurs. */
     async scrollIntoView (selector: string | ElementHandle, options?: ScrollIntoViewOptions): Promise<void> {
       const optionsResolved = {
         scrollDelay: 200,
@@ -585,7 +590,7 @@ export const createCursor = (
         }
       ))
 
-      const elemBoundingBox = await boundingBoxWithFallback(page, elem) // is relative to viewport
+      const elemBoundingBox = await getElementBox(page, elem) // is relative to viewport
       const elemBox = {
         top: elemBoundingBox.y,
         left: elemBoundingBox.x,
@@ -672,6 +677,7 @@ export const createCursor = (
       }
     },
 
+    /** Scrolls the page the distance set by `delta`. */
     async scroll (delta: Partial<Vector>, options?: ScrollOptions) {
       const optionsResolved = {
         scrollDelay: 200,
@@ -732,6 +738,7 @@ export const createCursor = (
       await delay(optionsResolved.scrollDelay)
     },
 
+    /** Scrolls to the specified destination point. */
     async scrollTo (destination: ScrollToDestination, options?: ScrollOptions) {
       const optionsResolved = {
         scrollDelay: 200,
@@ -775,6 +782,7 @@ export const createCursor = (
       }, optionsResolved)
     },
 
+    /** Gets the element via a selector. Can use an XPath. */
     async getElement (selector: string | ElementHandle, options?: GetElementOptions): Promise<ElementHandle<Element>> {
       const optionsResolved = {
         ...defaultOptions?.getElement,
@@ -809,11 +817,14 @@ export const createCursor = (
     }
   }
 
-  if (visible) {
-    const removeMouseHelper = installMouseHelper(page).then(
+  /**
+    * Make the cursor no longer visible.
+    * Defined only if `visible=true` was passed.
+    */
+  actions.removeMouseHelper = visible
+    ? installMouseHelper(page).then(
       ({ removeMouseHelper }) => removeMouseHelper)
-    actions.removeMouseHelper = removeMouseHelper
-  }
+    : undefined
 
   // Start random mouse movements. Do not await the promise but return immediately
   if (performRandomMoves) {