Keyboard & Mouse

CraftDriver provides low-level keyboard and mouse APIs for complex interaction scenarios.

Keyboard

Access the keyboard API via browser.keyboard.

press(key)

Press and release a key.

await browser.keyboard.press('Enter');
await browser.keyboard.press('Tab');
await browser.keyboard.press('Escape');

Common key names:

• Navigation: 'Tab', 'Enter', 'Escape', 'Backspace', 'Delete'
• Arrows: 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'
• Modifiers: 'Shift', 'Control', 'Alt', 'Meta'
• Function: 'F1' through 'F12'
• Special: 'Home', 'End', 'PageUp', 'PageDown', 'Insert'

type(text)

Type a string of text character by character.

await browser.keyboard.type('Hello, World!');

down(key)

Press and hold a key.

await browser.keyboard.down('Shift');

up(key)

Release a held key.

await browser.keyboard.up('Shift');

chord(...keys)

Press a key combination.

await browser.keyboard.chord('Control', 'a');
await browser.keyboard.chord('Shift', 'Tab');

Key Combinations

Combine down() and up() for modifier key combinations:

// Ctrl+A (select all)
await browser.keyboard.down('Control');
await browser.keyboard.press('a');
await browser.keyboard.up('Control');

// Shift+Tab (reverse tab)
await browser.keyboard.down('Shift');
await browser.keyboard.press('Tab');
await browser.keyboard.up('Shift');

Examples

Search and Submit

await browser.find('#search').click();
await browser.keyboard.type('craftdriver');
await browser.keyboard.press('Enter');

Form Navigation with Tab

await browser.find('#first-name').fill('John');
await browser.keyboard.press('Tab');
await browser.keyboard.type('Doe'); // Now in last-name field
await browser.keyboard.press('Tab');
await browser.keyboard.type('john@example.com');

Select All and Delete

await browser.find('#input').click();
await browser.keyboard.down('Control');
await browser.keyboard.press('a');
await browser.keyboard.up('Control');
await browser.keyboard.press('Backspace');

---

Mouse

Access the mouse API via browser.mouse. click(), move(), and dragAndDrop() all accept a Target: a CSS selector string, a By locator, or { x, y } coordinates.

click(target, options?)

Click at coordinates or on an element.

await browser.mouse.click({ x: 100, y: 200 });
await browser.mouse.click('#submit');
await browser.mouse.click('#submit', { button: 'right', clickCount: 2 });

dblclick(target, options?)

Double-click at coordinates or on an element (shorthand for click(target, { clickCount: 2 })).

await browser.mouse.dblclick('#item');

move(target, options?)

Move the mouse to coordinates or over an element.

await browser.mouse.move({ x: 150, y: 300 });
await browser.mouse.move('#target');

down(button?)

Press the mouse button.

await browser.mouse.down();
await browser.mouse.down('right');

up(button?)

Release the mouse button.

await browser.mouse.up();
await browser.mouse.up('right');

wheel(deltaX, deltaY, target?)

Scroll the page.

// Scroll down
await browser.mouse.wheel(0, 100);

// Scroll up
await browser.mouse.wheel(0, -100);

// Scroll right
await browser.mouse.wheel(100, 0);

// Scroll while targeting an element
await browser.mouse.wheel(0, 300, '#scroll-panel');

dragAndDrop(from, to)

Drag from one position to another.

await browser.mouse.dragAndDrop(
  { x: 100, y: 100 }, // Start position
  { x: 300, y: 300 } // End position
);

Examples

Custom Drag Operation

// Get element positions
const source = await browser.find('#draggable').boundingBox();
const target = await browser.find('#drop-zone').boundingBox();

// Calculate centers
const startX = source.x + source.width / 2;
const startY = source.y + source.height / 2;
const endX = target.x + target.width / 2;
const endY = target.y + target.height / 2;

// Perform drag
await browser.mouse.dragAndDrop({ x: startX, y: startY }, { x: endX, y: endY });

Canvas Drawing

// Move to start position
await browser.mouse.move({ x: 100, y: 100 });
await browser.mouse.down();

// Draw a line
await browser.mouse.move({ x: 200, y: 100 });
await browser.mouse.move({ x: 200, y: 200 });
await browser.mouse.move({ x: 100, y: 200 });
await browser.mouse.move({ x: 100, y: 100 });

await browser.mouse.up();

Scroll Through Content

// Navigate to page
await browser.navigateTo('https://example.com/long-page');

// Scroll down gradually
for (let i = 0; i < 5; i++) {
  await browser.mouse.wheel(0, 200);
  await browser.pause(500);
}

---

Element-Level Keyboard Shortcuts

For element-scoped key presses, use the press() method on ElementHandle:

// Press Enter in a specific input
const search = browser.find('#search');
await search.fill('query');
await search.press('Enter');

// Tab out of a field
const username = browser.find('#username');
await username.fill('user');
await username.press('Tab');

This is often more convenient than using the global keyboard API.

---

Touch gestures (mobile emulation)

When running with mobileEmulation, two convenience gestures are exposed under browser.gesture:

// Swipe from one point to another (px coordinates).
await browser.gesture.swipe({
  from: [200, 600],
  to:   [200, 200],
  durationMs: 300,
});

// Pinch / zoom centered on a point.
await browser.gesture.pinch({
  center: [200, 400],
  scale: 0.5,      // < 1 zooms out, > 1 zooms in
  distance: 100,   // initial finger separation, px
  durationMs: 250,
});

These wrap the W3C Pointer Actions API with two simulated touch pointers. They work whether or not BiDi is enabled.