feat: scroll, scrollTo (#165)

* feat: scrollTo

* use cdp scroll

Author: bvandercar-vt

README.md

@@ -144,16 +144,32 @@ 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(selector: string | ElementHandle, options?: ScrollOptions) => Promise<void>`
+#### `scrollIntoView(selector: string | ElementHandle, options?: ScrollIntoViewOptions) => Promise<void>`
 
 Scrolls the element into view. If already in view, no scroll occurs.
 
 - **selector:** CSS selector or ElementHandle to identify the target element.
-- **options (optional):** Additional options for scrolling. **Extends the `options` of the `getElement` function (below)**
+- **options (optional):** Additional options for scrolling. **Extends the `options` of the `getElement` and `scroll` functions (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`.
 
+#### `scrollTo: (destination: Partial<Vector> | 'top' | 'bottom' | 'left' | 'right', options?: ScrollOptions) => Promise<void>`
+
+Scrolls to the specified destination point.
+
+- **destination:** An object with `x` and `y` coordinates representing the target position. For example, `{ x: 500, y: 300 }`. Can also be `"top"` or `"bottom"`.
+- **options (optional):** Additional options for scrolling. **Extends the `options` of the `scroll` function (below)**
+
+#### `scroll: (delta: Partial<Vector>, options?: ScrollOptions) => Promise<void>`
+
+Scrolls the page the distance set by `delta`.
+
+- **delta:** An object with `x` and `y` coordinates representing the distance to scroll from the current position.
+- **options (optional):** Additional options for scrolling.
+  - `scrollSpeed (number):` Scroll speed. 0 to 100. 100 is instant. Default is `100`.
+  - `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.

src/__debug__/browser-debug.ts

@@ -16,7 +16,8 @@ const cursorDefaultOptions = {
   waitForClick: 10,
   scrollDelay: 100,
   scrollSpeed: 40,
-  inViewportMargin: 50
+  inViewportMargin: 50,
+  waitForSelector: 200
 } as const satisfies ClickOptions
 
 puppeteer.launch({ headless: false }).then(async (browser) => {
@@ -26,8 +27,10 @@ puppeteer.launch({ headless: false }).then(async (browser) => {
 
   const cursor = createCursor(page, undefined, undefined, {
     move: cursorDefaultOptions,
+    moveTo: cursorDefaultOptions,
     click: cursorDefaultOptions,
-    moveTo: cursorDefaultOptions
+    scroll: cursorDefaultOptions,
+    getElement: cursorDefaultOptions
   })
 
   const html = await fs.readFile(join(__dirname, 'custom-page.html'), 'utf8')
@@ -44,6 +47,14 @@ puppeteer.launch({ headless: false }).then(async (browser) => {
     await cursor.click('#box3')
 
     await cursor.click('#box1')
+
+    // await cursor.scrollTo('right')
+
+    // await cursor.scrollTo('left')
+
+    // await cursor.scrollTo('bottom')
+
+    // await cursor.scrollTo('top')
   }
 
   await performActions()

src/__test__/spoof.spec.ts

@@ -48,6 +48,10 @@ describe('Mouse movements', () => {
     expect(await page.evaluate(() => window.boxWasClicked)).toEqual(true)
   }
 
+  const getScrollPosition = async (): Promise<{ top: number, left: number }> => await page.evaluate(() => (
+    { top: window.scrollY, left: window.scrollX }
+  ))
+
   it('Should click on the element without throwing an error (CSS selector)', async () => {
     await testClick('#box1')
   })
@@ -57,10 +61,6 @@ describe('Mouse movements', () => {
   })
 
   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 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
@@ -89,6 +89,25 @@ describe('Mouse movements', () => {
     await cursor.click(boxes[0])
     expect(await boxes[0].isIntersectingViewport()).toBeTruthy()
   })
+
+  it('Should scroll to position correctly', async () => {
+    expect(await getScrollPosition()).toEqual({ top: 0, left: 0 })
+
+    await cursor.scrollTo('bottom')
+    expect(await getScrollPosition()).toEqual({ top: 4450, left: 0 })
+
+    await cursor.scrollTo('right')
+    expect(await getScrollPosition()).toEqual({ top: 4450, left: 2250 })
+
+    await cursor.scrollTo('top')
+    expect(await getScrollPosition()).toEqual({ top: 0, left: 2250 })
+
+    await cursor.scrollTo('left')
+    expect(await getScrollPosition()).toEqual({ top: 0, left: 0 })
+
+    await cursor.scrollTo({ y: 200, x: 400 })
+    expect(await getScrollPosition()).toEqual({ top: 200, left: 400 })
+  })
 })
 
 jest.setTimeout(15_000)