Skip to content

UI Tests

Overview

Most tests of Blender's functionality to prevent regressions can be achieved by other sections in the handbook. That being said, there are still some broad categories that benefit from running in an actual window. Undo integration, modal operators, and interacting with menus, panels, and buttons are all possible and appropriate to test with UI tests.

This category of tests runs by having a Blender window open and simulating mouse and keyboard events using the --event-simulate command line option.

Categories

Type File
Undo Tests tests/python/ui_simulate/test_undo.py

Example

def duplicate_cube():
    e, t = _test_vars(window := _test_window())
    yield from _view3d_startup_area_maximized(e)

    yield from _call_menu(e, "Add -> Mesh -> Cube")

    yield e.shift.d()
    t.assertEqual(len(window.view_layer.objects), 2)

The test runner expects yield statements to construct events that are sent to the running instance. These are commonly constructed via the e variable, a fluent builder defined in tests/python/ui_simulate/modules/easy_keys.py.

Standard unittest assertions are available on the t variable.

How to Run

Locally

The CMake WITH_UI_TESTS option enables running the tests, after which they will run as part of the standard test suite with make test.

Outside of make test or ctest -R, these tests can also be run with the following:

python ./tests/python/ui_simulate/run.py \
  --blender=<PATH_TO_BLENDER> \
  --tests <TEST_FILE>.<TEST_FUNCTION> \
  --keep-open

e.g.

python ./tests/python/ui_simulate/run.py \
  --blender=../build_linux/bin/blender \
  --tests test_undo.text_editor_simple \
  --keep-open

Where --keep-open prevents Blender from closing to assist in debugging.

Warning

Running these tests while doing other work can be potentially irritating, as the window will constantly steal focus as events are run on Mac and Windows. On Linux WITH_UI_TESTS_HEADLESS is enabled by default when supported using the weston compositor which avoids this issue. However, users may want to disable this to assist in troubleshooting or developing new tests.

On the Buildbot

Currently, these tests do not run on every buildbot build, as they require a graphical user environment to run. They can be requested with @blender-bot build +test_gpu_ui.

Limitations

Selecting UI Elements

It is currently not possible to select the position of UI elements based on a name or ID. Absolute coordinates can be specified, but doing so should take the following into account:

  • The tests run in a 800 by 600 window by default.
  • Tests that specify a location are sensitive to potentially unrelated UI changes.

Many operators are run via the Menu Search functionality; leading to potential breakages if there are changes to the list of operators from renaming or reordering.