feat(timeouts): add a unique error message when waitForAngular times out

To improve the readability of error messages, when waitForAngular times out
it now produces a custom message. This should help clarify confusion
for pages that continually poll using $interval. This change also adds more
documentation on timeouts. See issue #109.

debugging/timeout_spec.js

@@ -29,6 +29,26 @@ describe('timeout possibilities', function() {
     expect(true).toEqual(true);
   });
 
+  describe('waitForAngular', function() {
+    it('should timeout and give a reasonable message', function() {
+
+      ptor.driver.manage().timeouts().setScriptTimeout(55);
+
+      ptor.get('app/index.html#/async');
+
+
+      var status =
+        ptor.findElement(protractor.By.binding('slowHttpStatus'));
+      var button = ptor.findElement(protractor.By.css('[ng-click="slowHttp()"]'));
+
+      expect(status.getText()).toEqual('not started');
+
+      button.click();
+
+      expect(status.getText()).toEqual('done');
+    }, 5000); // The 5000 here sets the Jasmine spec timeout.
+  });
+
   it('should timeout due to Jasmine spec timeout', function() {
     ptor.driver.sleep(1000);
     expect(true).toBe(true);

docs/debugging.md

@@ -104,8 +104,14 @@ Jasmine tests have a timeout which can be set
   `it('should pass', function() {...}, 5555);`
 
 Webdriver has a timeout for script execution, which can be set with
-`driver.manage().timeouts().setScriptTimeout`. Protractor sets this to 100
-seconds by default, so usually Jasmine will time out first.
+`driver.manage().timeouts().setScriptTimeout`. Protractor sets this to 5
+seconds by default.
+
+Protractor attempts to synchronize with your page before performing actions.
+This means waiting for all $timeout or $http requests to resolve, as well as
+letting the current $digest cycle finish. If your page has not synchronized
+within the script execution timeout, Protractor will fail with the message
+'Timed out waiting for Protractor to synchronize with the page'.
 
 If your website uses $timeout or $http to continuously poll, Protractor will
 interpret that as your site being busy and will time out on all requests. See

lib/cli.js

@@ -146,7 +146,7 @@ var startJasmineTests = function() {
       withCapabilities(config.capabilities).build();
 
   driver.getSession().then(function(session) {
-    driver.manage().timeouts().setScriptTimeout(100000);
+    driver.manage().timeouts().setScriptTimeout(5000);
 
     id = session.getId();
 

lib/protractor.js

@@ -108,7 +108,15 @@ Protractor.prototype.waitForAngular = function() {
     return webdriver.promise.fulfilled();
   }
   return this.driver.executeAsyncScript(
-      clientSideScripts.waitForAngular, this.rootEl);
+      clientSideScripts.waitForAngular, this.rootEl).then(null, function(err) {
+        console.log('Error was: ' + util.inspect(err));
+        if (!/asynchronous script timeout/.test(err.message)) {
+          throw err;
+        }
+        var timeout = /[\d\.]*\ seconds/.exec(err.message);
+        throw 'Timed out waiting for Protractor to synchronize with ' +
+              'the page after ' + timeout;
+      });
 };
 
 // TODO: activeelement also returns a WebElement.

referenceConf.js

@@ -82,6 +82,6 @@ exports.config = {
     // If true, include stack traces in failures.
     includeStackTrace: true,
     // Default time to wait in ms before a test fails.
-    defaultTimeoutInterval: 5000
+    defaultTimeoutInterval: 30000
   }
 };