Add test coverage around startup race and missing file on startup.

Author: davidmorgan

pkgs/watcher/test/file_watcher/shared.dart renamed to pkgs/watcher/test/file_watcher/file_tests.dart

@@ -2,16 +2,20 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
+import 'dart:io';
+
 import 'package:test/test.dart';
 
 import '../utils.dart';
 
-void sharedTests() {
+void fileTests({required bool isNative}) {
+  setUp(() {
+    writeFile('file.txt');
+  });
+
   test("doesn't notify if the file isn't modified", () async {
     await startWatcher(path: 'file.txt');
-    await pumpEventQueue();
-    deleteFile('file.txt');
-    await expectRemoveEvent('file.txt');
+    await expectNoEvents();
   });
 
   test('notifies when a file is modified', () async {
@@ -70,4 +74,22 @@ void sharedTests() {
     // startWatcher awaits 'ready'
     await startWatcher(path: 'foo/bar/baz');
   });
+
+  test('throws if file does not exist', () async {
+    await startWatcher(path: 'other_file.txt');
+
+    // TODO(davidmorgan): reconcile differences.
+    if (isNative && Platform.isLinux) {
+      expect(expectNoEvents, throwsA(isA<PathNotFoundException>()));
+    } else {
+      // The polling watcher and the MacOS watcher do not throw on missing file
+      // on watch. Instead, they report both creating and modification as
+      // modifications.
+      await expectNoEvents();
+      writeFile('other_file.txt');
+      await expectModifyEvent('other_file.txt');
+      writeFile('other_file.txt');
+      await expectModifyEvent('other_file.txt');
+    }
+  });
 }

pkgs/watcher/test/file_watcher/native_test.dart

@@ -9,14 +9,10 @@ import 'package:test/test.dart';
 import 'package:watcher/src/file_watcher/native.dart';
 
 import '../utils.dart';
-import 'shared.dart';
+import 'file_tests.dart';
 
 void main() {
   watcherFactory = NativeFileWatcher.new;
 
-  setUp(() {
-    writeFile('file.txt');
-  });
-
-  sharedTests();
+  fileTests(isNative: true);
 }

pkgs/watcher/test/file_watcher/polling_test.dart

@@ -2,19 +2,14 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-import 'package:test/test.dart';
 import 'package:watcher/watcher.dart';
 
 import '../utils.dart';
-import 'shared.dart';
+import 'file_tests.dart';
 
 void main() {
   watcherFactory = (file) =>
       PollingFileWatcher(file, pollingDelay: const Duration(milliseconds: 100));
 
-  setUp(() {
-    writeFile('file.txt');
-  });
-
-  sharedTests();
+  fileTests(isNative: false);
 }

pkgs/watcher/test/file_watcher/startup_race_tests.dart

@@ -0,0 +1,39 @@
+// Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:io';
+
+import 'package:test/test.dart';
+
+import '../utils.dart';
+
+/// Tests for a startup race that affects MacOS.
+///
+/// As documented in `File.watch`, changes from shortly _before_ the `watch`
+/// method is called might be reported on MacOS. They should be ignored.
+void startupRaceTests() {
+  test('ignores events from before watch starts', () async {
+    // Write then immediately watch 100 times and count the events received.
+    var events = 0;
+    final futures = <Future<void>>[];
+    for (var i = 0; i != 100; ++i) {
+      writeFile('file$i.txt');
+      await startWatcher(path: 'file$i.txt');
+      futures.add(
+        waitForEvent().then((event) {
+          if (event != null) ++events;
+        }),
+      );
+    }
+    await Future.wait(futures);
+
+    // TODO(davidmorgan): the MacOS watcher currently does get unwanted events,
+    // fix it.
+    if (Platform.isMacOS) {
+      expect(events, greaterThan(50));
+    } else {
+      expect(events, 0);
+    }
+  });
+}

pkgs/watcher/test/utils.dart

@@ -174,6 +174,23 @@ Matcher isModifyEvent(String path) => isWatchEvent(ChangeType.MODIFY, path);
 /// [path].
 Matcher isRemoveEvent(String path) => isWatchEvent(ChangeType.REMOVE, path);
 
+/// Takes the first event emitted during [duration], or returns `null` if there
+/// is none.
+Future<WatchEvent?> waitForEvent({
+  Duration duration = const Duration(seconds: 1),
+}) async {
+  final result = await _watcherEvents.peek
+      .then<WatchEvent?>((e) => e)
+      .timeout(duration, onTimeout: () => null);
+  if (result != null) _watcherEvents.take(1).ignore();
+  return result;
+}
+
+/// Expects that no events are omitted for [duration].
+Future expectNoEvents({Duration duration = const Duration(seconds: 1)}) async {
+  expect(await waitForEvent(duration: duration), isNull);
+}
+
 /// Expects that the next event emitted will be for an add event for [path].
 Future expectAddEvent(String path) =>
     _expectOrCollect(isWatchEvent(ChangeType.ADD, path));