Pilot
The pilot object is used by App.run_test to programmatically operate an app.
See the guide on how to test Textual apps.
OutOfBounds
class
¶
Bases: Exception
Raised when the pilot mouse target is outside of the (visible) screen.
Pilot
class
¶
Bases: Generic[ReturnType]
Pilot object to drive an app.
click
async
¶
Simulate clicking with the mouse at a specified position.
The final position to be clicked is computed based on the selector provided and the offset specified and it must be within the visible area of the screen.
Parameters
Name | Type | Description | Default |
---|---|---|---|
selector |
type[Widget] | str | None
|
A selector to specify a widget that should be used as the reference for the click offset. If this is not specified, the offset is interpreted relative to the screen. You can use this parameter to try to click on a specific widget. However, if the widget is currently hidden or obscured by another widget, the click may not land on the widget you specified. |
None
|
offset |
tuple[int, int]
|
The offset to click. The offset is relative to the selector provided or to the screen, if no selector is provided. |
(0, 0)
|
shift |
bool
|
Click with the shift key held down. |
False
|
meta |
bool
|
Click with the meta key held down. |
False
|
control |
bool
|
Click with the control key held down. |
False
|
Raises
Type | Description |
---|---|
OutOfBounds
|
If the position to be clicked is outside of the (visible) screen. |
Returns
Type | Description |
---|---|
bool
|
True if no selector was specified or if the click landed on the selected widget, False otherwise. |
exit
async
¶
Exit the app with the given result.
Parameters
Name | Type | Description | Default |
---|---|---|---|
result |
ReturnType
|
The app result returned by |
required |
hover
async
¶
Simulate hovering with the mouse cursor at a specified position.
The final position to be hovered is computed based on the selector provided and the offset specified and it must be within the visible area of the screen.
Parameters
Name | Type | Description | Default |
---|---|---|---|
selector |
type[Widget] | str | None | None
|
A selector to specify a widget that should be used as the reference for the hover offset. If this is not specified, the offset is interpreted relative to the screen. You can use this parameter to try to hover a specific widget. However, if the widget is currently hidden or obscured by another widget, the hover may not land on the widget you specified. |
None
|
offset |
tuple[int, int]
|
The offset to hover. The offset is relative to the selector provided or to the screen, if no selector is provided. |
(0, 0)
|
Raises
Type | Description |
---|---|
OutOfBounds
|
If the position to be hovered is outside of the (visible) screen. |
Returns
Type | Description |
---|---|
bool
|
True if no selector was specified or if the hover landed on the selected widget, False otherwise. |
pause
async
¶
Insert a pause.
Parameters
Name | Type | Description | Default |
---|---|---|---|
delay |
float | None
|
Seconds to pause, or None to wait for cpu idle. |
None
|
press
async
¶
wait_for_animation
async
¶
Wait for any current animation to complete.
wait_for_scheduled_animations
async
¶
Wait for any current and scheduled animations to complete.