fix(tests): add events_checker() fixture(#1151)

* Wait for directory reader thread to start.

* fix: add events_checker() fixture, use for tests

This makes the unit tests more reliable by allowing events to be
received in different orders and by allowing additional (non-expected)
events.

* Check for DirModifiedEvent on file create.

This matches the original test logic, before addition of the
events_checker() fixture.

* Make events_checker() validate order by default.

Rather than allow events in any order, match the order of the events as
added.  On MacOS, fsevents does not produce events in a determistic
order so allow any ordering on that platform.

* Use events_checker() as a context manager.

This reduces the code a little.  Use `ec` as the short local name of
the checker instance.

Add `verbose` argument to `events_checker()` that turns on verbose
debugging output.

* Fix lint warnings.

* Unit test fixes for MacOS.

Remove events that are sometimes not generated.

* Fix unreliable test for Window.

* Fix lint warning, improve comment.

Author: nascheme

src/watchdog/observers/winapi.py

@@ -412,6 +412,7 @@ def _run(self) -> None:
         # missed, we re-use these for each call to _run_inner().
         event_buffer = ctypes.create_string_buffer(BUFFER_SIZE)
         nbytes = DWORD()
+        self._buf_queue.put(b'')  # indicates that this thread has started
         try:
             while not self._should_stop:
                 self._run_inner(handle, event_buffer, nbytes)
@@ -430,6 +431,11 @@ def start(self) -> None:
                 return  # stop already called, do not start
             self._reader_thread = threading.Thread(target=self._run)
         self._reader_thread.start()
+        # Wait for empty bytes object, indicating reader thread has started.
+        # This reduces the time window between this method returning and the
+        # actual ReadDirectoryChangesW() call, which reduces the time that
+        # events could be missed.
+        _ = self._buf_queue.get(timeout=2)
 
     def stop(self) -> None:
         with self._lock:

tests/conftest.py

@@ -8,7 +8,7 @@
 
 import pytest
 
-from .utils import ExpectEvent, Helper, P, StartWatching, TestEventQueue
+from .utils import EventsChecker, ExpectEvent, Helper, P, StartWatching, TestEventQueue
 
 
 @pytest.fixture
@@ -78,3 +78,8 @@ def start_watching_fixture(helper: Helper) -> StartWatching:
 @pytest.fixture(name="expect_event")
 def expect_event_fixture(helper: Helper) -> ExpectEvent:
     return helper.expect_event
+
+
+@pytest.fixture(name="events_checker")
+def events_checker_fixture(helper: Helper) -> EventsChecker:
+    return helper.events_checker