Wrap Directory.watch on linux for the watcher package.

pkg/watcher/test/utils.dart

 // Copyright (c) 2012, 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.
 
 library watcher.test.utils;
 
 import 'dart:async';
+import 'dart:collection';
 import 'dart:io';
 
 import 'package:path/path.dart' as p;
 import 'package:scheduled_test/scheduled_test.dart';
 import 'package:unittest/compact_vm_config.dart';
 import 'package:watcher/watcher.dart';
 import 'package:watcher/src/stat.dart';
+import 'package:watcher/src/utils.dart';
 
 /// The path to the temporary sandbox created for each test. All file
 /// operations are implicitly relative to this directory.
 String _sandboxDir;
 
 /// The [DirectoryWatcher] being used for the current scheduled test.
 DirectoryWatcher _watcher;
 
 /// The index in [_watcher]'s event stream for the next event. When event
 /// expectations are set using [expectEvent] (et. al.), they use this to
 /// expect a series of events in order.
 var _nextEvent = 0;
 
 /// The mock modification times (in milliseconds since epoch) for each file.
 ///
 /// The actual file system has pretty coarse granularity for file modification
 /// times. This means using the real file system requires us to put delays in
 /// the tests to ensure we wait long enough between operations for the mod time
 /// to be different.
 ///
 /// Instead, we'll just mock that out. Each time a file is written, we manually
 /// increment the mod time for that file instantly.
 Map<String, int> _mockFileModificationTimes;
 
+typedef DirectoryWatcher WatcherFactory(String directory);
+
+/// Sets the function used to create the directory watcher.
+set watcherFactory(WatcherFactory factory) {
+  _watcherFactory = factory;
+}
+WatcherFactory _watcherFactory;
+
 void initConfig() {
   useCompactVMConfiguration();
   filterStacks = true;
 }
 
 /// Creates the sandbox directory the other functions in this library use and
 /// ensures it's deleted when the test ends.
 ///
 /// This should usually be called by [setUp].
 void createSandbox() {
   var dir = Directory.systemTemp.createTempSync('watcher_test_');
   _sandboxDir = dir.path;
 
   _mockFileModificationTimes = new Map<String, int>();
   mockGetModificationTime((path) {
     path = p.normalize(p.relative(path, from: _sandboxDir));
 
     // Make sure we got a path in the sandbox.
-    assert(p.isRelative(path)  && !path.startsWith(".."));
+    assert(p.isRelative(path) && !path.startsWith(".."));
 
-    return new DateTime.fromMillisecondsSinceEpoch(
-        _mockFileModificationTimes[path]);
+    var mtime = _mockFileModificationTimes[path];
+    return new DateTime.fromMillisecondsSinceEpoch(mtime == null ? 0 : mtime);
   });
 
   // Delete the sandbox when done.
   currentSchedule.onComplete.schedule(() {
     if (_sandboxDir != null) {
       new Directory(_sandboxDir).deleteSync(recursive: true);
       _sandboxDir = null;
     }
 
     _mockFileModificationTimes = null;
     mockGetModificationTime(null);
   }, "delete sandbox");
 }
 
 /// Creates a new [DirectoryWatcher] that watches a temporary directory.
 ///
 /// Normally, this will pause the schedule until the watcher is done scanning
 /// and is polling for changes. If you pass `false` for [waitForReady], it will
 /// not schedule this delay.
 ///
 /// If [dir] is provided, watches a subdirectory in the sandbox with that name.
 DirectoryWatcher createWatcher({String dir, bool waitForReady}) {
   if (dir == null) {
     dir = _sandboxDir;
   } else {
     dir = p.join(_sandboxDir, dir);
   }
 
-  // Use a short delay to make the tests run quickly.
-  _watcher = new DirectoryWatcher(dir,
-      pollingDelay: new Duration(milliseconds: 100));
+  var watcher = _watcherFactory(dir);
 
   // Wait until the scan is finished so that we don't miss changes to files
   // that could occur before the scan completes.
   if (waitForReady != false) {
-    schedule(() => _watcher.ready, "wait for watcher to be ready");
+    schedule(() => watcher.ready, "wait for watcher to be ready");
   }
 
-  currentSchedule.onComplete.schedule(() {
-    _nextEvent = 0;
-    _watcher = null;
-  }, "reset watcher");
-
-  return _watcher;
+  return watcher;
 }
 
-/// Expects that the next set of events will all be changes of [type] on
-/// [paths].
+/// The stream of events from the watcher started with [startWatcher].
+Stream _watcherEvents;
+
+/// Creates a new [DirectoryWatcher] that watches a temporary directory and
+/// starts monitoring it for events.
 ///
-/// Validates that events are delivered for all paths in [paths], but allows
-/// them in any order.
-void expectEvents(ChangeType type, Iterable<String> paths) {
-  var pathSet = paths
-      .map((path) => p.join(_sandboxDir, path))
-      .map(p.normalize)
-      .toSet();
+/// If [dir] is provided, watches a subdirectory in the sandbox with that name.
+void startWatcher({String dir}) {
+  // We want to wait until we're ready *after* we subscribe to the watcher's
+  // events.
+  _watcher = createWatcher(dir: dir, waitForReady: false);
 
-  // Create an expectation for as many paths as we have.
-  var futures = [];
+  // Schedule [_watcher.events.listen] so that the watcher doesn't start
+  // watching [dir] before it exists. Expose [_watcherEvents] immediately so
+  // that it can be accessed synchronously after this.
+  _watcherEvents = futureStream(schedule(() {
+    var allEvents = new Queue();
+    var subscription = _watcher.events.listen(allEvents.add,
+        onError: currentSchedule.signalError);
 
-  for (var i = 0; i < paths.length; i++) {
-    // Immediately create the futures. This ensures we don't register too
-    // late and drop the event before we receive it.
-    var future = _watcher.events.elementAt(_nextEvent++).then((event) {
-      expect(event.type, equals(type));
-      expect(pathSet, contains(event.path));
+    currentSchedule.onComplete.schedule(() {
+      var numEvents = _nextEvent;
+      subscription.cancel();
+      _nextEvent = 0;
+      _watcher = null;
 
-      pathSet.remove(event.path);
-    });
+      // If there are already errors, don't add this to the output and make
+      // people think it might be the root cause.
+      if (currentSchedule.errors.isEmpty) {
+        expect(allEvents, hasLength(numEvents));
+      }
+    }, "reset watcher");
 
-    // Make sure the schedule is watching it in case it fails.
-    currentSchedule.wrapFuture(future);
+    return _watcher.events;
+  }, "create watcher")).asBroadcastStream();
 
-    futures.add(future);
-  }
-
-  // Schedule it so that later file modifications don't occur until after this
-  // event is received.
-  schedule(() => Future.wait(futures),
-      "wait for $type events on ${paths.join(', ')}");
+  schedule(() => _watcher.ready, "wait for watcher to be ready");
 }
 
-void expectAddEvent(String path) => expectEvents(ChangeType.ADD, [path]);
-void expectModifyEvent(String path) => expectEvents(ChangeType.MODIFY, [path]);
-void expectRemoveEvent(String path) => expectEvents(ChangeType.REMOVE, [path]);
+/// A future set by [inAnyOrder] that will complete to the set of events that
+/// occur in the [inAnyOrder] block.
+Future<Set<WatchEvent>> _unorderedEventFuture;
 
-void expectRemoveEvents(Iterable<String> paths) {
-  expectEvents(ChangeType.REMOVE, paths);
+/// Runs [block] and allows multiple [expectEvent] calls in that block to match
+/// events in any order.
+void inAnyOrder(block()) {
+  var oldFuture = _unorderedEventFuture;
+  try {
+    var firstEvent = _nextEvent;
+    var completer = new Completer();
+    _unorderedEventFuture = completer.future;
+    block();
+
+    _watcherEvents.skip(firstEvent).take(_nextEvent - firstEvent).toSet()
+        .then(completer.complete, onError: completer.completeError);
+    currentSchedule.wrapFuture(_unorderedEventFuture,
+        "waiting for ${_nextEvent - firstEvent} events");
+  } finally {
+    _unorderedEventFuture = oldFuture;
+  }
 }
 
+/// Expects that the next set of event will be a change of [type] on [path].
+///
+/// Multiple calls to [expectEvent] require that the events are received in that
+/// order unless they're called in an [inAnyOrder] block.
+void expectEvent(ChangeType type, String path) {
+  var matcher = predicate((e) {
+    return e is WatchEvent && e.type == type &&
+        e.path == p.join(_sandboxDir, path);
+  }, "is $type $path");
+
+  if (_unorderedEventFuture != null) {
+    var future = _unorderedEventFuture;

[Bob Nystrom, 2013/11/06 19:24:04]

Document that this is being stored locally since _unorderedEventFuture may get
assigned before the schedule() call below runs.

[nweiz, 2013/11/07 00:46:37]

Done.

+    _nextEvent++;

[Bob Nystrom, 2013/11/06 19:24:04]

Move this above the if() and remove the ++ below.

[nweiz, 2013/11/07 00:46:37]

Done.

+
+    expect(
+        schedule(() => future, "should fire $type event on $path"),
+        completion(contains(matcher)));

[Bob Nystrom, 2013/11/06 19:24:04]

For inAnyOrder, should we care about duplicate events? It looks like this
doesn't as far as I can tell.

[nweiz, 2013/11/07 00:46:37]

I thought about doing so, but I decided it wasn't worth the trouble. Since we
validate the number of events sent, the only case where we break is if a test
tries to assert that multiple identical events were fired, which doesn't seem
useful.

+  } else {
+    var future = currentSchedule.wrapFuture(
+        _watcherEvents.elementAt(_nextEvent++),
+        "waiting for $type event on $path");
+
+    expect(
+        schedule(() => future, "should fire $type event on $path"),
+        completion(matcher));
+  }
+}
+
+void expectAddEvent(String path) => expectEvent(ChangeType.ADD, path);
+void expectModifyEvent(String path) => expectEvent(ChangeType.MODIFY, path);
+void expectRemoveEvent(String path) => expectEvent(ChangeType.REMOVE, path);
+
 /// Schedules writing a file in the sandbox at [path] with [contents].
 ///
 /// If [contents] is omitted, creates an empty file. If [updatedModified] is
 /// `false`, the mock file modification time is not changed.
 void writeFile(String path, {String contents, bool updateModified}) {
   if (contents == null) contents = "";
   if (updateModified == null) updateModified = true;
 
   schedule(() {
     var fullPath = p.join(_sandboxDir, path);
@@ skipping 33 matching lines @@
 
     // Make sure we always use the same separator on Windows.
     to = p.normalize(to);
 
     // Manually update the mock modification time for the file.
     var milliseconds = _mockFileModificationTimes.putIfAbsent(to, () => 0);
     _mockFileModificationTimes[to]++;
   }, "rename file $from to $to");
 }
 
+/// Schedules creating a directory in the sandbox at [path].

[Bob Nystrom, 2013/11/06 19:24:04]

Can you use the descriptor API instead of adding this?

[nweiz, 2013/11/07 00:46:37]

I wanted to keep this consistent with the other methods in this file, which
don't use the descriptor API. I'll add a TODO to switch these tests over to
using descriptor if you like, but to be honest I don't think it's a great fit.
These tests usually create only a couple files or directories per test, and very
rarely create the sort of complex directory structure that the descriptor API is
designed to make easy. I think there's more value in preserving similarity
between the creation functions and the modification functions in this case than
in using the descriptor library for the creation functions.

[Bob Nystrom, 2013/11/07 18:16:05]

SGTM. That was my guess behind your thinking here.

+void createDir(String path) {
+  schedule(() {
+    new Directory(p.join(_sandboxDir, path)).createSync();
+  }, "create directory $path");
+}
+
+/// Schedules renaming a directory in the sandbox from [from] to [to].
+void renameDir(String from, String to) {

[Bob Nystrom, 2013/11/06 19:24:04]

Does scheduled_test have something for this already? Should it?

[nweiz, 2013/11/07 00:46:37]

It doesn't. Right now it just exposes the descriptor API, which exists more to
provide a clear way of setting and validating complex directory structures than
to provide a general-purpose "scheduled IO" library. It's possible that there's
room for a new library that just takes common filesystem IO operations and
schedules them, but it would look more like a collection of utility functions
than the wrappers that exist now do.

+  schedule(() {
+    new Directory(p.join(_sandboxDir, from))
+        .renameSync(p.join(_sandboxDir, to));
+  }, "rename directory $from to $to");
+}
+
 /// Schedules deleting a directory in the sandbox at [path].
 void deleteDir(String path) {

[Bob Nystrom, 2013/11/06 19:24:04]

Ditto.

   schedule(() {
     new Directory(p.join(_sandboxDir, path)).deleteSync(recursive: true);
   }, "delete directory $path");
 }
 
-/// A [Matcher] for [WatchEvent]s.
-class _ChangeMatcher extends Matcher {
-  /// The expected change.
-  final ChangeType type;
-
-  /// The expected path.
-  final String path;
-
-  _ChangeMatcher(this.type, this.path);
-
-  Description describe(Description description) {
-    description.add("$type $path");
+/// Runs [callback] with every permutation of non-negative [i], [j], and [k]
+/// less than [limit].
+///
+/// [limit] defaults to 3.
+void withPermutations(callback(int i, int j, int k), {int limit}) {
+  if (limit == null) limit = 3;
+  for (var i = 0; i < limit; i++) {
+    for (var j = 0; j < limit; j++) {
+      for (var k = 0; k < limit; k++) {
+        callback(i, j, k);
+      }
+    }
   }
-
-  bool matches(item, Map matchState) =>
-      item is WatchEvent &&
-      item.type == type &&
-      p.normalize(item.path) == p.normalize(path);
 }