Tests: Armor OpenOrCreateDialog.wait_for() to be more robust against MainWindow being left open

Author: davidfstr

RELEASE_NOTES.md

@@ -69,6 +69,10 @@ and new `--port`/`--host` options for controlling how projects are served.
       to refer to when making autonomous changes to Crystal.
     * Decrease average cost of CI runs by running fewer macOS jobs by default.
 
+* Testing improvements
+    * Automated tests will now recover gracefully if a previous failed test
+      left a MainWindow open.
+
 ### v1.10.0 (June 21, 2025)
 
 This release contains significant usability improvements: Reopening a project

src/crystal/tests/index.py

@@ -8,7 +8,7 @@
     test_icons, test_install_to_desktop, test_load_urls, test_log_drawer,
     test_menus, test_new_group, test_new_root_url, test_open_project,
     test_parse_html, test_profile, test_project_migrate, test_readonly_mode,
-    test_server, test_shell, test_ssd, test_tasks, test_tasktree,
+    test_runner, test_server, test_shell, test_ssd, test_tasks, test_tasktree,
     test_untitled_projects,
     test_workflows, test_xthreading,
 )
@@ -68,6 +68,7 @@ def _test_functions_in_module(mod) -> list[Callable]:
     _test_functions_in_module(test_profile) +
     _test_functions_in_module(test_project_migrate) +
     _test_functions_in_module(test_readonly_mode) +
+    _test_functions_in_module(test_runner) +
     _test_functions_in_module(test_server) +
     _test_functions_in_module(test_shell) +
     _test_functions_in_module(test_ssd) +

src/crystal/tests/test_runner.py

@@ -0,0 +1,35 @@
+"""
+Tests for Crystal's test runner functionality.
+
+These tests verify that the test infrastructure itself works correctly,
+including error recovery mechanisms, and test utilities.
+"""
+
+from contextlib import redirect_stderr
+from crystal.tests.util.asserts import assertIn
+from crystal.tests.util.windows import OpenOrCreateDialog
+import io
+
+
+# === OpenOrCreateDialog Tests ===
+
+async def test_when_main_window_left_open_then_ocd_wait_for_does_recover_gracefully() -> None:
+    # Intentionally leave a MainWindow open, simulating a test failure
+    ocd1 = await OpenOrCreateDialog.wait_for()
+    main_window = await ocd1.create_and_leave_open()
+    
+    # Wait for an OpenOrCreateDialog to appear, simulating a newly started test.
+    # But it won't appear because the MainWindow is still open.
+    # OpenOrCreateDialog should detect this and attempt to recover automatically.
+    # 
+    # The recovery mechanism should:
+    # 1. Detect that a MainWindow is open
+    # 2. Print a warning message
+    # 3. Close the MainWindow (handling any "Do you want to save?" dialog)
+    # 4. Wait for the OpenOrCreateDialog to appear
+    with redirect_stderr(io.StringIO()) as captured_stderr:
+        ocd2 = await OpenOrCreateDialog.wait_for(timeout=1.0)
+    assertIn(
+        'WARNING: OpenOrCreateDialog.wait_for() noticed that a MainWindow was left open',
+        captured_stderr.getvalue()
+    )

src/crystal/tests/util/windows.py

@@ -17,13 +17,15 @@
     WaitTimedOut, window_condition, window_disposed_condition,
 )
 import crystal.tests.util.xtempfile as xtempfile
+from crystal.util.wx_dialog import mocked_show_modal
 from crystal.util.xos import is_mac_os
 import os.path
 import re
 import sys
 import tempfile
 import traceback
 from typing import TYPE_CHECKING
+from unittest.mock import patch
 import wx
 
 if TYPE_CHECKING:
@@ -43,13 +45,55 @@ class OpenOrCreateDialog:
     create_button: wx.Button
 
     @staticmethod
-    async def wait_for(timeout: float | None=None) -> OpenOrCreateDialog:
+    async def wait_for(timeout: float | None=None, *, _attempt_recovery: bool=True) -> OpenOrCreateDialog:
         self = OpenOrCreateDialog(ready=True)
-        open_or_create_project_dialog = await wait_for(
-            window_condition('cr-open-or-create-project'),
-            timeout=timeout,
-            stacklevel_extra=1,
-        )  # type: wx.Window
+        try:
+            open_or_create_project_dialog = await wait_for(
+                window_condition('cr-open-or-create-project'),
+                timeout=timeout,
+                stacklevel_extra=1,
+            )  # type: wx.Window
+        except WaitTimedOut as e:
+            if _attempt_recovery:
+                # Check if a MainWindow is open from a previous failed test
+                try:
+                    main_window: wx.Window = await wait_for(
+                        window_condition('cr-main-window'),
+                        # Short timeout. Check whether a MainWindow is open.
+                        timeout=0.1,
+                        # Attribute failure to this recovery logic
+                        stacklevel_extra=0,
+                    )
+                    assert isinstance(main_window, wx.Frame)
+                    
+                    print(
+                        'WARNING: OpenOrCreateDialog.wait_for() noticed that '
+                        'a MainWindow was left open. '
+                        'Did a previous test fail to close it?',
+                        file=sys.stderr
+                    )
+
+                    # 1. Try to close MainWindow that is open
+                    # 2. If prompted whether to save the project, answer no
+                    with patch('crystal.browser.ShowModal',
+                            mocked_show_modal('cr-save-changes-dialog', wx.ID_NO)):
+                        main_window.Close()
+                        
+                        await wait_for(
+                            window_disposed_condition('cr-main-window'),
+                            timeout=4.0,  # 2.0s isn't long enough for macOS test runners on GitHub Actions
+                            # Attribute failure to this recovery logic
+                            stacklevel_extra=0,
+                        )
+                    
+                    # Try again to wait for the OpenOrCreateDialog
+                    return await OpenOrCreateDialog.wait_for(timeout=timeout, _attempt_recovery=False)
+                except WaitTimedOut:
+                    # Recovery failed
+                    pass
+            # Raise original timeout
+            raise e from None
+        
         assert isinstance(open_or_create_project_dialog, wx.Dialog)
         self.open_or_create_project_dialog = open_or_create_project_dialog
         self.open_as_readonly = self.open_or_create_project_dialog.FindWindow(name=