Testdriver Scroll

---
name: testdriver:scroll
description: Scroll pages and elements
---
<!-- Generated from scroll.mdx. DO NOT EDIT. -->

## Overview

Scroll the page or the active element in any direction with the mouse wheel or the keyboard.

<Warning>
  **Focus Requirements**
  
  A scroll needs focus on the page or on a frame. If an input field or another interactive element has focus, scroll commands can fail. Before you scroll, put the focus on the page:
  - Click a non-interactive area (for example, the page background)
  - Push the Escape key to remove the focus from interactive elements
  - Click outside of input fields or text areas
  
  **If the scroll still does not work**, use the Page Down or Page Up keys directly:
  ```javascript
  await testdriver.pressKeys(['pagedown']); // Scroll down
  await testdriver.pressKeys(['pageup']);   // Scroll up
  ```
</Warning>

## Syntax

```javascript
await testdriver.scroll(direction, options)
```

## Parameters

<ParamField path="direction" type="string" default="down">
  Direction to scroll: `'up'`, `'down'`
</ParamField>

<ParamField path="options" type="object">
  <Expandable title="properties">
    <ParamField path="amount" type="number" default="300">
      Amount to scroll in pixels
    </ParamField>
  </Expandable>
</ParamField>

## Returns

`Promise<void>`

## Examples

### Basic Scrolling

```javascript
// Scroll down (default)
await testdriver.scroll();

// Scroll down 5 clicks
await testdriver.scroll('down', { amount: 5 });

// Scroll up
await testdriver.scroll('up');

// Scroll up 2 clicks
await testdriver.scroll('up', { amount: 2 });
```

### Horizontal Scrolling

```javascript
// Scroll right
await testdriver.scroll('right', { amount: 3 });

// Scroll left
await testdriver.scroll('left', { amount: 3 });
```

### Scroll Methods

```javascript
// Mouse wheel scroll (default)
await testdriver.scroll('down', { amount: 3 });

// For keyboard-based scrolling, use pressKeys instead
await testdriver.pressKeys(['pagedown']);
```

## Best Practices

<Check>
  **Make sure that the page has focus before you scroll**
  
  ```javascript
  // After typing in an input, unfocus it first
  await testdriver.find('email input').click();
  await testdriver.type('user@example.com');
  
  // Click elsewhere or press Escape before scrolling
  await testdriver.pressKeys(['escape']);
  // Or click a non-interactive area
  // await testdriver.find('page background').click();
  
  // Now scroll will work properly
  await testdriver.scroll('down');
  
  // If scroll still doesn't work, use Page Down directly
  // await testdriver.pressKeys(['pagedown']);
  ```
</Check>

<Check>
  **Control the scroll distance with the options object**
  
  ```javascript
  // For web pages, mouse scroll works well
  await testdriver.scroll('down', { amount: 3 });
  
  // For desktop apps or when mouse doesn't work, use keyboard
  await testdriver.pressKeys(['pagedown']);
  ```
</Check>

<Warning>
  **The keyboard scroll uses Page Down and Page Up**
  
  A keyboard scroll usually moves one "page" each time. This can be more than the click amount that you set. It is more compatible than a mouse scroll, but it is less precise.
</Warning>

## Use Cases

<AccordionGroup>
  <Accordion title="Infinite Scroll">
    ```javascript
    // Scroll multiple times for infinite scroll
    for (let i = 0; i < 5; i++) {
      await testdriver.scroll('down', { amount: 5 });
      await new Promise(r => setTimeout(r, 1000)); // Wait for load
    }
    ```
  </Accordion>
  
  <Accordion title="Horizontal Gallery">
    ```javascript
    // Navigate horizontal carousel
    await testdriver.scroll('right', { amount: 3 });
    await new Promise(r => setTimeout(r, 500));
    
    const nextImage = await testdriver.find('next image in carousel');
    await nextImage.click();
    ```
  </Accordion>
</AccordionGroup>

## Complete Example

```javascript
import { beforeAll, afterAll, describe, it } from 'vitest';
import TestDriver from 'testdriverai';

describe('Scrolling', () => {
  let testdriver;

  beforeAll(async () => {
    client = new TestDriver(process.env.TD_API_KEY);
    await testdriver.auth();
    await testdriver.connect();
  });

  afterAll(async () => {
    await testdriver.disconnect();
  });

  it('should scroll to find elements', async () => {
    await testdriver.focusApplication('Google Chrome');
    
    // Scroll down the page
    await testdriver.scroll('down', { amount: 5 });
    
    // Click footer link
    const privacyLink = await testdriver.find('Privacy Policy link');
    await privacyLink.click();
    
    await testdriver.assert('privacy policy page is displayed');
  });

  it('should handle infinite scroll', async () => {
    await testdriver.focusApplication('Google Chrome');
    
    // Scroll multiple times to load content
    for (let i = 0; i < 3; i++) {
      await testdriver.scroll('down', { amount: 5 });
      await new Promise(r => setTimeout(r, 1500)); // Wait for load
    }
    
    // Verify content loaded
    await testdriver.assert('more than 10 items are visible');
  });
});
```

## Related Methods

- [`find()`](/find) - Find elements after a scroll
- [`pressKeys()`](/press-keys) - Use the Page Down and Page Up keys
- [`wait()`](/wait) - Wait after a scroll