(airflow) branch main updated: Adjusted the contributors doc to include a section on sleep calls in tests (#53234)

[po...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git


The following commit(s) were added to refs/heads/main by this push:
     new 022c7e71740 Adjusted the contributors doc to include a section on sleep calls in tests (#53234)
022c7e71740 is described below

commit 022c7e717408221bce63938d57c65b3cdeb36159
Author: Dominik <10...@users.noreply.github.com>
AuthorDate: Tue Jul 15 22:51:19 2025 +0200

    Adjusted the contributors doc to include a section on sleep calls in tests (#53234)
---
 contributing-docs/testing/unit_tests.rst | 49 ++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/contributing-docs/testing/unit_tests.rst b/contributing-docs/testing/unit_tests.rst
index c15776a9632..8122e6fe9be 100644
--- a/contributing-docs/testing/unit_tests.rst
+++ b/contributing-docs/testing/unit_tests.rst
@@ -69,6 +69,55 @@ For avoid this make sure:
         with pytest.warns(AirflowProviderDeprecationWarning, match="expected warning pattern"):
             SomeDeprecatedClass(foo="bar", spam="egg")
 
+Mocking time-related functionality in tests
+-------------------------------------------
+
+Mocking sleep calls
+...................
+
+To speed up test execution and avoid unnecessary delays, you should mock sleep calls in tests or set the sleep time to 0.
+If the method you're testing includes a call to ``time.sleep()`` or ``asyncio.sleep()``, mock these calls instead.
+How to mock ``sleep()`` depends on how it's imported:
+
+* If ``time.sleep`` is imported as ``import time``:
+
+.. code-block:: python
+
+    @mock.patch("time.sleep", return_value=None)
+    def test_your_test():
+        pass
+
+* If ``sleep`` is imported directly using ``from time import sleep``:
+
+.. code-block:: python
+
+    @mock.patch("path.to.the.module.sleep", return_value=None)
+    def test_your_test():
+        pass
+
+For methods that use ``asyncio`` for async sleep calls you can proceed identically.
+
+**NOTE:** There are certain cases in which the method functioning correctly depends on actual time passing.
+In those cases the test with the mock will fail. Then it's okay to leave it unmocked.
+Use your judgment and prefer mocking whenever possible.
+
+Controlling date and time
+.........................
+
+Some features rely on the current date and time, e.g a function that generates timestamps, or passing of time.
+To test such features reliably, we use the ``time-machine`` library to control the system's time:
+
+.. code-block:: python
+
+    @time_machine.travel(datetime(2025, 3, 27, 21, 58, 1, 2345), tick=False)
+    def test_log_message(self):
+        """
+        The tested code uses datetime.now() to generate a timestamp.
+        Freezing time ensures the timestamp is predictable and testable.
+        """
+
+By setting ``tick=False``, time is frozen at the specified moment and does not advance during the test.
+If you want time to progress from a fixed starting point, you can set ``tick=True``.
 
 Airflow configuration for unit tests
 ------------------------------------