Overview#

omni.kit.test_suite.helpers is a set of internal helper functions and classes designed to support test automation within the Omniverse Kit SDK. It provides utility methods to manage asynchronous UI updates, monitor USD stage events, and control test-related window arrangements and dialogs. The extension helps tests verify that stages are loaded correctly, prims are selected or excluded as needed, and user interfaces are arranged for consistent test execution.

Concepts#

The extension focuses on synchronizing test workflows with stage events and asynchronous UI behaviors. Key concepts include:

Waiting for asynchronous operations such as UI refreshes or stage loading.
Managing USD stage state and prim selections.
Handling material dialogs and multiple descendents in a consistent test environment.

Functionality#

Asynchronous Waiting: Functions like wait, wait_stage_loading, and wait_for_viewport_ready enable tests to pause until certain operations complete. This helps ensure that the stage or viewport is in the expected state before proceeding.
Stage and Prim Management: The open_stage, select_prims, and get_prims APIs allow tests to load stages and traverse or manipulate prims while excluding irrelevant ones. The StageEventHandler class provides a mechanism to await specific stage events, ensuring reliable stage state tracking.
Window and Dialog Controls: Methods such as wait_for_window, arrange_windows, and functions for pushing/popping window heights help manage the UI environment during tests. Additionally, experimental dialog handling functions (e.g. handle_assign_material_dialog and handle_create_material_dialog) support automating material-related interactions, even though some are marked as deprecated or legacy.
Auxiliary Utilities: The get_random_material_list functions help in retrieving test-related data, such as asset frame details and material selections, to streamline test case implementations.

Relationships#

Dependencies: This extension relies on core modules like omni.usd, omni.kit.ui_test, and omni.kit.viewport.utility. These dependencies ensure proper stage interactions and viewport management during test execution.
Test Environment Integration: Designed for use within internal test suites, the extension provides essential primitives to synchronize and validate stage states and UI configurations in a consistent and predictable manner.

Considerations#

Some APIs related to dialog handling and window height management are marked as deprecated. Users should be aware of these constraints when integrating the helpers into new test suites.
As this extension is meant for internal testing, the provided interfaces emphasize practical synchronization and state verification rather than extensive customization or production usage.