Merge remote-tracking branch 'myk002/myk_delay_until' into develop

ci/test.lua

@@ -83,6 +83,19 @@ local function delay(frames)
     script.sleep(frames, 'frames')
 end
 
+-- Will call the predicate_fn every frame until it returns true. If it fails to
+-- return true before timeout_frames have elapsed, throws an error. If
+-- timeout_frames is not specified, defaults to 100.
+local function delay_until(predicate_fn, timeout_frames)
+    timeout_frames = tonumber(timeout_frames) or 100
+    repeat
+        delay()
+        if predicate_fn() then return end
+        timeout_frames = timeout_frames - 1
+    until timeout_frames < 0
+    error('timed out while waiting for predicate to return true')
+end
+
 local function clean_require(module)
     -- wrapper around require() - forces a clean load of every module to ensure
     -- that modules checking for dfhack.internal.IN_TEST at load time behave
@@ -273,6 +286,7 @@ local function build_test_env()
         expect = {},
         mock = mock,
         delay = delay,
+        delay_until = delay_until,
         require = clean_require,
         reqscript = clean_reqscript,
     }

docs/changelog.txt

@@ -70,6 +70,7 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
 - The ``test/main`` command to invoke the test harness has been renamed to just ``test``
 - DFHack unit tests must now match any output expected to be printed via ``dfhack.printerr()``
 - Fortress mode is now supported for unit tests (allowing tests that require a fortress map to be loaded) - note that these tests are skipped by continuous integration for now, pending a suitable test fortress
+- Unit tests can now use ``delay_until(predicate_fn, timeout_frames)`` to delay until a condition is met
 
 # 0.47.05-r1