Overview
Scroll the page or the active element in any direction with the mouse wheel or the keyboard.Focus RequirementsA 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
await testdriver.pressKeys(['pagedown']); // Scroll down
await testdriver.pressKeys(['pageup']); // Scroll up
Syntax
await testdriver.scroll(direction, options)
Parameters
string
default:"down"
Direction to scroll:
'up', 'down'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
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']);
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']);
The keyboard scroll uses Page Down and Page UpA 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.
Use Cases
Infinite Scroll
Infinite Scroll
// 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
}
Horizontal Gallery
Horizontal Gallery
// 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();
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 scrollpressKeys()- Use the Page Down and Page Up keyswait()- Wait after a scroll