Debugging API

• Chrome Remote Debugging Protocol (alias V8 Inspector)
• V8 Debugging Protocol (deprecated in favor of V8 Inspector)

Depending on the Node version you are using, you can use either one of the above API :

Node >= 8

Starting from Node 8, the core provide the inspector module that allow to communicate with V8 via the CrDP protocol. You can find the latest node documentation here A guide made by the node foundation is also available here

Node >= 6.3.0 && Node < 8

Node 6.3.0 has seen the new V8 Inspector implemented but only via the --inspect and --inspect-brk flag. You can find more information in the node documentation here

Note that the old V8 Debugging Protocol was available and used as the main debugger protocol as this time (except for the new flags of course), see below for more informations

Node < 6.3.0

Node relied on V8's internal Debug API and associated commands and events. This Debug API was published at v8/include/v8-debug.h and in code in here. Note that this API has been deprecated then later removed, so the links above are in the V8 5.4 branch.

Debugging Tools

Name	Sponsor	Protocol available	State
Node CLI Debugger	Node Foundation	Both	Up to date
Chrome DevTools	Google	V8 inspector	Up to date
Visual Studio Code	Microsoft	Both	Up to date
JetBrains WebStorm	JetBrains	Both	Up to date
node-inspector	StrongLoop	V8 Debugging Protocol	Deprecated
Theseus	Adobe Research	V8 Debugging Protocol	Not Maintained

Blackbox

Blackbox is a popular term that allows debugging user-land code without touching in their internals.

For futher reference in nodejs debugging follow these instructions.

Enabling Blackbox through UI

See the ignore-script section at Google Chrome reference

Enabling Blackbox through CLI

Let's create a file called example-blackbox.js to simulate a blackbox usage

module.exports = {
  doSomethingAsync: async () => {
    debugger
    console.log('Async done')
  }
}

Then we have our index.js file

const { doSomethingAsync } = require('./example-blackbox')
async function main() {
  await doSomethingAsync()
  console.log('Done!')
}

main()

Start debugging using CLI:

node inspect index.js

and enable the blackbox by calling Debugger.setBlackBoxPatterns and passing the ignore regex, in our case a simple example-blackbox.js:

debug> Debugger.setBlackboxPatterns({ patterns: ['example-blackbox.js'] })

Afterall, perform a continue and see the script be running without stopping into example-blackbox.js function.

debug> c
< Async done
<
< Done!
<
< Waiting for the debugger to disconnect...

Additional information

The blackbox term was replaced by ignore-list at Google Chrome Dev Tools in latest versions.