Tests: Increase determinism and speed of tests that perform downloads

Author: davidfstr

RELEASE_NOTES.md

@@ -16,6 +16,9 @@ Release Notes ⋮
     * macOS 14+ is now the minimum macOS version.
       Drop support for macOS 13.
 
+* Testing improvements
+    * Increased determinism and speed of tests that perform downloads.
+
 ### v2.0.0 (September 26, 2025)
 
 Crystal 2.0 is a huge release with many new features and all-new tutorials!

src/crystal/browser/__init__.py

@@ -1242,28 +1242,33 @@ def fg_task() -> bool:
             else:
                 progress_dialog = None
 
-        # Run download() on a background thread because it can take a long time
-        # to instantiate the tree of related download tasks (when _LAZY_LOAD_CHILDREN == False)
-        # 
-        # NOTE: Loudly crashes the entire scheduler thread upon failure.
-        #       If this failure mode ends up happening commonly,
-        #       suggest implementing a less drastic failure mode.
-        @capture_crashes_to(self.project.root_task)
-        def bg_task() -> None:
-            assert selected_entity is not None
-            
+        if DownloadResourceGroupMembersTask._LAZY_LOAD_CHILDREN:
             # Start download
             selected_entity.download(needs_result=False)
-            
-            # Close progress dialog, if applicable
-            if progress_dialog is not None:
-                def fg_task() -> None:
-                    nonlocal progress_dialog
-                    assert progress_dialog is not None
-                    progress_dialog.Destroy()
-                    progress_dialog = None  # unexport
-                fg_call_and_wait(fg_task)
-        bg_call_later(bg_task)
+        else:
+            # Run download() on a background thread because it can take a long time
+            # to instantiate the tree of related download tasks 
+            # (when _LAZY_LOAD_CHILDREN == False)
+            # 
+            # NOTE: Loudly crashes the entire scheduler thread upon failure.
+            #       If this failure mode ends up happening commonly,
+            #       suggest implementing a less drastic failure mode.
+            @capture_crashes_to(self.project.root_task)
+            def bg_task() -> None:
+                assert selected_entity is not None
+                
+                # Start download
+                selected_entity.download(needs_result=False)
+                
+                # Close progress dialog, if applicable
+                if progress_dialog is not None:
+                    def fg_task() -> None:
+                        nonlocal progress_dialog
+                        assert progress_dialog is not None
+                        progress_dialog.Destroy()
+                        progress_dialog = None  # unexport
+                    fg_call_and_wait(fg_task)
+            bg_call_later(bg_task)
 
     def _on_update_group_members(self, event):
         selected_entity = self.entity_tree.selected_entity

src/crystal/tests/README.md

@@ -324,13 +324,13 @@ download.
 It's not recommended to manually wait for a download to complete using a 
 fixed timeout because they can take a highly variable amount of time to complete,
 depending on how many embedded subresources there are, among other factors.
-Instead use the `wait_for_download_to_start_and_finish` utility method,
+Instead use the `wait_for_download_task_to_start_and_finish` utility method,
 which looks for continued *progress* in a download, regardless of how long the
 total download task takes to finish:
 
 ```
-            home_ti.Expand()
-            await wait_for_download_to_start_and_finish(mw.task_tree)
+            async with wait_for_download_task_to_start_and_finish(project):
+                home_ti.Expand()
 ```
 
 ## Waiting for other things to happen

src/crystal/tests/test_do_not_download_groups.py

@@ -11,7 +11,7 @@
     assert_does_open_webbrowser_to, extracted_project,
     served_project_from_filepath,
 )
-from crystal.tests.util.tasks import wait_for_download_to_start_and_finish
+from crystal.tests.util.tasks import wait_for_download_task_to_start_and_finish
 from crystal.tests.util.wait import (
     first_child_of_tree_item_is_not_loading_condition, wait_for,
 )
@@ -34,8 +34,8 @@ async def test_when_download_html_page_then_does_not_download_embedded_resource_
         root_ti = TreeItem.GetRootItem(mw.entity_tree.window)
         home_ti = root_ti.GetFirstChild()
         assert home_ti is not None
-        home_ti.Expand()
-        await wait_for_download_to_start_and_finish(mw.task_tree)
+        async with wait_for_download_task_to_start_and_finish(project):
+            home_ti.Expand()
         assert first_child_of_tree_item_is_not_loading_condition(home_ti)()
 
         # Expand HTML page children in entity tree
@@ -60,8 +60,8 @@ async def test_then_embedded_resource_does_not_appear_in_a_hidden_embedded_clust
         root_ti = TreeItem.GetRootItem(mw.entity_tree.window)
         home_ti = root_ti.GetFirstChild()
         assert home_ti is not None
-        home_ti.Expand()
-        await wait_for_download_to_start_and_finish(mw.task_tree)
+        async with wait_for_download_task_to_start_and_finish(project):
+            home_ti.Expand()
         assert first_child_of_tree_item_is_not_loading_condition(home_ti)()
 
         # Expand HTML page children in entity tree
@@ -83,8 +83,8 @@ async def test_when_browse_to_html_page_and_browser_requests_embedded_resource_t
         home_ti = root_ti.GetFirstChild()
         assert home_ti is not None
         home_ti.SelectItem()
-        await mw.click_download_button()
-        await wait_for_download_to_start_and_finish(mw.task_tree)
+        async with wait_for_download_task_to_start_and_finish(project):
+            click_button(mw.download_button)
 
         # Start server
         home_ti.SelectItem()
@@ -104,8 +104,8 @@ async def test_given_embedded_resource_selected_in_entity_tree_when_press_downlo
         root_ti = TreeItem.GetRootItem(mw.entity_tree.window)
         home_ti = root_ti.GetFirstChild()
         assert home_ti is not None
-        home_ti.Expand()
-        await wait_for_download_to_start_and_finish(mw.task_tree)
+        async with wait_for_download_task_to_start_and_finish(project):
+            home_ti.Expand()
         assert first_child_of_tree_item_is_not_loading_condition(home_ti)()
 
         # Expand HTML page children in entity tree
@@ -119,13 +119,8 @@ async def test_given_embedded_resource_selected_in_entity_tree_when_press_downlo
         assert not comic_image_r.has_any_revisions()
 
         comic_image_r_ti.SelectItem()
-        await mw.click_download_button(
-            # NOTE: May "finish immediately" because has no embedded subresources
-            immediate_finish_ok=True)
-        await wait_for_download_to_start_and_finish(
-            mw.task_tree,
-            # NOTE: May "finish immediately" because has no embedded subresources
-            immediate_finish_ok=True)
+        async with wait_for_download_task_to_start_and_finish(project):
+            click_button(mw.download_button)
         assert comic_image_r.has_any_revisions()
 
 
@@ -137,8 +132,8 @@ async def test_given_do_not_download_group_selected_in_entity_tree_when_press_do
         home_ti = root_ti.GetFirstChild()
         assert home_ti is not None
         home_ti.SelectItem()
-        await mw.click_download_button()
-        await wait_for_download_to_start_and_finish(mw.task_tree)
+        async with wait_for_download_task_to_start_and_finish(project):
+            click_button(mw.download_button)
 
         # Expand group children in entity tree
         comic_image_rg_ti = root_ti.find_child(comic_image_rg_pattern)
@@ -151,8 +146,8 @@ async def test_given_do_not_download_group_selected_in_entity_tree_when_press_do
         assert not comic_image_r.has_any_revisions()
 
         comic_image_rg_ti.SelectItem()
-        await mw.click_download_button()
-        await wait_for_download_to_start_and_finish(mw.task_tree)
+        async with wait_for_download_task_to_start_and_finish(project):
+            click_button(mw.download_button)
         assert comic_image_r.has_any_revisions()
 
 
@@ -163,8 +158,8 @@ async def test_then_embedded_resource_in_entity_tree_appears_with_do_not_downloa
         root_ti = TreeItem.GetRootItem(mw.entity_tree.window)
         home_ti = root_ti.GetFirstChild()
         assert home_ti is not None
-        home_ti.Expand()
-        await wait_for_download_to_start_and_finish(mw.task_tree)
+        async with wait_for_download_task_to_start_and_finish(project):
+            home_ti.Expand()
         assert first_child_of_tree_item_is_not_loading_condition(home_ti)()
 
         # Expand HTML page children in entity tree

src/crystal/tests/test_download.py

@@ -7,7 +7,7 @@
 from crystal.tests.util.controls import click_button, TreeItem
 from crystal.tests.util.runner import bg_sleep
 from crystal.tests.util.server import MockHttpServer, served_project
-from crystal.tests.util.tasks import wait_for_download_to_start_and_finish
+from crystal.tests.util.tasks import wait_for_download_task_to_start_and_finish
 from crystal.tests.util.wait import DEFAULT_WAIT_PERIOD, wait_for
 from crystal.tests.util.windows import NewGroupDialog, OpenOrCreateDialog
 import crystal.tests.util.xtempfile as xtempfile
@@ -37,12 +37,11 @@ async def test_given_downloading_resource_when_start_download_resource_then_exis
         async with (await OpenOrCreateDialog.wait_for()).create() as (mw, project):
             r = Resource(project, home_url)
 
-            rr_future = r.download()
-            
-            rr_future2 = r.download()
-            assert rr_future2 is rr_future
-            
-            await wait_for_download_to_start_and_finish(mw.task_tree)
+            async with wait_for_download_task_to_start_and_finish(project):
+                rr_future = r.download()
+                
+                rr_future2 = r.download()
+                assert rr_future2 is rr_future
 
 
 # ------------------------------------------------------------------------------

src/crystal/tests/test_entitytree.py

@@ -7,7 +7,7 @@
 from crystal.tests.util.downloads import network_down
 from crystal.tests.util.runner import bg_sleep
 from crystal.tests.util.server import extracted_project, served_project
-from crystal.tests.util.tasks import wait_for_download_to_start_and_finish
+from crystal.tests.util.tasks import wait_for_download_task_to_start_and_finish
 from crystal.tests.util.wait import (
     DEFAULT_WAIT_PERIOD, first_child_of_tree_item_is_not_loading_condition,
     wait_for,
@@ -725,11 +725,11 @@ async def test_given_rr_is_downloaded_and_is_error_when_expand_rrn_then_shows_er
             with network_down():
                 r = Resource(project, home_url)
                 home_rr = RootResource(project, 'Home', r)
-                revision_future = home_rr.download()
-                while not revision_future.done():
-                    await bg_sleep(DEFAULT_WAIT_PERIOD)
-                # Wait for download to complete, including the trailing wait
-                await wait_for_download_to_start_and_finish(mw.task_tree, immediate_finish_ok=True)
+                async with wait_for_download_task_to_start_and_finish(project):
+                    revision_future = home_rr.download()
+                    while not revision_future.done():
+                        await bg_sleep(DEFAULT_WAIT_PERIOD)
+                    # (Wait for download to complete, including the trailing wait)
 
                 rr = revision_future.result()
                 assert DownloadErrorDict(
@@ -780,16 +780,15 @@ async def test_given_rr_is_downloaded_but_revision_body_missing_when_expand_rrn_
                 # TODO: In the future, block on the redownload finishing
                 #       and list the links in the redownloaded revision,
                 #       WITHOUT needing to reopen the project later
-                home_ti.Expand()
-                await wait_for(first_child_of_tree_item_is_not_loading_condition(home_ti))
-                (error_ti,) = home_ti.Children
-                assert (
-                    'Cannot list links: URL revision body is missing. Recommend delete and redownload.' ==
-                    error_ti.Text
-                )
-                
-                # Wait for redownload to complete
-                await wait_for_download_to_start_and_finish(mw.task_tree, immediate_finish_ok=True)
+                async with wait_for_download_task_to_start_and_finish(project):
+                    home_ti.Expand()
+                    await wait_for(first_child_of_tree_item_is_not_loading_condition(home_ti))
+                    (error_ti,) = home_ti.Children
+                    assert (
+                        'Cannot list links: URL revision body is missing. Recommend delete and redownload.' ==
+                        error_ti.Text
+                    )
+                    # (Wait for redownload to complete)
 
                 # Reexpand RootResourceNode and ensure the children are the same
                 home_ti.Collapse()

src/crystal/tests/test_load_urls.py

@@ -6,7 +6,7 @@
 from crystal.tests.util.server import extracted_project, served_project
 from crystal.tests.util.ssd import database_on_ssd
 from crystal.tests.util.subtests import awith_subtests, SubtestsContext
-from crystal.tests.util.tasks import wait_for_download_to_start_and_finish
+from crystal.tests.util.tasks import wait_for_download_task_to_start_and_finish
 from crystal.tests.util.wait import (
     first_child_of_tree_item_is_not_loading_condition,
     tree_has_no_children_condition, wait_for,
@@ -181,8 +181,8 @@ async def test_given_project_database_on_ssd_given_resource_group_node_selected_
                     feed_group_ti.SelectItem()
 
                     # Wait for download to start and complete
-                    await mw.click_download_button()
-                    await wait_for_download_to_start_and_finish(mw.task_tree)
+                    async with wait_for_download_task_to_start_and_finish(project):
+                        click_button(mw.download_button)
 
                     # Ensure did not show LoadUrlsProgressDialog
                     assert 0 == progress_listener_method.call_count