Merge branch 'master' into scrollTo

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,12 +144,12 @@ 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`.
@@ -163,6 +162,13 @@ Scrolls to the specified destination point.
 - **options (optional):** Additional options for scrolling.
   - `behavior (ScrollBehavior):` Directly passed to `window.scrollTo`.
   - `scrollDelay (number):` Time to wait after scrolling. Default is `200`.
+#### `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`
 

src/__test__/custom-page.html

@@ -38,6 +38,10 @@
   setTimeout(() => {
     box.style.top = Math.random() * 500
   }, 1000)
+  window.boxWasClicked = false
+  box.addEventListener('click', () => {
+    window.boxWasClicked = true
+  })
 </script>
 
 </html>

src/__test__/spoof.spec.ts

@@ -1,7 +1,7 @@
-import type { Page } from 'puppeteer'
+import type { ElementHandle, Page } from 'puppeteer'
 import { type ClickOptions, createCursor, GhostCursor } from '../spoof'
 import { join } from 'path'
-import { promises as fs } from 'fs'
+import { readFileSync } from 'fs'
 import installMouseHelper from '../mouse-helper'
 
 declare const page: Page
@@ -18,63 +18,76 @@ const cursorDefaultOptions = {
   inViewportMargin: 50
 } as const satisfies ClickOptions
 
+declare global {
+  // eslint-disable-next-line no-var
+  var boxWasClicked: boolean
+}
+
 describe('Mouse movements', () => {
+  const html = readFileSync(join(__dirname, 'custom-page.html'), 'utf8')
+
   beforeAll(async () => {
     await installMouseHelper(page)
-    const html = await fs.readFile(join(__dirname, 'custom-page.html'), 'utf8')
+  })
+
+  beforeEach(async () => {
     await page.goto('data:text/html,' + encodeURIComponent(html), {
       waitUntil: 'networkidle2'
     })
-  })
 
-  beforeEach(() => {
     cursor = createCursor(page, undefined, undefined, {
       move: cursorDefaultOptions,
       click: cursorDefaultOptions,
       moveTo: cursorDefaultOptions
     })
   })
 
+  const testClick = async (clickSelector: string): Promise<void> => {
+    expect(await page.evaluate(() => window.boxWasClicked)).toEqual(false)
+    await cursor.click(clickSelector)
+    expect(await page.evaluate(() => window.boxWasClicked)).toEqual(true)
+  }
+
   it('Should click on the element without throwing an error (CSS selector)', async () => {
-    await cursor.click('#box1')
+    await testClick('#box1')
   })
 
   it('Should click on the element without throwing an error (XPath selector)', async () => {
-    await cursor.click('//*[@id="box1"]')
+    await testClick('//*[@id="box1"]')
   })
 
   it('Should scroll to elements correctly', async () => {
     const getScrollPosition = async (): Promise<{ top: number, left: number }> => await page.evaluate(() => (
       { top: window.scrollY, left: window.scrollX }
     ))
 
-    const box1 = await page.waitForSelector('#box1')
-    if (box1 == null) throw new Error('box not found')
-    const box2 = await page.waitForSelector('#box2')
-    if (box2 == null) throw new Error('box not found')
-    const box3 = await page.waitForSelector('#box3')
-    if (box3 == null) throw new Error('box not found')
+    const boxes = await Promise.all([1, 2, 3].map(async (number: number): Promise<ElementHandle<HTMLElement>> => {
+      const selector = `#box${number}`
+      const box = await page.waitForSelector(selector) as ElementHandle<HTMLElement> | null
+      if (box == null) throw new Error(`${selector} not found`)
+      return box
+    }))
 
     expect(await getScrollPosition()).toEqual({ top: 0, left: 0 })
 
-    expect(await box1.isIntersectingViewport()).toBeTruthy()
-    await cursor.click(box1)
+    expect(await boxes[0].isIntersectingViewport()).toBeTruthy()
+    await cursor.click(boxes[0])
     expect(await getScrollPosition()).toEqual({ top: 0, left: 0 })
-    expect(await box1.isIntersectingViewport()).toBeTruthy()
+    expect(await boxes[0].isIntersectingViewport()).toBeTruthy()
 
-    expect(await box2.isIntersectingViewport()).toBeFalsy()
-    await cursor.move(box2)
+    expect(await boxes[1].isIntersectingViewport()).toBeFalsy()
+    await cursor.move(boxes[1])
     expect(await getScrollPosition()).toEqual({ top: 2500, left: 0 })
-    expect(await box2.isIntersectingViewport()).toBeTruthy()
+    expect(await boxes[1].isIntersectingViewport()).toBeTruthy()
 
-    expect(await box3.isIntersectingViewport()).toBeFalsy()
-    await cursor.move(box3)
+    expect(await boxes[2].isIntersectingViewport()).toBeFalsy()
+    await cursor.move(boxes[2])
     expect(await getScrollPosition()).toEqual({ top: 4450, left: 2250 })
-    expect(await box3.isIntersectingViewport()).toBeTruthy()
+    expect(await boxes[2].isIntersectingViewport()).toBeTruthy()
 
-    expect(await box1.isIntersectingViewport()).toBeFalsy()
-    await cursor.click(box1)
-    expect(await box1.isIntersectingViewport()).toBeTruthy()
+    expect(await boxes[0].isIntersectingViewport()).toBeFalsy()
+    await cursor.click(boxes[0])
+    expect(await boxes[0].isIntersectingViewport()).toBeTruthy()
   })
 })
 

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
@@ -153,6 +156,9 @@ export interface GhostCursor {
   scrollTo: (
     destination: Partial<Vector> | 'top' | 'bottom',
     options?: ScrollToOptions) => Promise<void>
+  getElement: (
+    selector: string | ElementHandle,
+    options?: GetElementOptions) => Promise<ElementHandle<Element>>
   getLocation: () => Vector
 }
 
@@ -389,10 +395,15 @@ export const createCursor = (
      */
     click?: ClickOptions
     /**
-   * Default options for the `scrollIntoView` function
-   * @default ScrollOptions
-   */
+    * 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
@@ -496,9 +507,16 @@ export const createCursor = (
 
       try {
         await delay(optionsResolved.hesitate)
-        await page.mouse.down()
+
+        const cdpClient = getCDPClient(page)
+        const dispatchParams: Omit<Protocol.Input.DispatchMouseEventRequest, 'type'> = {
+          ...previous,
+          button: 'left',
+          clickCount: 1
+        }
+        await cdpClient.send('Input.dispatchMouseEvent', { ...dispatchParams, type: 'mousePressed' })
         await delay(optionsResolved.waitForClick)
-        await page.mouse.up()
+        await cdpClient.send('Input.dispatchMouseEvent', { ...dispatchParams, type: 'mouseReleased' })
       } catch (error) {
         log('Warning: could not click mouse, error message:', error)
       }
@@ -529,34 +547,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)
@@ -623,7 +615,7 @@ 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,
@@ -632,6 +624,8 @@ export const createCursor = (
         ...options
       } satisfies ScrollOptions
 
+      const elem = await this.getElement(selector, optionsResolved)
+
       const {
         viewportWidth,
         viewportHeight,
@@ -807,6 +801,39 @@ export const createCursor = (
         destination
       )
       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
     }
   }