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

def __init__(self, app):

Bases: Generic[ReturnType]

Pilot object to drive an app.

app property

app: App[ReturnType]

click async

def click(
    self,
    selector=None,
    offset=(0, 0),
    shift=False,
    meta=False,
    control=False,
):

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.

Example

The code below runs an app and clicks its only button right in the middle:

async with SingleButtonApp().run_test() as pilot:
    await pilot.click(Button, offset=(8, 1))

Parameters

Parameter	Default	Description
selector type[Widget] | str | None	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.
offset tuple[int, int]	(0, 0)	The offset to click. The offset is relative to the selector provided or to the screen, if no selector is provided.
shift bool	False	Click with the shift key held down.
meta bool	False	Click with the meta key held down.
control bool	False	Click with the control key held down.

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

def exit(self, result):

Exit the app with the given result.

Parameters

Parameter	Default	Description
result ReturnType	required	The app result returned by run or run_async.

hover async

def hover(self, selector=None, offset=(0, 0)):

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

Parameter	Default	Description
selector type[Widget] | str | None | 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.
offset tuple[int, int]	(0, 0)	The offset to hover. The offset is relative to the selector provided or to the screen, if no selector is provided.

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.

mouse_down async

def mouse_down(
    self,
    selector=None,
    offset=(0, 0),
    shift=False,
    meta=False,
    control=False,
):

Simulate a MouseDown event at a specified position.

The final position for the event is computed based on the selector provided and the offset specified and it must be within the visible area of the screen.

Parameters

Parameter	Default	Description
selector type[Widget] | str | None	None	A selector to specify a widget that should be used as the reference for the event offset. If this is not specified, the offset is interpreted relative to the screen. You can use this parameter to try to target a specific widget. However, if the widget is currently hidden or obscured by another widget, the event may not land on the widget you specified.
offset tuple[int, int]	(0, 0)	The offset for the event. The offset is relative to the selector provided or to the screen, if no selector is provided.
shift bool	False	Simulate the event with the shift key held down.
meta bool	False	Simulate the event with the meta key held down.
control bool	False	Simulate the event with the control key held down.

Raises

Type	Description
OutOfBounds	If the position for the event is outside of the (visible) screen.

Returns

Type	Description
bool	True if no selector was specified or if the event landed on the selected widget, False otherwise.

mouse_up async

def mouse_up(
    self,
    selector=None,
    offset=(0, 0),
    shift=False,
    meta=False,
    control=False,
):

Simulate a MouseUp event at a specified position.

The final position for the event is computed based on the selector provided and the offset specified and it must be within the visible area of the screen.

Parameters

Parameter	Default	Description
selector type[Widget] | str | None	None	A selector to specify a widget that should be used as the reference for the event offset. If this is not specified, the offset is interpreted relative to the screen. You can use this parameter to try to target a specific widget. However, if the widget is currently hidden or obscured by another widget, the event may not land on the widget you specified.
offset tuple[int, int]	(0, 0)	The offset for the event. The offset is relative to the selector provided or to the screen, if no selector is provided.
shift bool	False	Simulate the event with the shift key held down.
meta bool	False	Simulate the event with the meta key held down.
control bool	False	Simulate the event with the control key held down.

Raises

Type	Description
OutOfBounds	If the position for the event is outside of the (visible) screen.

Returns

Type	Description
bool	True if no selector was specified or if the event landed on the selected widget, False otherwise.

pause async

def pause(self, delay=None):

Insert a pause.

Parameters

Parameter	Default	Description
delay float | None	None	Seconds to pause, or None to wait for cpu idle.

press async

def press(self, *keys):

Simulate key-presses.

Parameters

Parameter	Default	Description
*keys str	()	Keys to press.

resize_terminal async

def resize_terminal(self, width, height):

Resize the terminal to the given dimensions.

Parameters

Parameter	Default	Description
width int	required	The new width of the terminal.
height int	required	The new height of the terminal.

wait_for_animation async

def wait_for_animation(self):

Wait for any current animation to complete.

wait_for_scheduled_animations async

def wait_for_scheduled_animations(self):

Wait for any current and scheduled animations to complete.

WaitForScreenTimeout class

Bases: Exception

Exception raised if messages aren't being processed quickly enough.

If this occurs, the most likely explanation is some kind of deadlock in the app code.