Input Commands
Input commands handle mouse and keyboard interactions, providing human-like input simulation.
Overview
The input commands module provides functionality for simulating user input including mouse movements, clicks, keyboard typing, and key presses.
A class for simulating user input events using Chrome DevTools Protocol.
The Input domain provides methods for simulating user input, including: - Keyboard events (key presses, releases) - Mouse events (clicks, movements, wheel) - Touch events (taps, multi-touch gestures) - Drag and drop events - Synthetic gestures (pinch, scroll, tap)
These methods allow for programmatic control of input events without requiring actual user interaction, making it useful for testing and automation.
staticmethod
Generates a command to cancel any active dragging in the page.
This is useful when you need to interrupt an ongoing drag operation that might have been started with dispatchDragEvent or by other means.
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to cancel dragging.
TYPE:
|
staticmethod
dispatch_key_event(type, modifiers=None, timestamp=None, text=None, unmodified_text=None, key_identifier=None, code=None, key=None, windows_virtual_key_code=None, native_virtual_key_code=None, auto_repeat=None, is_keypad=None, is_system_key=None, location=None, commands=None)
Generates a command to dispatch a key event to the page.
This method can simulate various types of keyboard events such as key presses, key releases, and character inputs.
| PARAMETER | DESCRIPTION |
|---|---|
type
|
Type of the key event. Allowed values: keyDown, keyUp, rawKeyDown, char. - keyDown: Corresponds to a user pressing a key - keyUp: Corresponds to a user releasing a key - rawKeyDown: A physical key press, without the text processing - char: Generates a character without explicit key events
TYPE:
|
modifiers
|
Bit field representing pressed modifier keys. Values: Alt=1, Ctrl=2, Meta/Command=4, Shift=8 (default: 0). For example, to simulate Ctrl+Shift, use 10.
TYPE:
|
timestamp
|
Time at which the event occurred, in seconds since epoch.
TYPE:
|
text
|
Text as generated by processing a virtual key code with a keyboard layout. Not needed for 'keyUp' and 'rawKeyDown' events (default: "").
TYPE:
|
unmodified_text
|
Text that would have been generated by the keyboard without modifiers (except for shift). Useful for shortcut key handling (default: "").
TYPE:
|
key_identifier
|
Unique key identifier (e.g., 'U+0041') (default: "").
TYPE:
|
code
|
Unique DOM defined string value for each physical key (e.g., 'KeyA') (default: "").
TYPE:
|
key
|
Unique DOM defined string value describing the meaning of the key in the context of active modifiers, keyboard layout, etc. (e.g., 'AltGr') (default: "").
TYPE:
|
windows_virtual_key_code
|
Windows virtual key code (default: 0).
TYPE:
|
native_virtual_key_code
|
Native virtual key code (default: 0).
TYPE:
|
auto_repeat
|
Whether the event was generated from auto repeat (default: false).
TYPE:
|
is_keypad
|
Whether the event was generated from the keypad (default: false).
TYPE:
|
is_system_key
|
Whether the event was a system key event (default: false).
TYPE:
|
location
|
Whether the event was from the left or right side of the keyboard: 0=Default, 1=Left, 2=Right (default: 0).
TYPE:
|
commands
|
Editing commands to send with the key event (e.g., 'selectAll')
(default: []). These are related to but not equal to the command names
used in
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to dispatch the key event.
TYPE:
|
staticmethod
dispatch_mouse_event(type, x, y, modifiers=None, timestamp=None, button=None, click_count=None, force=None, tangential_pressure=None, tilt_x=None, tilt_y=None, twist=None, delta_x=None, delta_y=None, pointer_type=None)
Generates a command to dispatch a mouse event to the page.
This method allows simulating various mouse interactions such as clicks, movements, and wheel scrolling.
| PARAMETER | DESCRIPTION |
|---|---|
type
|
Type of the mouse event. Allowed values: - mousePressed: Mouse button pressed - mouseReleased: Mouse button released - mouseMoved: Mouse moved - mouseWheel: Mouse wheel rotated
TYPE:
|
x
|
X coordinate of the event relative to the main frame's viewport in CSS pixels.
TYPE:
|
y
|
Y coordinate of the event relative to the main frame's viewport in CSS pixels. 0 refers to the top of the viewport, and Y increases going down.
TYPE:
|
modifiers
|
Bit field representing pressed modifier keys. Values: Alt=1, Ctrl=2, Meta/Command=4, Shift=8 (default: 0).
TYPE:
|
timestamp
|
Time at which the event occurred, in seconds since epoch.
TYPE:
|
button
|
Mouse button being pressed/released. Default is "none". Allowed values: "none", "left", "middle", "right", "back", "forward".
TYPE:
|
click_count
|
Number of times the mouse button was clicked (default: 0). For example, 2 for a double-click.
TYPE:
|
force
|
The normalized pressure, which has a range of [0,1] (default: 0). Used primarily for pressure-sensitive inputs.
TYPE:
|
tangential_pressure
|
The normalized tangential pressure, which has a range of [-1,1] (default: 0). Used for stylus input.
TYPE:
|
tilt_x
|
The plane angle between the Y-Z plane and the plane containing both the stylus axis and the Y axis, in degrees of the range [-90,90]. A positive tiltX is to the right (default: 0).
TYPE:
|
tilt_y
|
The plane angle between the X-Z plane and the plane containing both the stylus axis and the X axis, in degrees of the range [-90,90]. A positive tiltY is towards the user (default: 0).
TYPE:
|
twist
|
The clockwise rotation of a pen stylus around its own major axis, in degrees in the range [0,359] (default: 0).
TYPE:
|
delta_x
|
X delta in CSS pixels for mouse wheel event (default: 0). Positive values scroll right.
TYPE:
|
delta_y
|
Y delta in CSS pixels for mouse wheel event (default: 0). Positive values scroll up.
TYPE:
|
pointer_type
|
Pointer type (default: "mouse"). Allowed values: "mouse", "pen".
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to dispatch the mouse event.
TYPE:
|
staticmethod
Generates a command to dispatch a touch event to the page.
This method allows simulating touch interactions on touch-enabled devices or emulated touch environments.
| PARAMETER | DESCRIPTION |
|---|---|
type
|
Type of the touch event. Allowed values: - touchStart: Touch started - at least one point must be specified - touchEnd: Touch ended - points that are no longer pressed should be removed - touchMove: Touch moved - active points should be updated - touchCancel: Touch canceled - clears all touch points Touch end and cancel events must not contain any touch points, while touch start and move must contain at least one.
TYPE:
|
touch_points
|
list of active touch points. One event per any changed point (compared to previous event) is generated, emulating pressing/moving/releasing points one by one. Each point includes coordinates and other properties.
TYPE:
|
modifiers
|
Bit field representing pressed modifier keys. Values: Alt=1, Ctrl=2, Meta/Command=4, Shift=8 (default: 0).
TYPE:
|
timestamp
|
Time at which the event occurred, in seconds since epoch.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to dispatch the touch event.
TYPE:
|
staticmethod
Generates a command to ignore input events (useful while auditing page).
When enabled, all input events will be ignored, which can be useful during automated tests or when you want to prevent user interaction while performing certain operations.
| PARAMETER | DESCRIPTION |
|---|---|
enabled
|
If true, input events processing will be ignored.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to set ignore input events.
TYPE:
|
staticmethod
Generates a command to dispatch a drag event into the page.
This experimental method allows simulating drag and drop operations by dispatching drag events at specific coordinates.
| PARAMETER | DESCRIPTION |
|---|---|
type
|
Type of the drag event. Allowed values: - dragEnter: Fired when a dragged item enters a valid drop target - dragOver: Fired when a dragged item is being dragged over a valid drop target - drop: Fired when an item is dropped on a valid drop target - dragCancel: Fired when a drag operation is being canceled
TYPE:
|
x
|
X coordinate of the event relative to the main frame's viewport in CSS pixels.
TYPE:
|
y
|
Y coordinate of the event relative to the main frame's viewport in CSS pixels. 0 refers to the top of the viewport, and Y increases going down.
TYPE:
|
data
|
Drag data containing items being dragged, their MIME types, and other information.
TYPE:
|
modifiers
|
Bit field representing pressed modifier keys. Values: Alt=1, Ctrl=2, Meta/Command=4, Shift=8 (default: 0).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to dispatch the drag event.
TYPE:
|
staticmethod
emulate_touch_from_mouse_event(type, x, y, button, timestamp=None, delta_x=None, delta_y=None, modifiers=None, click_count=None)
Generates a command to emulate touch event from the mouse event parameters.
This experimental method allows converting mouse events into touch events, useful for testing touch interactions in environments where touch is not available.
| PARAMETER | DESCRIPTION |
|---|---|
type
|
Type of the mouse event to convert. Allowed values: - mousePressed: Converted to touchStart - mouseReleased: Converted to touchEnd - mouseMoved: Converted to touchMove - mouseWheel: May trigger scrolling
TYPE:
|
x
|
X coordinate of the mouse pointer in device-independent pixels (DIP).
TYPE:
|
y
|
Y coordinate of the mouse pointer in DIP.
TYPE:
|
button
|
Mouse button. Only "none", "left", "right" are supported.
TYPE:
|
timestamp
|
Time at which the event occurred, in seconds since epoch. Default is current time.
TYPE:
|
delta_x
|
X delta in DIP for mouse wheel event (default: 0). Used for scrolling.
TYPE:
|
delta_y
|
Y delta in DIP for mouse wheel event (default: 0). Used for scrolling.
TYPE:
|
modifiers
|
Bit field representing pressed modifier keys. Values: Alt=1, Ctrl=2, Meta/Command=4, Shift=8 (default: 0).
TYPE:
|
click_count
|
Number of times the mouse button was clicked (default: 0). For example, 2 for a double-click.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to emulate touch from mouse event.
TYPE:
|
staticmethod
ime_set_composition(text, selection_start, selection_end, replacement_start=None, replacement_end=None)
Generates a command to set the current candidate text for IME.
This experimental method sets the text for Input Method Editors (IME), which are used for entering characters in languages that require more keystrokes than the number of characters (like Chinese, Japanese, Korean).
Use imeCommitComposition to commit the final text. Use imeSetComposition with empty string as text to cancel composition.
| PARAMETER | DESCRIPTION |
|---|---|
text
|
The text to insert as the IME composition.
TYPE:
|
selection_start
|
Start position of the selection within the composition text.
TYPE:
|
selection_end
|
End position of the selection within the composition text.
TYPE:
|
replacement_start
|
Start position of the text to be replaced (default: same as selection_start).
TYPE:
|
replacement_end
|
End position of the text to be replaced (default: same as selection_end).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to set IME composition.
TYPE:
|
staticmethod
Generates a command to emulate inserting text that doesn't come from a key press.
This experimental method is useful for inserting text that would normally come from sources other than keyboard, such as emoji pickers, IMEs, or clipboard pastes.
| PARAMETER | DESCRIPTION |
|---|---|
text
|
The text to insert.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to insert text.
TYPE:
|
staticmethod
Generates a command to control interception of drag and drop events.
This experimental method prevents default drag and drop behavior and instead emits Input.dragIntercepted events. Drag and drop behavior can then be directly controlled via Input.dispatchDragEvent.
This is useful for implementing custom drag and drop logic or for testing drag and drop behavior in automated tests.
| PARAMETER | DESCRIPTION |
|---|---|
enabled
|
If true, drag events will be intercepted and reported as dragIntercepted events, preventing the default behavior.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to set drag interception.
TYPE:
|
staticmethod
Generates a command to synthesize a pinch gesture over a time period.
This experimental method creates a synthetic pinch gesture (zoom in/out) by issuing appropriate touch events over time. This is useful for testing pinch-to-zoom functionality in web applications.
| PARAMETER | DESCRIPTION |
|---|---|
x
|
X coordinate of the start of the gesture in CSS pixels.
TYPE:
|
y
|
Y coordinate of the start of the gesture in CSS pixels.
TYPE:
|
scale_factor
|
Relative scale factor after zooming: - >1.0 zooms in (fingers moving apart) - <1.0 zooms out (fingers moving together)
TYPE:
|
relative_speed
|
Relative pointer speed in pixels per second (default: 800). Controls how fast the gesture happens.
TYPE:
|
gesture_source_type
|
Which type of input events to be generated: - 'default': Platform's preferred input type - 'touch': Touch input - 'mouse': Mouse input
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to synthesize a pinch gesture.
TYPE:
|
staticmethod
synthesize_scroll_gesture(x, y, x_distance=None, y_distance=None, x_overscroll=None, y_overscroll=None, prevent_fling=None, speed=None, gesture_source_type=None, repeat_count=None, repeat_delay_ms=None, interaction_marker_name=None)
Generates a command to synthesize a scroll gesture over a time period.
This experimental method creates a synthetic scroll gesture by issuing appropriate touch events over time. This is useful for testing scrolling behavior in web applications.
| PARAMETER | DESCRIPTION |
|---|---|
x
|
X coordinate of the start of the gesture in CSS pixels.
TYPE:
|
y
|
Y coordinate of the start of the gesture in CSS pixels.
TYPE:
|
x_distance
|
The distance to scroll along the X axis (positive to scroll left).
TYPE:
|
y_distance
|
The distance to scroll along the Y axis (positive to scroll up).
TYPE:
|
x_overscroll
|
The number of additional pixels to scroll back along the X axis, in addition to the given distance. This creates an overscroll effect (rubber-banding).
TYPE:
|
y_overscroll
|
The number of additional pixels to scroll back along the Y axis, in addition to the given distance. This creates an overscroll effect (rubber-banding).
TYPE:
|
prevent_fling
|
Prevent fling (default: true). If false, a fling animation might continue after the gesture.
TYPE:
|
speed
|
Swipe speed in pixels per second (default: 800).
TYPE:
|
gesture_source_type
|
Which type of input events to be generated: - 'default': Platform's preferred input type - 'touch': Touch input - 'mouse': Mouse input
TYPE:
|
repeat_count
|
The number of times to repeat the gesture (default: 0).
TYPE:
|
repeat_delay_ms
|
The number of milliseconds delay between each repeat (default: 250).
TYPE:
|
interaction_marker_name
|
The name of the interaction markers to generate, if not empty. Used for tracking gesture timing in performance measurements.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to synthesize a scroll gesture.
TYPE:
|
staticmethod
Generates a command to synthesize a tap gesture over a time period.
This experimental method creates a synthetic tap gesture by issuing appropriate touch events over time. This is useful for testing touch interaction in web applications.
| PARAMETER | DESCRIPTION |
|---|---|
x
|
X coordinate of the start of the gesture in CSS pixels.
TYPE:
|
y
|
Y coordinate of the start of the gesture in CSS pixels.
TYPE:
|
duration
|
Duration between touchdown and touchup events in milliseconds (default: 50). Controls how long the tap gesture takes.
TYPE:
|
tap_count
|
Number of times to perform the tap (e.g., 2 for a double tap, default: 1).
TYPE:
|
gesture_source_type
|
Which type of input events to be generated: - 'default': Platform's preferred input type - 'touch': Touch input - 'mouse': Mouse input
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Command
|
The CDP command to synthesize a tap gesture.
TYPE:
|
Usage
Input commands are used by element interaction methods and can be used directly for advanced input scenarios:
from pydoll.commands.input_commands import dispatch_mouse_event, dispatch_key_event
from pydoll.connection.connection_handler import ConnectionHandler
# Simulate mouse click
connection = ConnectionHandler()
await dispatch_mouse_event(
connection,
type="mousePressed",
x=100,
y=200,
button="left"
)
# Simulate keyboard typing
await dispatch_key_event(
connection,
type="keyDown",
key="Enter"
)
Key Functionality
The input commands module provides functions for:
Mouse Events
dispatch_mouse_event()- Mouse clicks, movements, and wheel events- Mouse button states (left, right, middle)
- Coordinate-based positioning
- Drag and drop operations
Keyboard Events
dispatch_key_event()- Key press and release eventsinsert_text()- Direct text insertion- Special key handling (Enter, Tab, Arrow keys, etc.)
- Modifier keys (Ctrl, Alt, Shift)
Touch Events
- Touch screen simulation
- Multi-touch gestures
- Touch coordinates and pressure
Human-like Behavior
The input commands support human-like behavior patterns:
- Natural mouse movement curves
- Realistic typing speeds and patterns
- Random micro-delays between actions
- Pressure-sensitive touch events
Element Methods
For most use cases, use the higher-level element methods like element.click() and element.type_text() which provide a more convenient API and handle common scenarios automatically.