omni.kit.ui_test¶

UI Testing Helper functions

Changelog

Usage Example:¶

# Demo:
import omni.kit.ui_test as ui_test
import omni.ui as ui

# Build some UI
window = ui.Window("Nice Window")
with window.frame:  # the frame can only have 1 widget under it
    with ui.HStack():
        ui.Label("Test1")
        with ui.VStack(width=150):
            ui.Label("Test2")
            ui.Button("TestButton", clicked_fn=on_click)

# Let UI build
await ui_test.wait_n_updates(2)

# Find a button
button = ui_test.find("Nice Window//Frame/**/Button[*]")

# Real / Unique path:
print(button.realpath)  # Nice Window//Frame/HStack[0]/VStack[0]/Button[0]

# button is a reference, actual omni.ui.Widget can be accessed:
print(type(button.widget))  # <class 'omni.ui._ui.Button'>

# Click on button
await button.click()

# Find can be nested
same_button = ui_test.find("Nice Window").find("**/Button[*]")

# Find multiple:
labels = ui_test.find_all("Nice Window//Frame/**/Label[*]")
print(labels[0].widget.text)  # Test 1
print(labels[1].widget.text)  # Test 2

API:¶

class omni.kit.ui_test.InitExt¶

on_startup()¶

class omni.kit.ui_test.KeyDownScope(key: carb.input.KeyboardInput, human_delay_speed: int = 2)¶

class omni.kit.ui_test.Vec2(*args)¶

Generic 2D Vector

Constructed from other Vec2, tuple of 2 floats or just 2 floats. Common vector operation supported:

v0 = Vec2(1, 2)
v1 = Vec2((1, 2))
v2 = Vec2(v1)

print(v0 + v1) # (2, 4)
print(v2 * 3) # (3, 6)
print(v2 / 4) # (0.25, 0.5)

to_tuple()¶

class omni.kit.ui_test.WidgetRef(widget: omni.ui._ui.Widget, path: str, window: Optional[omni.ui._ui.Window] = None)¶

Reference to omni.ui.Widget and a path it was found with.

async bring_to_front()¶: Bring window this widget belongs to on top. Currently this is implemented as undock() + focus().

property center¶: Center of the widget.

async click(pos: Optional[omni.kit.ui_test.vec2.Vec2] = None, right_click=False, double=False, human_delay_speed: int = 2)¶: Emulate mouse click on the widget.

async double_click(pos=None, human_delay_speed: int = 2)¶

async drag_and_drop(drop_target: omni.kit.ui_test.vec2.Vec2, human_delay_speed: int = 4)¶: Drag/drop for widget.centre to drop_target

find(path: str) → omni.kit.ui_test.query.WidgetRef¶

Find omni.ui Widget or Window by search query starting from this widget.

stage_window = ui_test.find("Stage//Frame/**/ScrollingFrame/TreeView[*].visible==True")
label = stage_window.find("**/Label[*].text=='hello'")
await label.right_click()

Returns: Found Widget or Window wrapped into WidgetRef object.

find_all(path: str) → List[omni.kit.ui_test.query.WidgetRef]¶

Find all omni.ui Widget or Window by search query starting from this widget.

stage_window = ui_test.find("Stage//Frame/**/ScrollingFrame/TreeView[*].visible==True")
labels = stage_window.find_all("**/Label[*]")
for label in labels:
    await label.right_click()

Returns: List of found Widget or Window wrapped into WidgetRef objects.

async focus()¶: Focus on a window this widget belongs to.

async input(text: str, end_key=KeyboardInput.ENTER, human_delay_speed: int = 2)¶

Emulate keyboard input of characters (text) into the widget.

It is a helper function for the following sequence:

Double click on the widget
Input characters
Press enter

property model¶

offset(*kwargs) → omni.kit.ui_test.vec2.Vec2¶

property path¶: Path this widget was found with.

property position¶: Screen position of widget’s top left corner.

property realpath¶: Actual unique path to this widget from the window.

async right_click(pos=None, human_delay_speed: int = 2)¶

property size¶: Computed size of the widget.

async undock()¶: Undock a window this widget belongs to.

property widget¶

property window¶

class omni.kit.ui_test.WindowRef(widget: omni.ui._ui.WindowHandle, path: str)¶

Reference to omni.ui.WindowHandle

property position¶: Screen position of widget’s top left corner.

property size¶: Computed size of the widget.

async omni.kit.ui_test.emulate_char_press(chars: str, delay_every_n_symbols: int = 20, human_delay_speed: int = 2)¶: Emulate Keyboard char input. Type N chars immediately and do a delay, then continue.

async omni.kit.ui_test.emulate_key_combo(combo: str, human_delay_speed: int = 2)¶

Emulate Keyboard key combination.

Parse string of keys separated by ‘+’ sign and treat as a key combo to emulate.

Examples: “CTRL+ENTER”, “SHIFT+ALT+Y”, “Z”

async omni.kit.ui_test.emulate_keyboard_press(key: carb.input.KeyboardInput, modifier: carb.input.KeyboardInput = 0, human_delay_speed: int = 2)¶: Emulate Keyboard key press. Down and up.

async omni.kit.ui_test.emulate_mouse_click(right_click=False, double=False)¶: Emulate Mouse single or double click.

async omni.kit.ui_test.emulate_mouse_drag_and_drop(start_pos, end_pos, right_click=False, human_delay_speed: int = 4)¶: Emulate Mouse Drag & Drop. Click at start position and slowly move to end position.

async omni.kit.ui_test.emulate_mouse_move(pos: omni.kit.ui_test.vec2.Vec2, human_delay_speed: int = 2)¶: Emulate Mouse move into position.

async omni.kit.ui_test.emulate_mouse_move_and_click(pos: omni.kit.ui_test.vec2.Vec2, right_click=False, double=False, human_delay_speed: int = 2)¶: Emulate Mouse move into position and click.

async omni.kit.ui_test.emulate_mouse_scroll(delta: omni.kit.ui_test.vec2.Vec2, human_delay_speed: int = 2)¶: Emulate Mouse scroll by delta.

omni.kit.ui_test.find(path: str) → omni.kit.ui_test.query.WidgetRef¶

Find omni.ui Widget or Window by search query. omni.ui_query is used under the hood.

Returned object can be used to get actual found item or/and do UI test operations on it.

stage_window = ui_test.find("Stage//Frame/**/ScrollingFrame/TreeView[*].visible==True")
await stage_window.right_click()

viewport = ui_test.find("Viewport")
center = viewport.center
print(center)

Returns: Found Widget or Window wrapped into WidgetRef object.

omni.kit.ui_test.find_all(path: str) → List[omni.kit.ui_test.query.WidgetRef]¶

Find all omni.ui Widget or Window by search query.

buttons = ui_test.find_all("Stage//Frame/**/Button[*]")
for button in buttons:
    await button.click()

Returns: List of found Widget or Window wrapped into WidgetRef objects.

omni.kit.ui_test.get_menubar() → omni.kit.ui_test.query.MenuRef¶

async omni.kit.ui_test.human_delay(human_delay_speed: int = 2)¶

Imitate human delay/slowness.

In practice that function just waits couple of frames, but semantically it is different from other wait function. It is used when we want to wait because it would look like normal person interaction. E.g. instead of moving mouse and clicking with speed of light wait a bit.

This is also a place where delay can be increased with a setting to debug UI tests.

async omni.kit.ui_test.menu_click(path, human_delay_speed: int = 32) → None¶

async omni.kit.ui_test.select_context_menu(menu_path: str, menu_root: Optional[omni.ui._ui.Widget] = None, offset=Vec2(100, 10), human_delay_speed: int = 4)¶

Emulate selection of context menu item with mouse.

Supports nested menus separated by /:

await ui_test.select_context_menu("Option/Select/All")

This function waits for current menu for some time first. Unless menu_root was passed explicitly. When there are nested menu mouse moves to each of them and makes human delay for it to open. Then is emulates mouse click on final menu item.

async omni.kit.ui_test.wait_n_updates(update_count=2)¶: Wait N updates (frames).