mirror of
https://github.com/electron/electron.git
synced 2026-10-28 11:44:46 +08:00
Subhadeep
1a285fc6dd
* docs: clarify debugger.sendCommand timing and empty-result behavior
Documents two long-standing but undocumented behaviors of
debugger.sendCommand():
- Commands sent before the target has navigated may not resolve
until navigation occurs.
- Commands whose protocol response has no `result` data resolve
with an empty object (`{}`), not `null` or `undefined`.
Both behaviors were originally reported in #14810 and #14811
(closed as working-as-intended) and re-verified against current
Electron's Promise-based sendCommand API before writing this up.
Fixes #14822
* docs: use [!NOTE] alert syntax per review feedback
* docs: keep markdownlint comment inside blockquote so [!NOTE] renders correctly
The disable comment wasn't prefixed with `>`, which split the blockquote
into two separate blocks on GitHub's renderer instead of one alert box.
Verified via the markdown render API before and after.
105 lines
3.3 KiB
Markdown
105 lines
3.3 KiB
Markdown
## Class: Debugger
|
|
|
|
> An alternate transport for Chrome's remote debugging protocol.
|
|
|
|
Process: [Main](../glossary.md#main-process)<br />
|
|
_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
|
|
|
|
Chrome Developer Tools has a [special binding][rdp] available at JavaScript
|
|
runtime that allows interacting with pages and instrumenting them.
|
|
|
|
```js
|
|
const { BrowserWindow } = require('electron')
|
|
|
|
const win = new BrowserWindow()
|
|
|
|
try {
|
|
win.webContents.debugger.attach('1.1')
|
|
} catch (err) {
|
|
console.log('Debugger attach failed : ', err)
|
|
}
|
|
|
|
win.webContents.debugger.on('detach', (event, reason) => {
|
|
console.log('Debugger detached due to : ', reason)
|
|
})
|
|
|
|
win.webContents.debugger.on('message', (event, method, params) => {
|
|
if (method === 'Network.requestWillBeSent') {
|
|
if (params.request.url === 'https://www.github.com') {
|
|
win.webContents.debugger.detach()
|
|
}
|
|
}
|
|
})
|
|
|
|
win.webContents.debugger.sendCommand('Network.enable')
|
|
```
|
|
|
|
### Instance Events
|
|
|
|
#### Event: 'detach'
|
|
|
|
Returns:
|
|
|
|
* `event` Event
|
|
* `reason` string - Reason for detaching debugger.
|
|
|
|
Emitted when the debugging session is terminated. This happens either when
|
|
`webContents` is closed or DevTools is invoked for the attached `webContents`.
|
|
|
|
#### Event: 'message'
|
|
|
|
Returns:
|
|
|
|
* `event` Event
|
|
* `method` string - Method name.
|
|
* `params` any - Event parameters defined by the 'parameters'
|
|
attribute in the remote debugging protocol.
|
|
* `sessionId` string - Unique identifier of attached debugging session,
|
|
will match the value sent from `debugger.sendCommand`.
|
|
|
|
Emitted whenever the debugging target issues an instrumentation event.
|
|
|
|
[rdp]: https://chromedevtools.github.io/devtools-protocol/
|
|
|
|
### Instance Methods
|
|
|
|
#### `debugger.attach([protocolVersion])`
|
|
|
|
* `protocolVersion` string (optional) - Requested debugging protocol version.
|
|
|
|
Attaches the debugger to the `webContents`.
|
|
|
|
#### `debugger.isAttached()`
|
|
|
|
Returns `boolean` - Whether a debugger is attached to the `webContents`.
|
|
|
|
#### `debugger.detach()`
|
|
|
|
Detaches the debugger from the `webContents`.
|
|
|
|
#### `debugger.sendCommand(method[, commandParams, sessionId])`
|
|
|
|
* `method` string - Method name, should be one of the methods defined by the
|
|
[remote debugging protocol][rdp].
|
|
* `commandParams` any (optional) - JSON object with request parameters.
|
|
* `sessionId` string (optional) - send command to the target with associated
|
|
debugging session id. The initial value can be obtained by sending
|
|
[Target.attachToTarget][attachToTarget] message.
|
|
|
|
[attachToTarget]: https://chromedevtools.github.io/devtools-protocol/tot/Target/#method-attachToTarget
|
|
|
|
Returns `Promise<any>` - A promise that resolves with the response defined by
|
|
the 'returns' attribute of the command description in the remote debugging protocol
|
|
or is rejected indicating the failure of the command.
|
|
|
|
Send given command to the debugging target.
|
|
|
|
> [!NOTE]
|
|
> <!-- markdownlint-disable-next-line MD032 -->
|
|
> * If `sendCommand` is called before the target has navigated (e.g.
|
|
> immediately after `attach()`), the returned promise may not resolve
|
|
> until navigation occurs.
|
|
> * If the command's response has no `result` data, as defined by that
|
|
> command's entry in the remote debugging protocol, the promise
|
|
> resolves with an empty object (`{}`), not `null` or `undefined`.
|