inspector: add a document and a test for inspector.emitProtocolEvent

doc/api/inspector.md

@@ -429,6 +429,34 @@ require('node:inspector').console.log('a message');
 The inspector console does not have API parity with Node.js
 console.
 
+### `inspector.emitProtocolEvent(eventName[, params])`
+
+<!-- YAML
+added:
+ - REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* `eventName` {string}
+* `params` {Object}
+
+Emits a protocol event with the specified `eventName` and optional `params`. This function allows you to send
+custom events that conform to the DevTools protocol, facilitating integration with debugging and inspection tools.
+The emitted events can be captured by connected DevTools Frontend instances, such as Chrome DevTools.
+
+```js
+inspector.emitProtocolEvent('NodeNetwork.requestWillBeSent', {
+  requestId: 'request-id-1',
+  timestamp: Date.now() / 1000,
+  wallTime: Date.now(),
+  request: {
+    url: 'https://nodejs.org/en',
+    method: 'GET',
+  }
+});
+```
+
 ### `inspector.open([port[, host[, wait]]])`
 
 <!-- YAML

lib/inspector.js

@@ -191,8 +191,10 @@ function inspectorWaitForDebugger() {
 
 function inspectorEmitProtocolEvent(eventName, params) {
   validateString(eventName, 'eventName');
-  validateObject(params, 'params');
-  emitProtocolEvent(eventName, JSONStringify(params));
+  if (params) {
+    validateObject(params, 'params');
+  }
+  emitProtocolEvent(eventName, JSONStringify(params ?? {}));
 }
 
 module.exports = {

test/parallel/test-inspector-emit-protocol-event.mjs

@@ -0,0 +1,46 @@
+// Flags: --inspect=0
+
+import * as common from '../common/index.mjs';
+
+common.skipIfInspectorDisabled();
+
+import inspector from 'node:inspector';
+import assert from 'node:assert';
+
+const session = new inspector.Session();
+session.connect();
+
+assert.throws(() => inspector.emitProtocolEvent(123), {
+  name: 'TypeError',
+  code: 'ERR_INVALID_ARG_TYPE',
+  message: 'The "eventName" argument must be of type string. Received type number (123)'
+});
+
+assert.throws(() => inspector.emitProtocolEvent('NodeNetwork.requestWillBeSent', 'params'), {
+  name: 'TypeError',
+  code: 'ERR_INVALID_ARG_TYPE',
+  message: 'The "params" argument must be of type object. Received type string (\'params\')'
+});
+
+session.on('NodeNetwork.requestWillBeSent', common.mustCall(({ params }) => {
+  assert.deepStrictEqual(params, {
+    requestId: 'request-id-1',
+    request: {
+      url: 'https://nodejs.org/en',
+      method: 'GET'
+    },
+    timestamp: 1000,
+    wallTime: 1000,
+  });
+}));
+
+inspector.emitProtocolEvent('NodeNetwork.requestWillBeSent', {
+  requestId: 'request-id-1',
+  request: {
+    url: 'https://nodejs.org/en',
+    method: 'GET'
+  },
+  timestamp: 1000,
+  wallTime: 1000,
+  unknown: 'unknown'
+});