inspector,doc: update hint text, add guide

doc/guides/debugging.md

@@ -0,0 +1,177 @@
+# Debugging Guide
+
+<!-- type=misc -->
+
+The goal of this guide is to provide you with enough information to get started
+debugging your Node.js apps and scripts.
+
+## Enable Debugging
+
+When started with the **--debug** or **--debug-brk** switches, Node.js listens
+for debugging commands defined by the [V8 Debugging Protocol][] on a TCP port,
+by default `5858`. Any debugger client which speaks this protocol can connect
+to and debug the running process.
+
+A running Node.js process can also be instructed to start listening for
+debugging messages by signaling it with `SIGUSR1` (on Linux and OS X).
+
+When started with the **--inspect** or **--inspect-brk** switches, Node.js
+listens for diagnostic commands defined by the [Chrome Debugging Protocol][]
+via websockets, by default at `ws://127.0.0.1:9229/node`. Any diagnostics
+client which speaks this protocol can connect to and debug the running process.
+
+The `--inspect` option and protocol are _experimental_ and may change.
+
+[V8 Debugging Protocol]: https://github.com/v8/v8/wiki/Debugging-Protocol
+[Chrome Debugging Protocol]: https://developer.chrome.com/devtools/docs/debugger-protocol
+
+
+## Debugging Clients
+
+Several commercial and open source tools can connect to Node's
+debugger and/or inspector. Info on these follows.
+
+* [Built-in Debugger](https://github.com/nodejs/node/blob/master/lib/_debugger.js)
+
+  * Start `node debug script_name.js` to start your script under Node's
+    builtin command-line debugger. Your script starts in another Node
+    process started with the `--debug-brk` option, and the initial Node
+    process runs the `_debugger.js` script and connects to your target.
+
+* [Chrome DevTools](https://github.com/ChromeDevTools/devtools-frontend)
+
+  * **Option 1 (Chrome 55+)**: Open `chrome://inspect` in your Chromium
+    browser. Click the Configure button and ensure your target host and port
+    are listed.
+  * **Option 2**: Paste the following URL in Chrome,
+    replacing the `ws` parameter with your hostname and port as needed:
+
+    `chrome-devtools://devtools/bundled/inspector.html?experiments=true&v8only=true&ws=localhost:9229/node`
+
+* [VS Code](https://github.com/microsoft/vscode)
+  * **Option 1**: In the Debug panel, click the settings button to choose
+    initial debug configurations. Select "Node.js v6.3+ (Experimental)" for
+    `--inspect` support, or "Node.js" for `--debug` support.
+  * **Option 2**: In debug configurations in `.vscode/launch.json`, set `type`
+    as `node2`.
+
+  * For more info, see <https://github.com/Microsoft/vscode-node-debug2>.
+
+* [WebStorm](https://www.jetbrains.com/webstorm/) 2016.2+ and other JetBrains
+                                                  IDEs (IJ U, PS, PC, RM, CL, AC)
+  * In the Node.js debug configuration add `--inspect` to the Node parameters
+    field for `--inspect` support. By default, the debug process will use V8
+    Debugging Protocol.
+
+* [node-inspector](https://github.com/node-inspector/node-inspector)
+
+* [chrome-remote-interface](https://github.com/cyrus-and/chrome-remote-interface)
+
+
+## Debugging command-line options
+
+* The following table clarifies the implications of various diag-related flags:
+
+<table cellpadding=0 cellspacing=0>
+  <tr><th>Flag</th><th>Meaning</th></tr>
+  <tr>
+    <td>--debug</td>
+    <td>
+      <ul>
+        <li>Enable debugger agent</li>
+        <li>Listen on default port (5858)</li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <td>--debug=<i>port</i></td>
+    <td>
+      <ul>
+        <li>Enable debugger agent</li>
+        <li>Listen on port <i>port</i></li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <td>--debug-brk</td>
+    <td>
+      <ul>
+        <li>Enable debugger agent</li>
+        <li>Listen on default port (5858)</li>
+        <li>Break before user code starts</li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <td>--debug-brk=<i>port</i></td>
+    <td>
+      <ul>
+        <li>Enable debugger agent</li>
+        <li>Listen on port <i>port</i></li>
+        <li>Break before user code starts</li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <td>--inspect</td>
+    <td>
+      <ul>
+        <li>Enable inspector agent</li>
+        <li>Listen on default port (9229)</li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <td>--inspect=<i>port</i></td>
+    <td>
+      <ul>
+        <li>Enable inspector agent</li>
+        <li>Listen on port <i>port</i></li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <td>--inspect-brk</td>
+    <td>
+      <ul>
+        <li>Enable inspector agent</li>
+        <li>Listen on default port (9229)</li>
+        <li>Break before user code starts</li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <td>--inspect-brk=<i>port</i></td>
+    <td>
+      <ul>
+        <li>Enable debugger agent</li>
+        <li>Listen on port <i>port</i></li>
+        <li>Break before user code starts</li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <td>--debug-port=<i>port</i></td>
+    <td>
+      <ul>
+        <li> Set port to <i>port</i> for other flags. Must come after others.
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <td><code>node debug <i>script.js</i></code></td>
+    <td>
+      <ul>
+        <li>Spawn child process to run user script under --debug mode,
+            and use main process to run CLI debugger.</li>
+      </ul>
+    </td>
+  </tr>
+</table>
+
+
+## Default ports: 
+
+* Inspector: 9229
+* Debugger:  5858
+

src/inspector_agent.cc

@@ -43,13 +43,12 @@ std::string GetWsUrl(int port, const std::string& id) {
 }
 
 void PrintDebuggerReadyMessage(int port, const std::string& id) {
-  fprintf(stderr, "Debugger listening on port %d.\n"
-    "Warning: This is an experimental feature and could change at any time.\n"
-    "To start debugging, open the following URL in Chrome:\n"
-    "    chrome-devtools://devtools/remote/serve_file/"
-    "@" V8_INSPECTOR_REVISION "/inspector.html?"
-    "experiments=true&v8only=true&ws=%s\n",
-      port, GetWsUrl(port, id).c_str());
+  fprintf(stderr, "Debugger listening on \x1B[33mws://%s\x1b[0m\n"
+  "* Info on connecting at"
+    "\x1B[33mhttps://nodejs.org/en/docs/guides/debugging\x1B[0m.\n"
+  "* Warning: This is an experimental feature and could change at any time."
+  "\n\n",
+  GetWsUrl(port, id).c_str());
   fflush(stderr);
 }
 

test/inspector/inspector-helper.js

@@ -412,20 +412,26 @@ exports.startNodeForInspectorTest = function(callback) {
 
   const timeoutId = timeout('Child process did not start properly', 4);
 
-  let found = false;
+  var found = false;
 
   const dataCallback = makeBufferingDataCallback((text) => {
     clearTimeout(timeoutId);
     console.log('[err]', text);
     if (found) return;
-    const match = text.match(/Debugger listening on port (\d+)/);
-    found = true;
-    child.stderr.removeListener('data', dataCallback);
-    assert.ok(match, text);
-    callback(new Harness(match[1], child));
+    const re = /Debugger listening on.*ws:\/\/(.*):(\d+)\/(\w+)/;
+    const match = text.match(re);
+    if (match) {
+      found = true;
+      child.stderr.removeListener('data', dataCallback);
+      callback(new Harness(match[2], child));
+      return;
+    }
   });
 
   child.stderr.on('data', dataCallback);
+  child.on('exit', (code, signal) => {
+    assert.ok(found, 'Failed to start child script.');
+  });
 
   const handler = tearDown.bind(null, child);