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.

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

def exit(self, result):

Exit the app with the given result.

Parameters

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

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

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

def pause(self, delay=None):

Insert a pause.

Parameters

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

press async

def press(self, *keys):

Simulate key-presses.

Parameters

Name	Type	Description	Default
*keys	str	Keys to press.	()

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.