debugging

44 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Open DevTools for renderer process programmatically

To debug a renderer process, call the openDevTools() API on the webContents of a BrowserWindow, BrowserView, or WebView instance. The Chromium Developer Tools are available for all renderer processes and are the most comprehensive tool for debugging individual renderer processes.

Example: opening DevTools on a BrowserWindow

const { BrowserWindow } = require('electron') const win = new BrowserWindow() win.webContents.openDevTools()

Main process debugging limitations

The main process cannot have developer tools opened directly. However, the Chromium Developer Tools can be used to debug Electron's main process through Node.js inspector integration, though you may encounter oddities like require not being present in the console.

V8 context crash DevTools message

When the V8 context crashes, DevTools displays the message: 'DevTools was disconnected from the page. Once page is reloaded, DevTools will automatically reconnect.'

Enable Chromium logging with environment variable

Chromium logs can be enabled by setting the ELECTRON_ENABLE_LOGGING environment variable.

Enable Chromium logging with command line argument

Chromium logs can be enabled by passing the --enable-logging command line argument to Electron. An optional file path can be specified to write logs to a file.

Main process debugging requires external debugger

DevTools in an Electron browser window can only debug JavaScript executed in that window. To debug JavaScript executed in the main process, an external debugger is required and Electron must be launched with the --inspect or --inspect-brk command line switch.

--inspect command line switch

The --inspect=[port] switch enables debugging of the main process. Electron will listen for V8 inspector protocol messages on the specified port, and an external debugger needs to connect on this port. The default port is 9229. Example: electron --inspect=9229 your/app

--inspect-brk command line switch

The --inspect-brk=[port] switch is like --inspect but pauses execution on the first line of JavaScript.

Chrome can debug Electron main process

Chrome can be used to debug an Electron app's main process by visiting chrome://inspect and selecting the launched Electron app to inspect.

V8 inspector protocol support required

External debuggers used for main process debugging must support the V8 inspector protocol.

VSCode launch.json configuration for Electron main process debugging

To debug an Electron app's main process in VSCode, create a .vscode/launch.json file with a Node.js launch configuration. The configuration should specify type "node", request "launch", set runtimeExecutable to the Electron binary at ${workspaceFolder}/node_modules/.bin/electron (or electron.cmd on Windows), set cwd to ${workspaceFolder}, args to ["."], and outputCapture to "std". On Windows, override runtimeExecutable to use electron.cmd instead of the UNIX electron binary.

Debugging Electron main process in VSCode

After configuring .vscode/launch.json for the main process, set breakpoints in main.js and start debugging in the Debug View to hit those breakpoints.

VSCode launch.json configuration for debugging Electron C++ codebase on Windows

To debug the native Electron C++ codebase on Windows, create a .vscode/launch.json file with a C++ debugging configuration. Set type to "cppvsdbg" (requires the built-in C/C++ extension ms-vscode.cpptools), request to "launch", program to the path of the electron.exe executable in the build output directory (${workspaceFolder}\out\your-executable-location\electron.exe where your-executable-location depends on build type: "Testing" for default builds, "Release" for release builds, or a custom directory name if specified during build), args to your Electron project path, stopAtEntry to false, cwd to ${workspaceFolder}, externalConsole to false, and set environment variables: ELECTRON_ENABLE_LOGGING to "true", ELECTRON_ENABLE_STACK_DUMPING to "true", and ELECTRON_RUN_AS_NODE to empty string. Use sourceFileMap to map the original source path (e.g., "o:\") to the workspace folder.

Debugging native Electron C++ code requires cppvsdbg debugger

The cppvsdbg debugger type requires the built-in C/C++ extension (ms-vscode.cpptools) to be enabled in VSCode.

${workspaceFolder} in Electron C++ debugging refers to Chromium src directory

When debugging the native Electron codebase, ${workspaceFolder} represents the full path to Chromium's src directory, not a typical application workspace.

Electron build output directory structure for debugging

The your-executable-location component in the electron.exe path varies depending on build configuration: "Testing" is used for default builds from Electron Build-Tools or default build instructions; "Release" is used if a Release build was created instead of a Testing build; or a custom directory name if modified during the build process.

Debugging Electron C++ code with breakpoints

Set breakpoints in .cc files of the native Electron C++ codebase and start debugging in the Debug View to hit those breakpoints.

DevTools extension loading with tooling

The easiest way to load a DevTools extension in Electron is to use third-party tooling to automate the process. The popular NPM package electron-devtools-installer automates DevTools extension loading.

Manual DevTools extension loading steps

To manually load a DevTools extension: (1) Install the extension in Google Chrome; (2) Navigate to chrome://extensions and find its extension ID, which is a hash string; (3) Find the filesystem location where Chrome stores extensions; (4) Pass the extension location to the ses.loadExtension API.

Chrome extension storage paths by platform

Chrome stores extensions in platform-specific locations: on Windows it is %LOCALAPPDATA%\Google\Chrome\User Data\Default\Extensions; on Linux it could be ~/.config/google-chrome/Default/Extensions/, ~/.config/google-chrome-beta/Default/Extensions/, ~/.config/google-chrome-canary/Default/Extensions/, or ~/.config/chromium/Default/Extensions/; on macOS it is ~/Library/Application Support/Google/Chrome/Default/Extensions.

loadExtension API example with React Developer Tools

This example shows how to load React Developer Tools in an Electron app: ```js const { app, session } = require('electron') const os = require('node:os') const path = require('node:path') // on macOS const reactDevToolsPath = path.join( os.homedir(), '/Library/Application Support/Google/Chrome/Default/Extensions/fmkadmapgofadopljbjfkapdkoienihi/4.9.0_0' ) app.whenReady().then(async () => { await session.defaultSession.loadExtension(reactDevToolsPath) }) ```

loadExtension returns Promise with Extension object

The loadExtension API returns a Promise with an Extension object containing metadata about the loaded extension. This promise must resolve (using await) before loading a page, otherwise the extension is not guaranteed to load.

loadExtension timing constraints

The loadExtension API cannot be called before the ready event of the app module is emitted. It also cannot be called on in-memory (non-persistent) sessions.

loadExtension must be called on every app boot

The loadExtension API must be called on every boot of your app if you want the extension to be loaded. Loaded extensions are not persisted between app launches.

Remove DevTools extension with removeExtension

You can pass the extension's ID to the ses.removeExtension API to remove it from your Session.

Limited chrome API support for DevTools extensions

Electron only supports a limited set of chrome.* APIs. Extensions using unsupported chrome.* APIs may not work in Electron.

Tested DevTools extensions in Electron

The following DevTools extensions have been tested to work in Electron: Ember Inspector, React Developer Tools, Backbone Debugger, jQuery Debugger, Vue.js devtools, Cerebral Debugger, Redux DevTools Extension, and MobX Developer Tools.

DevTools extension troubleshooting

If a DevTools extension is not working, first verify the extension is still maintained and compatible with the latest version of Google Chrome. If the extension works on Chrome but not on Electron, file a bug in Electron's issue tracker describing which part is not working.

REPL in main process via --interactive flag

Electron exposes the Node.js repl module through the --interactive CLI flag. You can start a REPL for the main process by running './node_modules/.bin/electron --interactive' if electron is installed as a local project dependency.

REPL not available on Windows main process

The --interactive flag for accessing the REPL in the main process is not available on Windows.

REPL in renderer process via DevTools Console

You can access a REPL for any renderer process using the DevTools Console tab. This provides an interactive environment for evaluating expressions in the renderer context.

VS Code debugging configuration for main and renderer processes

Example .vscode/launch.json configuration with three parts: 'Main' configuration uses type 'node' and starts the main process with --remote-debugging-port=9222; 'Renderer' configuration uses type 'chrome' and attaches to port 9222; 'Main + renderer' is a compound task that runs both simultaneously. The main process exposes port 9222 for the renderer debugger to attach to.

Debugger may skip first lines when attaching to renderer

When attaching a debugger to a renderer process, the first lines of code may be skipped because the debugger does not have time to connect before execution. Work around this by refreshing the page or setting a timeout before executing code in development mode.

Use lldb for native Electron debugging on macOS

To debug crashes or issues in Electron's native code (C++) on macOS, use lldb with step-through debugging and breakpoints. This is necessary when issues are caused by Electron itself rather than JavaScript application code.

Requirements for debugging Electron on macOS

Debugging Electron on macOS requires three things: (1) a testing build of Electron built from source rather than a downloaded binary, since downloaded binaries are heavily optimized making debugging difficult; (2) Xcode with command line tools including LLDB; (3) a configured ~/.lldbinit file to properly source-map Chromium code.

.lldbinit configuration for Electron debugging

Create or edit ~/.lldbinit with the following content to enable proper source-mapping of Chromium code: script sys.path[:0] = ['<path/to/electron/src/tools/lldb>']; script import lldbinit

Start lldb debugging session with Electron

Start debugging by opening Terminal and running: lldb ./out/Testing/Electron.app or use: target create "./out/Testing/Electron.app"

Set breakpoints in Electron source code using lldb

Set breakpoints on specific lines in Electron source files using the command: breakpoint set --file filename.cc --line line_number. Relevant code files are found in ./shell/

Why debugging downloaded Electron binaries is difficult

Downloaded Electron binaries are heavily optimized, which causes several debugging problems: the debugger cannot show the content of all variables, the execution path appears strange due to compiler optimizations like inlining and tail calls, and execution flow is hard to follow.

lldb step and next commands for Electron debugging

Use 'step' (or 's') to do source-level single stepping in the current thread, which follows into function calls. Use 'next' (or 'n') to step over function calls without entering them.

View variables in lldb during Electron debugging

Run 'frame variable' (or 'fr v') to show the arguments and local variables for the current frame during debugging.

Continue execution in lldb debugger

Run 'process continue' to finish debugging and resume execution. Use 'thread until 100' to continue until line 100 is hit in the current thread, which stops if execution leaves the current frame.

Missing .lldbinit causes source code not to display

If source code does not appear when expected during lldb debugging of Electron, it likely indicates that the ~/.lldbinit file has not been properly added to configure source-mapping.

Give your agent this brain