Testing Helpers

Rendering

urwid.testing.render_text(widget: AbstractWidget, size: _Size, *, focus: bool = False, strip: bool = False) → list[str]

Render widget and return the text of each row.

>>> from urwid import Pile, Text
>>> render_text(Text("ab cd"), (3,))
['ab ', 'cd ']
>>> render_text(Text("ab cd"), (3,), strip=True)
['ab', 'cd']
>>> render_text(Pile([Text("x")]), ())
['x']
Parameters:
  • widget – widget to render

  • size – size to render widget with: (), (cols,) or (cols, rows)

  • focus – whether widget is rendered in focus

  • strip – remove trailing whitespace from every row

Returns:

one string per canvas row, decoded with the target encoding.

urwid.testing.render_runs(widget: AbstractWidget, size: _Size, *, focus: bool = False) → list[list[tuple[Hashable, str]]]

Render widget and return each row as runs of display attribute and text.

Adjacent runs with the same attribute are merged, so the result does not depend on where the canvas splits runs for character sets or run-length encoding.

>>> from urwid import Text
>>> render_runs(Text([("bold", "Hi"), "!"]), (3,))
[[('bold', 'Hi'), (None, '!')]]
Parameters:
  • widget – widget to render

  • size – size to render widget with: (), (cols,) or (cols, rows)

  • focus – whether widget is rendered in focus

Returns:

one list of (attr, text) pairs per canvas row, the text decoded with the target encoding.

urwid.testing.attrs_for_text(widget: AbstractWidget, size: _Size, text: str, *, focus: bool = False) → frozenset[Hashable]

Render widget and return the display attributes of the runs that contain text.

Adjacent runs with the same attribute are merged first, as in render_runs(), so text is found even where the canvas splits it.

>>> from urwid import Text
>>> attrs_for_text(Text([("bold", "Hi"), " there"]), (10,), "Hi")
frozenset({'bold'})
>>> attrs_for_text(Text([("bold", "Hi"), " there"]), (10,), "Hi there")
frozenset()
Parameters:
  • widget – widget to render

  • size – size to render widget with: (), (cols,) or (cols, rows)

  • text – text to look for within one run

  • focus – whether widget is rendered in focus

Returns:

the attribute of every run containing text; empty when no single run contains it.

urwid.testing.resolve_attr(attr: Hashable, palette: Iterable[PaletteEntry], *, colors: int = 256) → AttrSpec

Return the AttrSpec a screen with palette draws display attribute attr with.

>>> resolve_attr("bold", [("bold", "dark red,bold", "default")], colors=16)
AttrSpec('dark red,bold', 'default')
Parameters:
  • attr – display attribute of a canvas run, such as one returned by render_runs()

  • palette – palette entries, as passed to MainLoop

  • colors – number of colors of the screen: 1, 16, 88, 256 or 2**24

Returns:

the attribute the screen resolves attr to; see urwid.BaseScreen.resolve_attr().

Raises:

ValueError – colors is not one of the supported numbers of colors.

urwid.testing.resolve_runs(runs: Iterable[Iterable[tuple[Hashable, str]]], palette: Iterable[PaletteEntry], *, colors: int = 256) → list[list[tuple[AttrSpec, str]]]

Resolve the attribute of every run returned by render_runs(), keeping the text.

Runs are not merged again, although two attributes may resolve to the same AttrSpec.

>>> from urwid import Text
>>> runs = render_runs(Text([("bold", "Hi"), "!"]), (3,))
>>> resolve_runs(runs, [("bold", "dark red,bold", "default")], colors=16)
[[(AttrSpec('dark red,bold', 'default'), 'Hi'), (AttrSpec('default', 'default'), '!')]]
Parameters:
  • runs – rows of (attr, text) pairs

  • palette – palette entries, as passed to MainLoop

  • colors – number of colors of the screen: 1, 16, 88, 256 or 2**24

Returns:

rows of (AttrSpec, text) pairs, in the shape of runs.

Raises:

ValueError – colors is not one of the supported numbers of colors.

Sizing checks

urwid.testing.check_sizing(widget: AbstractWidget, *, cols: int = 80, rows: int = 24) → None

Run the sizing check for each sizing mode in widget.sizing().

Warning

The check empties the canvas cache before every rendered case, so it is for tests, not for a running application.

>>> from urwid import Pile, Text
>>> check_sizing(Pile([Text("x")]))
Parameters:
Raises:

AssertionError – widget.sizing() is empty, or one of the checks fails.

urwid.testing.check_box_sizing(widget: AbstractWidget, *, cols: int = 80, rows: int = 24) → None

Check that the box widget widget renders canvases of the requested size, including degenerate sizes.

The sizes (cols, 0), (cols, 1), (0, rows), (1, rows) and (cols, rows) are rendered with focus off and on. Each canvas must have the requested columns and rows, and a cursor, when set, must lie inside it.

Warning

The check empties the canvas cache before every rendered case, so it is for tests, not for a running application.

>>> from urwid import Filler, Text
>>> check_box_sizing(Filler(Text("x")))
Parameters:
  • widget – box widget to check

  • cols – number of columns of the full size

  • rows – number of rows of the full size

Raises:

AssertionError – a canvas has the wrong size or its cursor lies outside it.

urwid.testing.check_flow_sizing(widget: AbstractFlowWidget, *, cols: int = 80) → None

Check that the flow widget widget renders as many rows as its rows() reports.

The widths 0, 1 and cols are rendered with focus off and on. Each canvas must have the requested columns and the rows widget.rows() returned before the render; in focus, its cursor must equal widget.get_cursor_coords() when the widget has that method; a cursor, when set, must lie inside it.

Warning

The check empties the canvas cache before every rendered case, so it is for tests, not for a running application.

>>> from urwid import Edit
>>> check_flow_sizing(Edit("> ", "abc"))
Parameters:
  • widget – flow widget to check

  • cols – number of columns of the full width

Raises:

AssertionError – a canvas has the wrong size or a cursor that does not match the widget.

urwid.testing.check_fixed_sizing(widget: AbstractWidget) → None

Check that the fixed widget widget renders a canvas of the size its pack(()) reports.

The widget is rendered with focus off and on; a cursor, when set, must lie inside the canvas.

Warning

The check empties the canvas cache before every rendered case, so it is for tests, not for a running application.

>>> from urwid import Text
>>> check_fixed_sizing(Text("x"))
Parameters:

widget – fixed widget to check

Raises:

AssertionError – a canvas size differs from pack(()) or its cursor lies outside it.

Input

urwid.testing.press(widget: AbstractWidget, size: _Size, *keys: str) → list[str]

Send keys to widget.keypress() in order and return the keys it did not handle.

The returned key is collected, not the sent one, since a widget may translate a key.

>>> from urwid import Edit
>>> edit = Edit("> ")
>>> press(edit, (10,), "a", "b", "esc")
['esc']
>>> edit.edit_text
'ab'
Parameters:
  • widget – widget to send the keys to

  • size – size passed to keypress()

  • keys – key names, such as "a" or "enter"

Returns:

the keys keypress() returned, in order.

urwid.testing.click(widget: AbstractWidget, size: _Size, col: int, row: int, *, button: int = 1, event: str = 'mouse press', focus: bool = True) → bool

Send one mouse event to widget.mouse_event() and return whether it was handled.

>>> from urwid import Button, MouseButton
>>> click(Button("OK"), (10,), 1, 0)
True
>>> click(Button("OK"), (10,), 1, 0, button=MouseButton.RIGHT)
False
Parameters:
  • widget – widget to send the event to

  • size – size passed to mouse_event()

  • col – column of the event, relative to the widget

  • row – row of the event, relative to the widget

  • button – mouse button number, see MouseButton

  • event – event name, such as "mouse press" or "mouse release"

  • focus – whether widget is in focus

Returns:

True when mouse_event() returned a true value.

Harness screen

class urwid.testing.ScriptedScreen(*, size: tuple[int, int] = (80, 24), inputs: Iterable[Iterable[_Input]] | None = ())

Screen without a terminal that records what is drawn and feeds scripted input to MainLoop.

MainLoop(widget, palette, screen=ScriptedScreen(...)) works with run(), which feeds one batch of inputs after every redraw and stops with ExitMainLoop once they are used up, and with process_input() plus draw_screen() called by hand.

A draw whose size, content (text and attributes) and cursor equal those of the last recorded frame is not recorded again, so canvases is the same sequence of distinct screens under every event loop, while the number of draws differs between them. Assert the frames and last_text, not a count of draws.

The input batches are consumed, so one screen scripts one run(). Alarms still pending after the last batch never fire.

inputs=None makes the screen unscripted: it feeds no input and never ends the loop. A MainLoop started on it with start() keeps serving alarms, watched files and call_from_thread() calls under VirtualClockEventLoop.run_until_idle(), and the screen still records the frames drawn. run() on it returns only when a callback raises ExitMainLoop.

>>> from urwid import Edit, Filler, MainLoop
>>> screen = ScriptedScreen(size=(6, 1), inputs=[["a", "b"], ["backspace"]])
>>> MainLoop(Filler(Edit("> ")), screen=screen).run()
>>> [frame.decoded_text for frame in screen.canvases]
[('>     ',), ('> ab  ',), ('> a   ',)]
>>> screen.last_text
['> a   ']

Create an unstarted screen.

Parameters:
  • size – (cols, rows) returned by get_cols_rows(); assign size to resize, then script a "window resize" key

  • inputs – batches of keys and mouse event tuples, one batch returned by each get_input(); None for an unscripted screen, which feeds no input and never ends the loop

Raises:

TypeError – a batch is not a sequence of keys and mouse event tuples.

canvases: list[Canvas]

distinct frames drawn, oldest first; canvases[-1] is the screen shown last

draw_count

number of draw_screen() calls, recorded or not

draw_screen(size: tuple[int, int], canvas: Canvas) → None

Record canvas unless it shows the same frame as the last one, then schedule the next input batch.

An unscripted screen schedules no input.

Parameters:
  • size – (cols, rows) the canvas was rendered for

  • canvas – canvas to show

get_cols_rows() → tuple[int, int]

Return size.

get_input(raw_keys: Literal[False] = False) → list[_Input]
get_input(raw_keys: Literal[True]) → tuple[list[_Input], list[int]]

Return the next input batch.

Parameters:

raw_keys – also return the raw key codes, which are always empty

Returns:

the batch, or (batch, []) when raw_keys is true; an unscripted screen returns an empty batch.

Raises:

ExitMainLoop – the scripted batches are used up.

hook_event_loop(event_loop: EventLoop, callback: Callable[[list[_Input], list[int]], Any]) → None

Feed the input batches to callback through alarms of event_loop, one after every draw.

An unscripted screen feeds nothing.

Parameters:
  • event_loop – event loop to schedule the batches on

  • callback – function taking the keys and the raw key codes of one batch

property last_text: list[str]

Return the text of each row of the frame drawn last.

Raises:

IndexError – nothing has been drawn yet.

size

(cols, rows) returned by get_cols_rows()

unhook_event_loop(event_loop: EventLoop) → None

Cancel a pending input batch and forget the event loop.

Parameters:

event_loop – event loop passed to hook_event_loop()

Virtual clock

class urwid.testing.VirtualClockEventLoop(*, timeout: float = 5.0)

Event loop whose alarms fire on a clock of its own, which jumps to the next alarm instead of waiting for it.

Pass it as MainLoop(..., event_loop=VirtualClockEventLoop()) to test a widget or an application that sets alarms, such as Notifications, without real delays. set_alarm_in() schedules against this clock. set_alarm_at() still takes a time.time() value, and only its offset from now counts. Alarms due together fire in the order they were set, and the loop enters idle, drawing the screen, as SelectEventLoop does.

Watched files are polled without waiting, so input, watch_pipe() and call_from_thread() work as on the select loop. The clock moves only while no watched file is readable, so a file that stays readable keeps later alarms from coming due until timeout runs out. A loop with nothing left to do but watch files waits for them in real time, up to timeout. run_until_idle() runs every pending alarm and readable file instead, and returns once none is left.

The clock is the loop’s own: code that reads time.monotonic() itself does not see it move.

>>> from urwid import MainLoop, Notifications, SolidFill
>>> event_loop = VirtualClockEventLoop()
>>> loop = MainLoop(SolidFill(), screen=ScriptedScreen(), event_loop=event_loop)
>>> notifications = Notifications(loop=loop, timeout=5)
>>> _ = notifications.notify("saved")
>>> event_loop.advance(4.9)
>>> len(notifications.notifications), event_loop.now
(1, 4.9)
>>> event_loop.advance(0.1)
>>> len(notifications.notifications)
0

Create a loop whose clock reads 0.

Parameters:

timeout – seconds of real time a run(), an advance() or a run_until_idle() may take

advance(seconds: float) → None

Move the clock seconds ahead, firing every alarm that comes due on the way.

Alarms fire in the order they come due, each with the clock at its due time, and the loop enters idle before the clock moves on. Readable watched files are served on the way, but the loop does not wait for one. Exceptions raised by the callbacks, ExitMainLoop included, reach the caller.

Parameters:

seconds – how far to move the clock; 0 fires the alarms already due

Raises:
  • ValueError – seconds is negative.

  • RuntimeError – called from a callback of an advance(), a run() or a run_until_idle() of this loop.

  • TimeoutError – the alarms still came due after timeout seconds of real time.

property now: float

Return the time of the loop’s clock, in seconds since the loop was created.

run() → None

Run the loop until a callback raises ExitMainLoop.

Raises:
  • TimeoutError – the loop still ran after timeout seconds of real time.

  • RuntimeError – no alarm is pending and no file is watched, so the loop would wait forever. Also when called from a callback of an advance(), a run() or a run_until_idle() of this loop.

run_until_idle(*, pause: float = 0.0) → None

Fire every pending alarm and serve every readable watched file, until none is left.

The clock jumps from alarm to alarm, as in advance(), and stops at the last alarm that fired. Alarms set by the callbacks fire in the same call. The loop enters idle before it returns, so a started MainLoop has drawn the screen. A watched file that is not readable is waited for only during the pauses. Exceptions raised by the callbacks, ExitMainLoop included, reach the caller.

>>> event_loop = VirtualClockEventLoop()
>>> _ = event_loop.alarm(3, lambda: event_loop.alarm(2, lambda: None))
>>> event_loop.run_until_idle()
>>> event_loop.now
5.0

A MainLoop started on an unscripted ScriptedScreen serves call_from_thread() calls and its alarms here, without run():

>>> from urwid import MainLoop, SolidFill
>>> event_loop = VirtualClockEventLoop()
>>> loop = MainLoop(SolidFill(), screen=ScriptedScreen(inputs=None), event_loop=event_loop)
>>> with loop.start():
...     loop.call_from_thread(print, "called back")
...     _ = loop.set_alarm_in(1, lambda *_: print("alarm"))
...     event_loop.run_until_idle()
called back
alarm
Parameters:

pause – seconds of real time to watch the files before each jump of the clock to the next alarm, so a worker thread polled by an alarm can hand back its result, for example through call_from_thread(); the pauses count toward timeout

Raises:
  • ValueError – pause is negative or not finite.

  • RuntimeError – called from a callback of an advance(), a run() or a run_until_idle() of this loop.

  • TimeoutError – alarms were still pending, or a file still readable, after timeout seconds of real time.