docs(ngMock/$timeout): recommend $verifyNoPendingTasks() when appropriate

For historical reasons, `$timeout.verifyNoPendingTasks()` throws if
there is any type of task pending (even if it is not a timeout). When
calling `$timeout.verifyNoPendingTasks()`, the user is most likely
interested in verifying pending timeouts only, which is now possible
with `$verifyNoPendingTasks('$timeout')`.

To raise awareness of `$verifyNoPendingTasks()`, it is mentioned in the
error message thrown by `$timeoutverifyNoPendingTasks()` if none of the
pending tasks is a timeout.

Author: gkalpak

src/ngMock/angular-mocks.js

@@ -150,6 +150,36 @@ angular.mock.$Browser = function($log, $$taskTrackerFactory) {
     self.defer.now = nextTime;
   };
 
+  /**
+   * @name $browser#defer.getPendingTasks
+   *
+   * @description
+   * Returns the currently pending tasks that need to be flushed.
+   * You can request a specific type of tasks only, by specifying a `taskType`.
+   *
+   * @param {string=} taskType - The type tasks to return.
+   */
+  self.defer.getPendingTasks = function(taskType) {
+    return !taskType
+        ? self.deferredFns
+        : self.deferredFns.filter(function(task) { return task.type === taskType; });
+  };
+
+  /**
+   * @name $browser#defer.formatPendingTasks
+   *
+   * @description
+   * Formats each task in a list of pending tasks as a string, suitable for use in error messages.
+   *
+   * @param {Array<Object>} pendingTasks - A list of task objects.
+   * @return {Array<string>} A list of stringified tasks.
+   */
+  self.defer.formatPendingTasks = function(pendingTasks) {
+    return pendingTasks.map(function(task) {
+      return '{id: ' + task.id + ', type: ' + task.type + ', time: ' + task.time + '}';
+    });
+  };
+
   /**
    * @name $browser#defer.verifyNoPendingTasks
    *
@@ -162,17 +192,10 @@ angular.mock.$Browser = function($log, $$taskTrackerFactory) {
    * @param {string=} taskType - The type tasks to check for.
    */
   self.defer.verifyNoPendingTasks = function(taskType) {
-    var pendingTasks = !taskType
-        ? self.deferredFns
-        : self.deferredFns.filter(function(task) { return task.type === taskType; });
+    var pendingTasks = self.defer.getPendingTasks(taskType);
 
     if (pendingTasks.length) {
-      var formattedTasks = pendingTasks
-          .map(function(task) {
-            return '{id: ' + task.id + ', type: ' + task.type + ', time: ' + task.time + '}';
-          })
-          .join('\n  ');
-
+      var formattedTasks = self.defer.formatPendingTasks(pendingTasks).join('\n  ');
       throw new Error('Deferred tasks to flush (' + pendingTasks.length + '):\n  ' +
           formattedTasks);
     }
@@ -2291,7 +2314,18 @@ angular.mock.$TimeoutDecorator = ['$delegate', '$browser', function($delegate, $
   $delegate.verifyNoPendingTasks = function() {
     // For historical reasons, `$timeout.verifyNoPendingTasks()` takes all types of pending tasks
     // into account. Keep the same behavior for backwards compatibility.
-    $browser.defer.verifyNoPendingTasks();
+    var pendingTasks = $browser.defer.getPendingTasks();
+
+    if (pendingTasks.length) {
+      var formattedTasks = $browser.defer.formatPendingTasks(pendingTasks).join('\n  ');
+      var hasPendingTimeout = pendingTasks.some(function(task) { return task.type === '$timeout'; });
+      var extraMessage = hasPendingTimeout ? '' : '\n\nNone of the pending tasks are timeouts. ' +
+          'If you only want to verify pending timeouts, use ' +
+          '`$verifyNoPendingTasks(\'$timeout\')` instead.';
+
+      throw new Error('Deferred tasks to flush (' + pendingTasks.length + '):\n  ' +
+          formattedTasks + extraMessage);
+    }
   };
 
   return $delegate;

test/ngMock/angular-mocksSpec.js

@@ -920,6 +920,27 @@ describe('ngMock', function() {
     }));
 
 
+    it('should recommend `$verifyNoPendingTasks()` when all pending tasks are not timeouts',
+      inject(function($rootScope, $timeout) {
+        var extraMessage = 'None of the pending tasks are timeouts. If you only want to verify ' +
+            'pending timeouts, use `$verifyNoPendingTasks(\'$timeout\')` instead.';
+        var errorMessage;
+
+        $timeout(noop, 100);
+        $rootScope.$evalAsync(noop);
+        try { $timeout.verifyNoPendingTasks(); } catch (err) { errorMessage = err.message; }
+
+        expect(errorMessage).not.toContain(extraMessage);
+
+        $timeout.flush(100);
+        $rootScope.$evalAsync(noop);
+        try { $timeout.verifyNoPendingTasks(); } catch (err) { errorMessage = err.message; }
+
+        expect(errorMessage).toContain(extraMessage);
+      })
+    );
+
+
     it('should do nothing when all tasks have been flushed', inject(function($rootScope, $timeout) {
       $timeout(noop, 100);
       $rootScope.$evalAsync(noop);