diff --git a/doc/guides/debugging.md b/doc/guides/debugging.md new file mode 100644 index 00000000000000..07afd7a144301e --- /dev/null +++ b/doc/guides/debugging.md @@ -0,0 +1,177 @@ +# Debugging Guide + + + +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 . + +* [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: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagMeaning
--debug +
    +
  • Enable debugger agent
    • +
  • Listen on default port (5858)
    • +
+
--debug=port +
    +
  • Enable debugger agent
    • +
  • Listen on port port
    • +
+
--debug-brk +
    +
  • Enable debugger agent
    • +
  • Listen on default port (5858)
    • +
  • Break before user code starts
    • +
+
--debug-brk=port +
    +
  • Enable debugger agent
    • +
  • Listen on port port
    • +
  • Break before user code starts
    • +
+
--inspect +
    +
  • Enable inspector agent
    • +
  • Listen on default port (9229)
    • +
+
--inspect=port +
    +
  • Enable inspector agent
    • +
  • Listen on port port
    • +
+
--inspect-brk +
    +
  • Enable inspector agent
    • +
  • Listen on default port (9229)
    • +
  • Break before user code starts
    • +
+
--inspect-brk=port +
    +
  • Enable debugger agent
    • +
  • Listen on port port
    • +
  • Break before user code starts
    • +
+
--debug-port=port +
    +
  • Set port to port for other flags. Must come after others. +
+
node debug script.js +
    +
  • Spawn child process to run user script under --debug mode, + and use main process to run CLI debugger.
    • +
+
+ + +## Default ports: + +* Inspector: 9229 +* Debugger: 5858 + diff --git a/src/inspector_agent.cc b/src/inspector_agent.cc index aec0bc06e32334..643c04992fdf28 100644 --- a/src/inspector_agent.cc +++ b/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); } diff --git a/test/inspector/inspector-helper.js b/test/inspector/inspector-helper.js index 850df8718fbe7c..7920d11d31cf0b 100644 --- a/test/inspector/inspector-helper.js +++ b/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);