Adding a 'debug' function to protractor. This schedules a debugger pause

within the webdriver control flow.

debugging/conf.js

@@ -0,0 +1,26 @@
+// Examples of tests to show how debugging works with Protractor. Tests
+// should be run against the testapp.
+
+exports.config = {
+  seleniumAddress: 'http://localhost:4444/wd/hub',
+
+  // Spec patterns are relative to the current working directly when
+  // protractor is called.
+  specs: [
+    'debugging/failure_spec.js',
+  ],
+
+  capabilities: {
+    'browserName': 'chrome'
+  },
+
+  baseUrl: 'http://localhost:8000',
+
+  // ----- Options to be passed to minijasminenode.
+  jasmineNodeOpts: {
+    onComplete: null,
+    isVerbose: false,
+    showColors: true,
+    includeStackTrace: true
+  }
+};

debugging/failure_spec.js

@@ -0,0 +1,31 @@
+var webdriver = require('selenium-webdriver');
+
+
+describe('modes of failure', function() {
+  ptor = protractor.getInstance();
+
+  it('should fail to find a non-existent element', function() {
+    ptor.get('app/index.html#/form');
+
+    // Run this statement before the line which fails. If protractor is run
+    // with the debugger (protractor debug debugging/conf.js), the test
+    // will pause after loading the webpage but before trying to find the
+    // element.
+    ptor.debugger();
+
+    // This element doesn't exist, so this fails.
+    var nonExistant = ptor.findElement(protractor.By.binding('nopenopenope'));
+  });
+
+  it('should fail to use protractor on a non-Angular site', function() {
+    ptor.get('http://www.google.com');
+  });
+
+  it('should fail an assertion', function() {
+    ptor.get('app/index.html#/form');
+
+    var greeting = ptor.findElement(protractor.By.binding('{{greeting}}'));
+
+    expect(greeting.getText()).toEqual('This is not what it equals');
+  });
+});

lib/protractor.js

@@ -401,6 +401,40 @@ Protractor.prototype.get = function(destination) {
   }, this.moduleNames_);
 };
 
+/**
+ * Pauses the test and injects some helper functions into the browser, so that
+ * debugging may be done in the browser console.
+ *
+ * This should be used under node in debug mode, i.e. with
+ * protractor debug <configuration.js>
+ *
+ * While in the debugger, commands can be scheduled through webdriver by
+ * entering the repl:
+ *   debug> repl
+ *   Press Ctrl + C to leave rdebug repl
+ *   > ptor.findElement(protractor.By.input('user').sendKeys('Laura'));
+ *   > ptor.debugger();
+ *   debug> c
+ *
+ * This will run the sendKeys command as the next task, then re-enter the
+ * debugger.
+ */
+Protractor.prototype.debugger = function() {
+  var clientSideScriptsList = [];
+  for (script in clientSideScripts) {
+    clientSideScriptsList.push(
+      script + ': ' + clientSideScripts[script].toString());
+  }
+
+  this.driver.executeScript(
+    'window.clientSideScripts = {' + clientSideScriptsList.join(', ') + '}')
+
+  var flow = webdriver.promise.controlFlow();
+  flow.execute(function() {
+    debugger;
+  });
+};
+
 /**
  * Create a new instance of Protractor by wrapping a webdriver instance.
  *