MOUSE, KEYBOARD & DRAG-AND-DROP ACTIONS

Master low-level input simulation in Playwright with Python: hover menus, drag-and-drop operations, precise mouse wheel scrolling, cursor coordinates, and custom keyboard combos.

🖱️ Advanced Input Simulation in Playwright

While high-level convenience methods (like click() and fill()) power most test suites, complex web user interfaces require physical input simulation. Interactive map views, kanban task boards, slider controls, and hover-triggered mega-menus demand granular control over hardware pointer coordinates and raw keyboard scan codes. Playwright provides high-level APIs like locator.hover() and locator.drag_to() alongside low-level controllers (page.mouse and page.keyboard), dispatching real browser events without synthesizing fake JavaScript events.

1. High-Level Locator Actions vs. Low-Level page.mouse / page.keyboard
Playwright separates pointer and keyboard automation into two layers: high-level locator-bound actions that auto-wait for element visibility and stability, and low-level page-wide virtual input devices.
Input Architecture Comparison
HIGH-LEVEL LOCATOR-BOUND ACTIONS (Recommended for 95% of UI tests):
* locator.hover()         ──► Auto-waits, scrolls into view, moves pointer over bounding box.
* locator.drag_to(target) ──► Auto-waits on source & target, executes complete drag gesture.
* locator.press("Enter")  ──► Focuses element, dispatches keydown, keypress, keyup.

LOW-LEVEL PAGE CONTROLLERS (For Canvas, Drag Sliders & Freeform Gestures):
* page.mouse.move(x, y)   ──► Dispatches mousemove to absolute screen coordinates.
* page.mouse.down() / up()──► Presses and releases pointer buttons explicitly.
* page.mouse.wheel(dx, dy)──► Dispatches vertical and horizontal wheel scroll ticks.
* page.keyboard.down(key) ──► Holds modifier keys down across subsequent mouse movements.
Rule: Prefer locator-level actions (hover, drag_to) for standard DOM elements; use page.mouse and page.keyboard for canvas, SVG drawings, or games.
Real-Time Example 1: Hover Menus & Flyout Navigation
Trigger CSS :hover states and JavaScript mouseenter listeners using locator.hover(). This scrolls the trigger into view, positions the cursor over its center, and exposes nested flyout submenus.
Python (Hover Menu Automation)
from playwright.sync_api import sync_playwright, expect

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()

    # Dropdown navigation revealed only on hover
    page.set_content("""
        
        
    """)

    parent_menu = page.locator("#services-parent")
    submenu_link = page.locator("#link-qa")

    # Initial state: submenu is hidden
    expect(submenu_link).to_be_hidden()

    # Hover over menu trigger to reveal flyout
    parent_menu.hover()

    # Auto-waiting assertion verifies hover revealed the target link
    expect(submenu_link).to_be_visible()
    expect(submenu_link).to_have_text("Automation QA Suite")

    print(f"Hover action revealed submenu item: '{submenu_link.inner_text()}'")
    browser.close()
Output: Hover action revealed submenu item: 'Automation QA Suite'
Real-Time Example 2: High-Level Drag-and-Drop via locator.drag_to()
Transfer draggable cards between containers (such as moving items across Kanban boards) using source.drag_to(target) in a single auto-waiting call.
Python (locator.drag_to Implementation)
from playwright.sync_api import sync_playwright, expect

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()

    page.set_content("""
        
Write Playwright Tests
""") source_card = page.locator("#task-card") destination_col = page.locator("#done-column") # High-level drag and drop source_card.drag_to(destination_col) # Verify card relocated to target container expect(destination_col.locator("#task-card")).to_be_visible() expect(page.locator("#todo-column").locator("#task-card")).to_have_count(0) print("Card moved to Done column successfully via drag_to()!") browser.close()
Output: Card moved to Done column successfully via drag_to()!
Real-Time Example 3: Low-Level Mouse Gestures (move, down, up)
When automating canvas drawing pads, custom signature widgets, or non-HTML5 drag libraries, use page.mouse.move(), down(), and up() to draw continuous coordinate paths.
Python (page.mouse Canvas Drawing)
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()

    page.set_content("""
        
        
0
""") canvas = page.locator("#paint-pad") box = canvas.bounding_box() # Calculate absolute coordinates inside the canvas start_x = box["x"] + 20 start_y = box["y"] + 20 # 1. Move to start position page.mouse.move(start_x, start_y) # 2. Press left mouse button down page.mouse.down() # 3. Drag across coordinates in 5 interpolated steps page.mouse.move(start_x + 80, start_y + 80, steps=5) # 4. Release mouse button page.mouse.up() points_drawn = int(page.locator("#points-logged").inner_text()) print(f"Dispatched multi-step drawing gesture! Total stroke points logged: {points_drawn}") browser.close()
Output: Dispatched multi-step drawing gesture! Total stroke points logged: 5
Real-Time Example 4: Mouse Wheel Scrolling & Infinite Feeds
Dispatch vertical and horizontal scroll wheel ticks using page.mouse.wheel(delta_x, delta_y) to test infinite scroll pagination or custom overflowing viewport containers.
Python (page.mouse.wheel Scrolling)
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()

    page.set_content("""
        

Top of Feed

Bottom of Feed Reached!
""") scroll_container = page.locator("#scroll-box") scroll_container.hover() # Check initial scroll position initial_scroll_y = scroll_container.evaluate("el => el.scrollTop") print(f"Initial scrollTop: {initial_scroll_y}px") # Dispatch mouse wheel scroll down by 450 vertical pixels page.mouse.wheel(delta_x=0, delta_y=450) # Read updated scroll position updated_scroll_y = scroll_container.evaluate("el => el.scrollTop") print(f"Updated scrollTop after mouse.wheel(): {updated_scroll_y}px") browser.close()
Output: Initial scrollTop: 0px Updated scrollTop after mouse.wheel(): 450px
Real-Time Example 5: Multi-Key Combinations via page.keyboard
Test custom keyboard shortcuts (like Control+S, Shift+Tab, or Alt+F) by holding modifier keys down, pressing letter keys, and releasing modifiers cleanly.
Python (Modifier Key Down/Up Sequencing)
from playwright.sync_api import sync_playwright, expect

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()

    page.set_content("""
        
No shortcut
""") editor = page.locator("#editor") status_display = page.locator("#shortcut-status") # Focus textarea editor.focus() # Dispatch Control+S shortcut combo page.keyboard.down("Control") page.keyboard.press("s") page.keyboard.up("Control") expect(status_display).to_have_text("CTRL_S_TRIGGERED") print(f"Keyboard event captured: '{status_display.inner_text()}'") browser.close()
Output: Keyboard event captured: 'CTRL_S_TRIGGERED'
Real-Time Example 6: Keyboard Text Insertion via keyboard.insert_text()
page.keyboard.insert_text() sends characters directly into the currently focused element as a text input event without triggering individual keydown/keyup events, ideal for emojis and non-Latin unicode.
Python (Unicode & Emoji Insertion)
from playwright.sync_api import sync_playwright, expect

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()

    page.set_content('')
    comment_box = page.locator("#comment-box")

    # Focus element and insert special characters and emoji symbols
    comment_box.focus()
    page.keyboard.insert_text("Playwright Automation 🚀 🇮🇳")

    expect(comment_box).to_have_value("Playwright Automation 🚀 🇮🇳")
    print(f"Inserted Unicode String: '{comment_box.input_value()}'")

    browser.close()
Output: Inserted Unicode String: 'Playwright Automation 🚀 🇮🇳'
Real-Time Example 7: Simulating Range Slider Dragging
Interact with native HTML5 <input type="range"> controls or custom slider handles by calculating track pixel widths and dispatching mouse drag actions.
Python (Slider Track Automation)
from playwright.sync_api import sync_playwright, expect

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()

    page.set_content("""
        
20
""") slider = page.get_by_label("Price Filter") value_display = page.locator("#range-val") # Approach A: Keyboard Arrow Navigation on focused slider slider.focus() slider.press("ArrowRight") slider.press("ArrowRight") slider.press("ArrowRight") print(f"Slider value after ArrowRight keystrokes: '{value_display.inner_text()}'") # Approach B: Relative Coordinate Click to jump across track box = slider.bounding_box() # Click at 80% mark across slider track (200px * 0.8 = 160px) page.mouse.click(box["x"] + 160, box["y"] + (box["height"] / 2)) print(f"Slider value after coordinate jump : '{value_display.inner_text()}'") browser.close()
Output: Slider value after ArrowRight keystrokes: '23' Slider value after coordinate jump : '80'
Real-Time Example 8: Handling Drag-and-Drop Fallbacks with drag_to() vs. Mouse Steps
Some non-standard JavaScript libraries (like react-beautiful-dnd or SortableJS) ignore HTML5 drag events and listen solely to pointer events. When drag_to() doesn't trigger a move, fallback to multi-step mouse emulation.
Python (Resilient Drag-and-Drop Fallback Helper)
from playwright.sync_api import Locator, Page, sync_playwright

def custom_pointer_drag(page: Page, source: Locator, target: Locator):
    """Fallback manual drag for UI components that ignore HTML5 Drag events."""
    src_box = source.bounding_box()
    dst_box = target.bounding_box()

    start_x = src_box["x"] + src_box["width"] / 2
    start_y = src_box["y"] + src_box["height"] / 2
    end_x = dst_box["x"] + dst_box["width"] / 2
    end_y = dst_box["y"] + dst_box["height"] / 2

    # Execute step-by-step pointer gesture
    page.mouse.move(start_x, start_y)
    page.mouse.down()
    page.mouse.move(end_x, end_y, steps=10)  # Multi-step movement fires continuous mousemove
    page.mouse.up()

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()

    page.set_content("""
        
""") source = page.locator("#drag-item") target = page.locator("#drop-target") custom_pointer_drag(page, source, target) print("Custom pointer drag sequence dispatched successfully!") browser.close()
Output: Custom pointer drag sequence dispatched successfully!
Real-Time Example 9: Mouse & Keyboard Methods Reference Matrix
A comprehensive reference summary of all core pointer and keyboard manipulation methods available in Playwright Python.
Input Methods Reference Matrix
PLAYWRIGHT MOUSE & KEYBOARD METHODS MATRIX:
┌──────────────────────────────┬──────────────────────────────┬─────────────────────────────────────────────────────────┐
│ Method / Operation           │ Parameters                   │ Description / Primary Use Case                          │
├──────────────────────────────┼──────────────────────────────┼─────────────────────────────────────────────────────────┤
│ locator.hover()              │ modifiers, position, timeout │ Scrolls element into view and moves cursor over center. │
│ locator.drag_to(target)      │ target: Locator, timeout     │ Drags source locator onto target locator via HTML5 drag.│
│ locator.press(key)           │ key: str ("Enter", "Tab")    │ Dispatches keyboard shortcut to target element.         │
│ page.mouse.move(x, y)        │ x: float, y: float, steps    │ Moves pointer across coordinates with optional steps.   │
│ page.mouse.down()            │ button="left"|"right"|...    │ Presses mouse pointer button without releasing.         │
│ page.mouse.up()              │ button="left"|"right"|...    │ Releases held mouse pointer button.                     │
│ page.mouse.click(x, y)       │ x: float, y: float, delay    │ Clicks exact screen coordinates.                        │
│ page.mouse.wheel(dx, dy)     │ delta_x: float, delta_y: flt │ Dispatches horizontal and vertical wheel scroll ticks.  │
│ page.keyboard.press(key)     │ key: str ("ControlOrMeta+A") │ Shortcut combination (down + up in one call).           │
│ page.keyboard.down(key)      │ key: str ("Shift", "Control")│ Holds key down across subsequent operations.            │
│ page.keyboard.up(key)        │ key: str ("Shift", "Control")│ Releases held key.                                      │
│ page.keyboard.insert_text()  │ text: str                    │ Directly inserts raw text/emojis without key events.    │
└──────────────────────────────┴──────────────────────────────┴─────────────────────────────────────────────────────────┘
Engineering Best Practice: Prefer locator.hover() and locator.drag_to() for standard web testing; reserve page.mouse and page.keyboard for canvas widgets and custom coordinate gestures.