Skip to content

Latest commit

 

History

History
182 lines (133 loc) · 5.81 KB

inspector.md

File metadata and controls

182 lines (133 loc) · 5.81 KB
Raw

Inspector

Stability: 1 - Experimental

The inspector module provides an API for interacting with the V8 inspector.

It can be accessed using:

const inspector = require('inspector');

inspector.attachContext(contextifiedSandbox[, options])

  • contextifiedSandbox {Object} The contextified object to attach to the inspector.
  • options {Object}
    • name {string} Name of the context. If not specified, a default name vm Module Context ${idx} where idx is the incrementing index corresponding to this call will be used.
    • origin {string} URL of the webpage this context corresponds to. Defaults to false.

Make inspector aware of the specified context. This allows code running in that context to be debugged, including support for debugger statement. If the context is already being tracked by inspector, this function is a no-op.

Note: Calling this function will prevent contextifiedSandbox from being garbage collected. To prevent memory leaks, [inspector.detachContext()][] must be called after work on the context has been completed.

inspector.contextAttached(contextifiedSandbox)

  • contextifiedSandbox {Object} A contextified object
  • Returns: {boolean}

Check if the specified context is attached to V8 inspector.

inspector.detachContext(contextifiedSandbox)

  • contextifiedSandbox {Object} The contextified object to detach from inspector

Inform the V8 inspector that the context has been destroyed. If the context is not being tracked by inspector, this function is a no-op.

inspector.open([port[, host[, wait]]])

  • port {number} Port to listen on for inspector connections. Optional, defaults to what was specified on the CLI.
  • host {string} Host to listen on for inspector connections. Optional, defaults to what was specified on the CLI.
  • wait {boolean} Block until a client has connected. Optional, defaults to false.

Activate inspector on host and port. Equivalent to node --inspect=[[host:]port], but can be done programatically after node has started.

If wait is true, will block until a client has connected to the inspect port and flow control has been passed to the debugger client.

inspector.close()

Deactivate the inspector. Blocks until there are no active connections.

inspector.url()

Return the URL of the active inspector, or undefined if there is none.

Class: inspector.Session

The inspector.Session is used for dispatching messages to the V8 inspector back-end and receiving message responses and notifications.

Constructor: new inspector.Session()

Create a new instance of the inspector.Session class. The inspector session needs to be connected through session.connect() before the messages can be dispatched to the inspector backend.

inspector.Session is an EventEmitter with the following events:

Event: 'inspectorNotification'

  • {Object} The notification message object

Emitted when any notification from the V8 Inspector is received.

session.on('inspectorNotification', (message) => console.log(message.method));
// Debugger.paused
// Debugger.resumed

It is also possible to subscribe only to notifications with specific method:

Event: <inspector-protocol-method>

  • {Object} The notification message object

Emitted when an inspector notification is received that has its method field set to the <inspector-protocol-method> value.

The following snippet installs a listener on the Debugger.paused event, and prints the reason for program suspension whenever program execution is suspended (through breakpoints, for example):

session.on('Debugger.paused', ({ params }) => {
  console.log(params.hitBreakpoints);
});
// [ '/node/test/inspector/test-bindings.js:11:0' ]

session.connect()

Connects a session to the inspector back-end. An exception will be thrown if there is already a connected session established either through the API or by a front-end connected to the Inspector WebSocket port.

session.post(method[, params][, callback])

  • method {string}
  • params {Object}
  • callback {Function}

Posts a message to the inspector back-end. callback will be notified when a response is received. callback is a function that accepts two optional arguments - error and message-specific result.

session.post('Runtime.evaluate', { expression: '2 + 2' },
             (error, { result }) => console.log(result));
// Output: { type: 'number', value: 4, description: '4' }

The latest version of the V8 inspector protocol is published on the Chrome DevTools Protocol Viewer.

Node inspector supports all the Chrome DevTools Protocol domains declared by V8. Chrome DevTools Protocol domain provides an interface for interacting with one of the runtime agents used to inspect the application state and listen to the run-time events.

session.disconnect()

Immediately close the session. All pending message callbacks will be called with an error. session.connect() will need to be called to be able to send messages again. Reconnected session will lose all inspector state, such as enabled agents or configured breakpoints.