Test interaction arising from use of UITester

[mdickinson]

This is a boiled-down version of a test interaction seen on a real project using TraitsUI and the UITester.

The test class has three tests: test1, test2 and test3, with test3 identical to test1. When run on my machine, the tests run in the order test1, test2, test3. But test1 passes, while test3 logs an exception (though it also passes), so either there's some source of non-determinism in test1 / test3, or something about test2 is altering global state.

Most of the ingredients here seem to be essential to reproducing the interaction, including the UITester, the FileEditor, the GuiTestAssistant and the ProgressEditor.

Here's the script:

import unittest
from pathlib import Path

from pyface.ui.qt.util.gui_test_assistant import GuiTestAssistant
from traits.api import Directory, Enum, HasStrictTraits, Instance, Int, observe
from traits.observation.events import TraitChangeEvent
from traitsui.api import ProgressEditor, UItem, View
from traitsui.testing.api import UITester


class ProgressBar(HasStrictTraits):
    value = Int()
    traits_view = View(UItem("value", editor=ProgressEditor()))


class Model1(HasStrictTraits):
    directory = Directory()
    model_directory = Instance(Path)
    state = Enum(["Idle", "Refreshing"])

    @observe("model_directory")
    def _refresh(self, event: TraitChangeEvent) -> None:
        if self.state != "Idle":
            raise RuntimeError("Cannot refresh when not in idle state.")
        self.state = "Refreshing"

    @observe("directory")
    def _update_model_directory(self, event: TraitChangeEvent) -> None:
        self.model_directory = Path(self.directory)

    traits_view = View(UItem("directory", enabled_when=f"state == 'Idle'"))


class Model2(HasStrictTraits):
    progress_bar = Instance(ProgressBar, ())
    traits_view = View(UItem("progress_bar", style="custom"))


class TestModels(GuiTestAssistant, unittest.TestCase):
    def test1(self) -> None:
        view = Model1()
        with UITester(auto_process_events=False).create_ui(view):
            view.directory = Path.cwd()

    def test2(self) -> None:
        view = Model2()
        with UITester(auto_process_events=False).create_ui(view):
            pass

    def test3(self) -> None:
        view = Model1()
        with UITester(auto_process_events=False).create_ui(view):
            view.directory = Path.cwd()

Here's the output on my machine (macOS/M3, EDM environment, Python 3.11.14, TraitsUI 8.0.0-3, traits 7.1.0-1, pyside6 6.10.0-2)

~/Desktop % edm run -e testenv -- python -m unittest -v weird_test.py
test1 (weird_test.TestModels.test1) ... ok
test2 (weird_test.TestModels.test2) ... ok
test3 (weird_test.TestModels.test3) ... Exception occurred in traits notification handler for event object: TraitChangeEvent(object=<weird_test.Model1 object at 0x114ef4810>, name='model_directory', old=PosixPath('/Users/mdickinson/Desktop'), new=PosixPath('.'))
Traceback (most recent call last):
  File "/Users/mdickinson/.edm/envs/testenv/lib/python3.11/site-packages/traits/observation/_trait_event_notifier.py", line 122, in __call__
    self.dispatcher(handler, event)
  File "/Users/mdickinson/.edm/envs/testenv/lib/python3.11/site-packages/traits/observation/observe.py", line 43, in dispatch_same
    handler(event)
  File "/Users/mdickinson/Desktop/weird_test.py", line 24, in _refresh
    raise RuntimeError("Cannot refresh when not in idle state.")
RuntimeError: Cannot refresh when not in idle state.
ok

----------------------------------------------------------------------
Ran 3 tests in 0.377s

OK

[mdickinson]

After running into this in a few more places, I suspect this of being primarily a bug in the FileEditor.

[mdickinson]

The following text was AI-generated (OpenCode / Claude Opus 4.6), and was the result of me asking for an investigation into the issue.

---

Root Cause Analysis

After tracing through the code, here's what I believe is happening.

Setup

The model has:

• directory = Directory() — the user-facing trait
• model_directory = Directory() — internal copy
• state = Str("Idle")
• @observe("directory") → _update_model_directory: sets model_directory = Path(directory)
• @observe("model_directory") → _refresh: checks state == "Idle", sets state = "Refreshing", does work, sets state = "Idle"

The View has enabled_when="state == 'Idle'" on the directory Item. The DirectoryEditor (a FileEditor subclass) has auto_set = False (see traitsui/editors/file_editor.py:50), so the Qt SimpleEditor connects QLineEdit.editingFinished to update_object (see traitsui/qt/file_editor.py:71).

Handler registration order

This is the crux of the problem. When the UI is created, the various notification handlers end up registered in a specific order on the model's directory trait's notifier list:

1. @observe("directory") → _update_model_directory — registered during the model's __init__ (by _init_trait_observers in ctraits.c:741), which appends a TraitEventNotifier to the trait's notifier list.

2. _update_editor — registered later, during Editor.prepare() via a dynamic on_trait_change call (traitsui/editor.py:248-249). Since the model object already exists, this handler is appended after the @observe handler.

For the state trait, _evaluate_when is registered as an anytrait handler via object.on_trait_change(self._evaluate_when, dispatch="ui") at traitsui/ui.py:440. Anytrait handlers go into the object-level notifier list (onotifiers), which fires after all trait-level notifiers (tnotifiers). On the main thread, dispatch="ui" is synchronous.

The notification chain when directory = Path.cwd() is set

Here's the exact sequence of events in test3:

Step 1: view.directory = Path.cwd() is called. The value is written to the object's __dict__. Then notifiers fire in list order.

Step 2: First notifier: @observe("directory") → _update_model_directory fires. This sets model_directory = Path(cwd).

Step 3: Inside step 2, model_directory changes. Its notifiers fire:

• @observe("model_directory") → _refresh fires. This sets state = "Refreshing".

Step 4: Inside step 3, state changes. Its notifiers fire:

• The onotifier _evaluate_when fires (registered as an anytrait handler). Since we're on the main thread, dispatch="ui" is synchronous.

Step 5: _evaluate_when → _do_evaluate_when → _evaluate_condition evaluates enabled_when="state == 'Idle'". Since state == "Refreshing", this is False. The editor's enabled was True, so it sets editor.enabled = False.

Step 6: editor.enabled = False triggers _enabled_changed (traitsui/qt/editor.py:83) → _enabled_changed_helper → self.control.setEnabled(False). The control is the parent QWidget (traitsui/qt/file_editor.py:56). Disabling the parent propagates to the child QLineEdit.

Step 7: If the QLineEdit has focus, disabling it causes it to lose focus, which triggers the editingFinished signal.

Step 8: editingFinished → update_object() (traitsui/qt/file_editor.py:96-106). This reads self._file_name.text(). But _update_editor (the handler that updates the QLineEdit text to reflect the new directory value) has not yet been called — it's later in the notifier list (registered after @observe). The QLineEdit still shows its old/stale text (empty string "" for a fresh editor).

Step 9: update_object sets self.value = file_name (the stale empty string). This property setter sets the model trait, so effectively directory = "".

Step 10: Traits allows re-entrant trait sets — there are no re-entrancy guards (confirmed in ctraits.c's setattr_trait, which writes the value and calls call_notifiers without any depth check). So a new notification chain fires depth-first:

• @observe("directory") → _update_model_directory fires again → sets model_directory = Path("") = PosixPath(".")
• @observe("model_directory") → _refresh fires, but state is still "Refreshing" (from step 3, which hasn't finished yet) → RuntimeError: _refresh called when state != 'Idle'

Why test1 passes but test3 fails

The entire mechanism depends on whether the QLineEdit has focus at the moment setEnabled(False) is called (step 7). editingFinished is only emitted when the QLineEdit loses focus, not on disable per se — but disabling a focused widget causes focus loss.

• test1: The UI was just created. The QLineEdit does not have focus (the dialog is freshly shown, and Qt hasn't assigned focus to the line edit). setEnabled(False) does not cause focus loss, so editingFinished doesn't fire. The chain completes cleanly.

• test2: Creates and destroys a ProgressEditor. The ProgressDialog.update() calls QApplication.processEvents() (pyface/ui/qt/progress_dialog.py:165). GuiTestAssistant.tearDown() also processes the event loop. These operations process pending events and alter global window/focus state.

• test3: Identical to test1, but the global Qt focus state left behind by test2's window lifecycle means the QLineEdit receives focus when the dialog is shown. Now when setEnabled(False) is called during the notification chain, the QLineEdit loses focus → editingFinished fires → the bug manifests.

Summary

The root cause is Qt widget side-effects (signal emission from focus changes) firing during a Traits notification chain, causing re-entrant trait modifications with stale data:

1. @observe("directory") fires before _update_editor (which would update the QLineEdit text), because it was registered first.
2. Inside the @observe chain, enabled_when evaluation synchronously disables the QLineEdit.
3. If the QLineEdit has focus (test-order-dependent), disabling it triggers editingFinished, which reads stale text from the QLineEdit and writes it back to the model.
4. This re-entrant set triggers _refresh while state is already "Refreshing" → RuntimeError.

[mdickinson]

For clarity, the analysis in the comment above was AI-generated: it came from OpenCode / Claude Opus 4.6. I (actual me, Mark) haven't yet looked over it for plausibility.