To be squashed: Address comments and add some more docs

Author: juliemr

lib/breakpointhook.js

@@ -1,3 +1,10 @@
 module.exports = function() {
   return true;
 };
+
+/**
+ * The reason this file exists is so that we can set a breakpoint via
+ * script name, and then control when that breakpoint is set in
+ * our library code by importing and calling this function. The
+ * breakpoint will always be on line 2.
+ */

lib/browser.ts

@@ -972,37 +972,46 @@ export class ProtractorBrowser extends AbstractExtendedWebDriver {
   }
 
   /**
-   * Beta (unstable) enterRepl function for entering the repl loop from
-   * any point in the control flow. Use browser.enterRepl() in your test.
+   * See browser.explore().
+   */
+  enterRepl(opt_debugPort?: number) {
+    return this.explore(opt_debugPort);
+  }
+
+  /**
+   * Beta (unstable) explore function for entering the repl loop from
+   * any point in the control flow. Use browser.explore() in your test.
    * Does not require changes to the command line (no need to add 'debug').
    * Note, if you are wrapping your own instance of Protractor, you must
    * expose globals 'browser' and 'protractor' for pause to work.
    *
    * @example
    * element(by.id('foo')).click();
-   * browser.enterRepl();
+   * browser.explore();
    * // Execution will stop before the next click action.
    * element(by.id('bar')).click();
    *
    * @param {number=} opt_debugPort Optional port to use for the debugging
    * process
    */
-  enterRepl(opt_debugPort?: number) {
+  explore(opt_debugPort?: number) {
     let debuggerClientPath = __dirname + '/debugger/clients/explorer.js';
-    let onStartFn = () => {
-      logger.info();
-      logger.info('------- Element Explorer -------');
-      logger.info(
-          'Starting WebDriver debugger in a child process. Element ' +
-          'Explorer is still beta, please report issues at ' +
-          'github.com/angular/protractor');
-      logger.info();
-      logger.info('Type <tab> to see a list of locator strategies.');
-      logger.info('Use the `list` helper function to find elements by strategy:');
-      logger.info('  e.g., list(by.binding(\'\')) gets all bindings.');
+    let onStartFn = (firstTime: boolean) => {
       logger.info();
+      if (firstTime) {
+        logger.info('------- Element Explorer -------');
+        logger.info(
+            'Starting WebDriver debugger in a child process. Element ' +
+            'Explorer is still beta, please report issues at ' +
+            'github.com/angular/protractor');
+        logger.info();
+        logger.info('Type <tab> to see a list of locator strategies.');
+        logger.info('Use the `list` helper function to find elements by strategy:');
+        logger.info('  e.g., list(by.binding(\'\')) gets all bindings.');
+        logger.info();
+      }
     };
-    this.debugHelper.init(debuggerClientPath, true, onStartFn, opt_debugPort);
+    this.debugHelper.initBlocking(debuggerClientPath, onStartFn, opt_debugPort);
   }
 
   /**
@@ -1043,6 +1052,6 @@ export class ProtractorBrowser extends AbstractExtendedWebDriver {
         logger.info();
       }
     };
-    this.debugHelper.init(debuggerClientPath, false, onStartFn, opt_debugPort);
+    this.debugHelper.init(debuggerClientPath, onStartFn, opt_debugPort);
   }
 }

lib/debugger.ts

@@ -26,21 +26,34 @@ export class DebugHelper {
 
   constructor(private browserUnderDebug_: ProtractorBrowser) {}
 
+
+  initBlocking(debuggerClientPath: string, onStartFn: Function, opt_debugPort?: number) {
+    this.init_(debuggerClientPath, true, onStartFn, opt_debugPort);
+  }
+
+  init(debuggerClientPath: string, onStartFn: Function, opt_debugPort?: number) {
+    this.init_(debuggerClientPath, false, onStartFn, opt_debugPort);
+  }
+
   /**
    *  1) Set up helper functions for debugger clients to call on (e.g.
    *     execute code, get autocompletion).
    *  2) Enter process into debugger mode. (i.e. process._debugProcess).
    *  3) Invoke the debugger client specified by debuggerClientPath.
    *
    * @param {string} debuggerClientPath Absolute path of debugger client to use.
-   * @param {boolean} blockUntilExit Whether to block until process exit or resume immediately.
+   * @param {boolean} blockUntilExit Whether to block the flow until process exit or resume
+   *     immediately.
    * @param {Function} onStartFn Function to call when the debugger starts. The
    *     function takes a single parameter, which represents whether this is the
    *     first time that the debugger is called.
-   * @param {number=} opt_debugPort Optional port to u`se for the debugging
+   * @param {number=} opt_debugPort Optional port to use for the debugging
    *     process.
+   * 
+   * @return {Promise} If blockUntilExit, a promise resolved when the debugger process
+   *     exits. Otherwise, resolved when the debugger process is ready to begin.
    */
-  init(
+  init_(
       debuggerClientPath: string, blockUntilExit: boolean, onStartFn: Function,
       opt_debugPort?: number) {
     wdpromise.ControlFlow.prototype.getControlFlowText = function() {
@@ -83,7 +96,7 @@ export class DebugHelper {
 
     // We run one flow.execute block for the debugging session. All
     // subcommands should be scheduled under this task.
-    var executePromise = flow.execute(() => {
+    let executePromise = flow.execute(() => {
       process['debugPort'] = opt_debugPort || process['debugPort'];
       this.validatePortAvailability_(process['debugPort']).then((firstTime: boolean) => {
         onStartFn(firstTime);
@@ -123,7 +136,7 @@ export class DebugHelper {
     // To be able to simulate callback/asynchronous code, we poll this object
     // whenever `breakpointHook` is called.
     this.dbgCodeExecutor = {
-      execPromise_: null,             // Promise pointing to currently executing command.
+      execPromise_: undefined,        // Promise pointing to currently executing command.
       execPromiseResult_: undefined,  // Return value of promise.
       execPromiseError_: undefined,   // Error from promise.
 

lib/debugger/clients/wddebugger.js

@@ -42,11 +42,6 @@ WdDebugger.prototype.initRepl_ = function() {
 
   // We want the prompt to show up only after the controlflow text prints.
   this.dbgRepl.printControlFlow_(function() {
-    // Backward compatibility: node version 0.8.14 has a number of built in 
-    // libraries for repl, and the keyword 'repl' clashes with our usage.
-    // if (repl._builtinLibs && repl._builtinLibs.indexOf('repl') > -1) {
-    //   repl._builtinLibs.splice(repl._builtinLibs.indexOf('repl'), 1);
-    // }
     self.replServer = repl.start({
       prompt: self.dbgRepl.prompt,
       input: process.stdin,

lib/debugger/modes/debuggerRepl.js

@@ -83,9 +83,7 @@ DebuggerRepl.prototype.stepEval = function(cmd, callback) {
  * @param {string} line Initial user entry
  * @param {function} callback
  */
-DebuggerRepl.prototype.complete = function(line, callback) {
-  console.log('calling debuggerrepl complete');
-  
+DebuggerRepl.prototype.complete = function(line, callback) {  
   var suggestions = DBG_INITIAL_SUGGESTIONS.filter(function(suggestion) {
     return suggestion.indexOf(line) === 0;
   });