Add 'Detect leaked widgets; in prevent segfault article

Author: Czaki

docs/blog/posts/solve_qt_segfault.md

@@ -13,6 +13,8 @@ tags:
 
 # Preventing segfaults in test suite that has Qt Tests
 
+[Updated 2029.10.09 with information about "Detect leaked widgets"]
+
 ## Motivation
 
 When providing an GUI application one needs to select GUI backend. 
@@ -228,12 +230,170 @@ For other problematic objects you can use similar approach. There are proper fix
 
 
 ### Detect leaked widgets
- 
-TBA https://github.com/napari/napari/pull/7251
+
+!!! note
+    If your test suite is small it may be much simpler to review all tests and check if all top level widgets are scheduled for deletion.
+
+With big test dataset it may be hard to detect if some widget is not scheduled for delete. 
+
+This whole section is describing set of heuristics that may help to detect such widgets, but may also lead to false positives.
+If you use some custom, complex procedure for widget deletion you may need to adjust these heuristics or meet strange errors.
+This heuristic may report some widget after many test suite runs. It means that in previous test suite runs this widget was deleted by garbage collector, but in this run it was not.
+
+!!! note 
+    If you are not expert in Qt and Python I strongly suggest to not write custom teardown procedure for widgets 
+    and just use `qtbot.add_widget` method everywhere.
+
+#### `QApplication.topLevelWidgets`
+
+The Qt provides method [`QApplication.topLevelWidgets`](https://doc.qt.io/qt-6/qapplication.html#topLevelWidgets) that returns list of all top level widgets.
+It is nice place to start searching for leaked widgets. Hoverer it has some limitations:
+
+1. It may create new python wrappers for widgets, so all methods that are monkeypatched or properties defined outside `__init__` method may not be available.
+2. Not all top level widgets are top level widgets that require teardown setup. For example, it returns `QMenu` objects that represents the main window menu bar.
+3. It returns all top level widgets, not only those that are created in test.
+
+
+Based on above info we cannot use custom attribute to mark widget as handled without defining them in constructor. 
+However, all Qt Objects have `objectName` property that stored in C++ object and is not recreated in python wrapper.
+But it is also could be used by custom code or styling, so it is not perfect.
+
+For code simplicity we will use `objectName` property to mark handled widgets.
+We will do this by subleasing `QtBot` class from `pytest-qt` plugin and overriding `addWidget` method.
+
+We will use fact that `qtbot.addWidget` allow for add custom teardown function that will be called before widget is deleted. 
+It is done by providing `before_close_func` argument to `addWidget` method. So if object added to `qtbot` 
+have `objectName` set to some value it could be changed in `before_close_func` function.
+
+We also need to define own `qtbot` fixture that will use our custom `QtBot` class.
+
+```python
+from pytestqt.qtbot import QtBot
+
+class QtBotWithOnCloseRenaming(QtBot):
+    """Modified QtBot that renames widgets when closing them in tests.
+
+    After a test ends that uses QtBot, all instantiated widgets added to
+    the bot have their name changed to 'handled_widget'. This allows us to
+    detect leaking widgets at the end of a test run, and avoid the
+    segmentation faults that often result from such leaks. [1]_
+
+    See Also
+    --------
+    `_find_dangling_widgets`: fixture that finds all widgets that have not
+    been renamed to 'handled_widget'.
+
+    References
+    ----------
+    .. [1] https://czaki.github.io/blog/2024/09/16/preventing-segfaults-in-test-suite-that-has-qt-tests/
+    """
+
+    def addWidget(self, widget, *, before_close_func=None):
+        # in QtBot implementation, the `add_widget` method is just calling `addWidget`
+        if widget.objectName() == '':
+            # object does not have a name, so we can set it
+            widget.setObjectName('handled_widget')
+            before_close_func_ = before_close_func
+        elif before_close_func is None:
+            # there is no custom teardown function,
+            # so we provide one that will set object name
+
+            def before_close_func_(w):
+                w.setObjectName('handled_widget')
+        else:
+            # user provided custom teardown function,
+            # so we need to wrap it to set object name
+
+            def before_close_func_(w):
+                before_close_func(w)
+                w.setObjectName('handled_widget')
+
+        super().addWidget(widget, before_close_func=before_close_func_)
+
+
+@pytest.fixture
+def qtbot(qapp, request):  # pragma: no cover
+    """Fixture to create a QtBotWithOnCloseRenaming instance for testing.
+
+    Make sure to call addWidget for each top-level widget you create to
+    ensure that they are properly closed after the test ends.
+
+    The `qapp` fixture is used to ensure that the QApplication is created
+    before, so we need it, even without using it directly in this fixture.
+    """
+    return QtBotWithOnCloseRenaming(request)
+```
+
+!!! note
+    As I expect that many readers of this blog post may be maintainers of napari plugins, 
+    the code bellow contains parts specific to the napari project. They are marked with a comment.
+    If you are not a napari plugin maintainer, you can remove these parts.
+
+The bellow fixture is implementing our heuristic to detect leaked widgets.
+It looks for all top level widgets that are not children of any other widget and have not been renamed to `handled_widget`.
+Then raises an exception with a list of such widgets.
+
+
+```python
+@pytest.fixture(autouse=True)
+def _find_dangling_widgets(request, qtbot):
+    yield
+
+    from qtpy.QtWidgets import QApplication
+
+    from napari._qt.qt_main_window import _QtMainWindow
+
+    top_level_widgets = QApplication.topLevelWidgets()
+
+    viewer_weak_set = getattr(request.node, '_viewer_weak_set', set())
+    # viewer_weak_set is used to store weak references to napari viewers
+    # it is required if you use `make_napari_viewer` fixture in your tests
+
+    problematic_widgets = []
+
+    for widget in top_level_widgets:
+        if widget.parent() is not None:
+            # if it has a parent, then it is enough to schedule the parent for deletion
+            continue
+        if (
+            isinstance(widget, _QtMainWindow)
+            and widget._qt_viewer.viewer in viewer_weak_set
+        ):
+            # this if is for napari viewer created using 
+            # make_napari_viewer fixture
+            continue
+
+        if widget.__class__.__module__.startswith('qtconsole'):
+            # this is for jupyter qtconsole
+            # we do not found yet how to properly handle some of widgets in it
+            continue
+
+        if widget.objectName() == 'handled_widget':
+            continue
+
+        problematic_widgets.append(widget)
+
+    if problematic_widgets:
+        text = '\n'.join(
+            f'Widget: {widget} of type {type(widget)} with name {widget.objectName()}'
+            for widget in problematic_widgets
+        )
+    
+        for widget in problematic_widgets:
+            # we set here object name to not raise exception in next test
+            widget.setObjectName('handled_widget')
+
+        raise RuntimeError(f'Found dangling widgets:\n{text}')
+
+```
+'
+<!-- TBA https://github.com/napari/napari/pull/7251 -->
 
 
 ## Bonus tip
 
+### Test hanging due to nested event loop
+
 Your tests are hanging, but any above solution did not help. What to do?
 
 One of the possible reason is that your code is created some nested event loop by opening [`QDialog`](https://doc.qt.io/qt-6/qdialog.html)