Merge pull request #6227 from harvey0100/wait

Wait Module Preperation

Author: richtja

avocado/utils/wait.py

@@ -1,3 +1,10 @@
+"""Utilities for waiting for conditions to be met.
+
+This module provides utilities for polling functions until they return
+a truthy value or a timeout expires, useful for testing and development
+scenarios where you need to wait for system state changes.
+"""
+
 import logging
 import time
 
@@ -6,18 +13,75 @@
 
 # pylint: disable=R0913
 def wait_for(func, timeout, first=0.0, step=1.0, text=None, args=None, kwargs=None):
-    """
-    Wait until func() evaluates to True.
+    """Wait until a function returns a truthy value or timeout expires.
+
+    This function repeatedly calls a given function with optional arguments
+    until it returns a truthy value (anything that evaluates to True in a
+    boolean context) or until the specified timeout expires. It provides
+    configurable delays before the first attempt and between subsequent
+    attempts, making it useful for polling operations in testing and
+    development scenarios.
+
+    The function uses time.monotonic() for reliable timeout calculation that
+    is not affected by system clock adjustments. Note that the step sleep
+    duration is not interrupted when timeout expires, so actual elapsed time
+    may exceed the specified timeout by up to one step duration.
+
+    :param func: Callable to be executed repeatedly until it returns a truthy
+                 value. Can be any callable object (function, lambda, method,
+                 callable class instance).
+    :type func: callable
+    :param timeout: Maximum time in seconds to wait for func to return a
+                    truthy value. Must be a non-negative number. If timeout
+                    expires before func returns truthy, None is returned.
+    :type timeout: float or int
+    :param first: Time in seconds to sleep before the first attempt to call
+                  func. Useful when you know the condition won't be met
+                  immediately. Defaults to 0.0 (no initial delay).
+    :type first: float or int
+    :param step: Time in seconds to sleep between successive calls to func.
+                 The actual sleep happens after each failed attempt. Defaults
+                 to 1.0 second. Note that this sleep is not interrupted when
+                 timeout expires.
+    :type step: float or int
+    :param text: Optional debug message to log before each attempt. When
+                 provided, logs at DEBUG level with elapsed time since start.
+                 If None, no logging occurs. Useful for debugging wait
+                 operations.
+    :type text: str or None
+    :param args: Optional list or tuple of positional arguments to pass to
+                 func on each call. If None, defaults to empty list.
+    :type args: list, tuple, or None
+    :param kwargs: Optional dictionary of keyword arguments to pass to func on
+                   each call. If None, defaults to empty dict.
+    :type kwargs: dict or None
+    :return: The truthy return value from func if it succeeds within timeout,
+             or None if timeout expires without func returning a truthy value.
+             The actual return value from func is preserved (e.g., strings,
+             numbers, lists, objects).
+    :rtype: Any (return type of func) or None
+    :raises: Any exception raised by func will be propagated to the caller.
+             No exception handling is performed on func calls.
 
-    If func() evaluates to True before timeout expires, return the
-    value of func(). Otherwise return None.
+    Example::
 
-    :param timeout: Timeout in seconds
-    :param first: Time to sleep before first attempt
-    :param step: Time to sleep between attempts in seconds
-    :param text: Text to print while waiting, for debug purposes
-    :param args: Positional arguments to func
-    :param kwargs: Keyword arguments to func
+        >>> import os
+        >>> # Wait for a file to exist
+        >>> wait_for(lambda: os.path.exists("/tmp/myfile"), timeout=30, step=1)
+        True
+        >>> # Wait for a counter to reach threshold
+        >>> counter = [0]
+        >>> def check(): counter[0] += 1; return counter[0] >= 5
+        >>> wait_for(check, timeout=10, step=0.5)
+        True
+        >>> # Wait with custom function and arguments
+        >>> def check_value(expected, current):
+        ...     return current >= expected
+        >>> wait_for(check_value, timeout=5, step=0.1, args=[10, 15])
+        True
+        >>> # Wait with debug logging
+        >>> wait_for(lambda: False, timeout=2, step=0.5, text="Waiting for condition")
+        None
     """
     args = args or []
     kwargs = kwargs or {}

selftests/check.py

@@ -27,9 +27,9 @@
     "job-api-check-tmp-directory-exists": 1,
     "nrunner-interface": 90,
     "nrunner-requirement": 28,
-    "unit": 874,
+    "unit": 900,
     "jobs": 11,
-    "functional-parallel": 342,
+    "functional-parallel": 344,
     "functional-serial": 7,
     "optional-plugins": 0,
     "optional-plugins-golang": 2,

selftests/functional/utils/wait.py

@@ -0,0 +1,54 @@
+import os
+import threading
+import time
+import unittest
+
+from avocado.utils import wait
+from selftests.utils import TestCaseTmpDir
+
+
+class WaitForFunctionalTest(TestCaseTmpDir):
+    """Functional tests for wait.wait_for with real-world scenarios."""
+
+    def test_condition_becomes_true(self):
+        """Test wait_for with condition that eventually becomes true (real I/O)."""
+        filepath = os.path.join(self.tmpdir.name, "test_file.txt")
+
+        # Create file after a delay
+        def create_file_delayed():
+            time.sleep(0.3)
+            with open(filepath, "w", encoding="utf-8") as f:
+                f.write("test content")
+
+        # Start file creation in background
+        thread = threading.Thread(target=create_file_delayed)
+        thread.start()
+
+        # Wait for file to exist
+        result = wait.wait_for(
+            lambda: os.path.exists(filepath),
+            timeout=2.0,
+            step=0.1,
+            text="Waiting for file to appear",
+        )
+
+        thread.join()
+        self.assertTrue(result)
+        self.assertTrue(os.path.exists(filepath))
+
+    def test_timeout_when_condition_never_true(self):
+        """Test that wait_for respects timeout when condition never becomes true."""
+        filepath = os.path.join(self.tmpdir.name, "nonexistent.txt")
+
+        # Wait for a file that will never be created
+        start = time.time()
+        result = wait.wait_for(lambda: os.path.exists(filepath), timeout=0.5, step=0.1)
+        elapsed = time.time() - start
+
+        self.assertIsNone(result)
+        self.assertGreaterEqual(elapsed, 0.5)
+        self.assertLess(elapsed, 0.7)
+
+
+if __name__ == "__main__":
+    unittest.main()

selftests/unit/utils/wait.py

@@ -0,0 +1,232 @@
+import time
+import unittest
+from unittest import mock
+
+from avocado.utils import wait
+
+
+class WaitForTest(unittest.TestCase):
+    """Unit tests for wait.wait_for function."""
+
+    def test_basic_success_immediate(self):
+        """Test wait_for with function that succeeds immediately."""
+        func = mock.Mock(return_value=True)
+        result = wait.wait_for(func, timeout=5)
+        self.assertTrue(result)
+        func.assert_called_once()
+
+    def test_basic_success_with_value(self):
+        """Test wait_for returns the truthy value from function."""
+        func = mock.Mock(return_value="success")
+        result = wait.wait_for(func, timeout=5)
+        self.assertEqual(result, "success")
+
+    def test_timeout_returns_none(self):
+        """Test wait_for returns None when timeout expires."""
+        func = mock.Mock(return_value=False)
+        start = time.time()
+        result = wait.wait_for(func, timeout=0.5, step=0.1)
+        elapsed = time.time() - start
+        self.assertIsNone(result)
+        self.assertGreaterEqual(elapsed, 0.5)
+        self.assertLess(elapsed, 0.7)  # Should not wait much longer than timeout
+
+    def test_function_eventually_succeeds(self):
+        """Test wait_for succeeds when function returns True after retries."""
+        call_count = {"count": 0}
+
+        def func_on_third_call():
+            call_count["count"] += 1
+            return call_count["count"] >= 3
+
+        result = wait.wait_for(func_on_third_call, timeout=5, step=0.1)
+        self.assertTrue(result)
+        self.assertEqual(call_count["count"], 3)
+
+    def test_first_delay(self):
+        """Test wait_for respects first delay parameter."""
+        func = mock.Mock(return_value=True)
+        start = time.time()
+        wait.wait_for(func, timeout=5, first=0.2)
+        elapsed = time.time() - start
+        self.assertGreaterEqual(elapsed, 0.2)
+
+    def test_step_interval(self):
+        """Test wait_for respects step interval between attempts."""
+        func = mock.Mock(return_value=False)
+        wait.wait_for(func, timeout=0.5, step=0.15, first=0.0)
+        # Should make roughly 0.5/0.15 = 3-4 attempts
+        call_count = func.call_count
+        self.assertGreaterEqual(call_count, 3)
+        self.assertLessEqual(call_count, 5)
+
+    def test_zero_timeout(self):
+        """Test wait_for with zero timeout."""
+        func = mock.Mock(return_value=False)
+        result = wait.wait_for(func, timeout=0)
+        self.assertIsNone(result)
+
+    def test_with_positional_args(self):
+        """Test wait_for passes positional arguments to function."""
+        func = mock.Mock(return_value=True)
+        wait.wait_for(func, timeout=5, args=["arg1", "arg2", 3])
+        func.assert_called_with("arg1", "arg2", 3)
+
+    def test_with_keyword_args(self):
+        """Test wait_for passes keyword arguments to function."""
+        func = mock.Mock(return_value=True)
+        wait.wait_for(func, timeout=5, kwargs={"key1": "value1", "key2": 42})
+        func.assert_called_with(key1="value1", key2=42)
+
+    def test_with_both_args_and_kwargs(self):
+        """Test wait_for passes both positional and keyword arguments."""
+        func = mock.Mock(return_value=True)
+        wait.wait_for(
+            func, timeout=5, args=["pos1", "pos2"], kwargs={"kw1": "val1", "kw2": 99}
+        )
+        func.assert_called_with("pos1", "pos2", kw1="val1", kw2=99)
+
+    def test_text_logging(self):
+        """Test wait_for logs debug messages when text is provided."""
+        func = mock.Mock(return_value=False)
+        with self.assertLogs("avocado.utils.wait", level="DEBUG") as log_context:
+            wait.wait_for(func, timeout=0.3, step=0.1, text="Waiting for condition")
+        # Should have logged at least once
+        self.assertGreater(len(log_context.output), 0)
+        self.assertIn("Waiting for condition", log_context.output[0])
+
+    def test_no_logging_without_text(self):
+        """Test wait_for does not log when text is None."""
+        func = mock.Mock(return_value=False)
+        with self.assertRaises(AssertionError):
+            # Should not log anything
+            with self.assertLogs("avocado.utils.wait", level="DEBUG"):
+                wait.wait_for(func, timeout=0.2, step=0.1, text=None)
+
+    def test_returns_first_truthy_value(self):
+        """Test wait_for returns first truthy value encountered."""
+        values = [False, 0, None, "", "found"]
+
+        def func_with_sequence():
+            return values.pop(0)
+
+        result = wait.wait_for(func_with_sequence, timeout=5, step=0.05)
+        self.assertEqual(result, "found")
+        # Should have values left since it stopped early
+        self.assertEqual(len(values), 0)
+
+    def test_function_returns_zero(self):
+        """Test wait_for treats zero as falsy and continues waiting."""
+        func = mock.Mock(return_value=0)
+        result = wait.wait_for(func, timeout=0.2, step=0.05)
+        self.assertIsNone(result)
+        self.assertGreater(func.call_count, 1)
+
+    def test_function_returns_empty_string(self):
+        """Test wait_for treats empty string as falsy."""
+        func = mock.Mock(return_value="")
+        result = wait.wait_for(func, timeout=0.2, step=0.05)
+        self.assertIsNone(result)
+
+    def test_function_returns_list(self):
+        """Test wait_for can return list when function returns truthy list."""
+        func = mock.Mock(return_value=["item1", "item2"])
+        result = wait.wait_for(func, timeout=5)
+        self.assertEqual(result, ["item1", "item2"])
+
+    def test_function_returns_dict(self):
+        """Test wait_for can return dict when function returns truthy dict."""
+        expected = {"key": "value"}
+        func = mock.Mock(return_value=expected)
+        result = wait.wait_for(func, timeout=5)
+        self.assertEqual(result, expected)
+
+    def test_function_raises_exception(self):
+        """Test wait_for propagates exceptions from the function."""
+        func = mock.Mock(side_effect=ValueError("Test error"))
+        with self.assertRaises(ValueError) as context:
+            wait.wait_for(func, timeout=5)
+        self.assertEqual(str(context.exception), "Test error")
+
+    def test_negative_timeout(self):
+        """Test wait_for with negative timeout."""
+        func = mock.Mock(return_value=False)
+        result = wait.wait_for(func, timeout=-1)
+        self.assertIsNone(result)
+
+    def test_large_step_vs_timeout(self):
+        """Test wait_for when step is larger than timeout.
+
+        Note: The function sleeps for full step duration even if it exceeds timeout.
+        """
+        func = mock.Mock(return_value=False)
+        start = time.time()
+        result = wait.wait_for(func, timeout=0.2, step=5.0)
+        elapsed = time.time() - start
+        self.assertIsNone(result)
+        # Function will sleep for full step duration after first attempt
+        self.assertGreaterEqual(elapsed, 5.0)
+        # Should be called once before sleeping
+        self.assertEqual(func.call_count, 1)
+
+    def test_very_small_timeout(self):
+        """Test wait_for with very small timeout value."""
+        func = mock.Mock(return_value=False)
+        result = wait.wait_for(func, timeout=0.01, step=0.001)
+        self.assertIsNone(result)
+
+    def test_none_args_and_kwargs(self):
+        """Test wait_for with None values for args and kwargs."""
+        func = mock.Mock(return_value=True)
+        result = wait.wait_for(func, timeout=5, args=None, kwargs=None)
+        self.assertTrue(result)
+        func.assert_called_once_with()
+
+    def test_empty_args_and_kwargs(self):
+        """Test wait_for with empty args and kwargs."""
+        func = mock.Mock(return_value=True)
+        result = wait.wait_for(func, timeout=5, args=[], kwargs={})
+        self.assertTrue(result)
+        func.assert_called_once_with()
+
+    def test_callable_object(self):
+        """Test wait_for works with callable objects, not just functions."""
+
+        class CallableCounter:
+            def __init__(self):
+                self.count = 0
+
+            def __call__(self):
+                self.count += 1
+                return self.count >= 3
+
+        callable_obj = CallableCounter()
+        result = wait.wait_for(callable_obj, timeout=5, step=0.1)
+        self.assertTrue(result)
+        self.assertEqual(callable_obj.count, 3)
+
+    def test_lambda_function(self):
+        """Test wait_for works with lambda functions."""
+        counter = {"value": 0}
+
+        def increment():
+            counter["value"] += 1
+            return counter["value"] >= 2
+
+        result = wait.wait_for(increment, timeout=5, step=0.1)
+        self.assertTrue(result)
+
+    def test_timing_precision(self):
+        """Test wait_for timeout is reasonably accurate."""
+        func = mock.Mock(return_value=False)
+        timeout_val = 1.0
+        start = time.time()
+        wait.wait_for(func, timeout=timeout_val, step=0.1)
+        elapsed = time.time() - start
+        # Should be close to timeout (within 20% tolerance for system variance)
+        self.assertGreaterEqual(elapsed, timeout_val)
+        self.assertLess(elapsed, timeout_val * 1.2)
+
+
+if __name__ == "__main__":
+    unittest.main()