testdriver:scroll

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:

await testdriver.pressKeys(['pagedown']); // Scroll down
await testdriver.pressKeys(['pageup']);   // Scroll up

</Warning>

Syntax

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

// 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

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

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

Scroll Methods

// 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**

// 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**

// 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

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 elements after a scroll
pressKeys() - Use the Page Down and Page Up keys
wait() - Wait after a scroll