Debugging the UI

An important aspect part of developing complex software is good tooling to aid in debugging and take guesswork out of development.

Developer Tools

The Developer Tools automatically open with the development environment, and provide console output, performance profiling and debugger support for the frontend of your application.

Main render thread debug window

In development mode under the File menu, the "Show transport window" button which will open tooling for the transport-manager, responsible for everything to do with hardware interaction. The developer tooling is similar, but provides configurable levels of debug console output for transport and connections libraries.

Transport window debug selection UI and console

Changing the transport-manager debug level requires a full-reload of the application. This happens automatically, but you will lose UI state.

Debugging with Breakpoints

Breakpointing with line-by-line step-through is a staple of serious debugging workflows.

To trigger a breakpoint, in your Typescript code insert the debugger keyword.

  1. export const LightBulb = (props: LightBulbProps) => {
  2. const isDarkMode = useDarkMode()
  3. // application stuff
  4. debugger
  5. return (
  6. <ImageSwitcher ... />
  7. )
  8. }

When hit, the console will pause execution and provide a stacktrace, display variable values, and (top right buttons) allows stepping through code line-by-line, by-function or just to resume execution.

Breakpoint triggered view shows surrounding source and variables

Redux State Viewer

One of the more powerful tools is the Redux tab, which displays the internal state of the application with information about hardware variables, UI side state, and connections information for potential devices.

developer tools showing redux state view

When using the Redux viewer, set the view mode to "State", and the viewer will show the current state of all data in the render thread.

committed is the UI's understanding of hardware tracked variables, and pushed is the UI state for variables. This distinction is made because constructs like Save containers defer hardware writes until prompted.

connections provides a list of all potential devices which pass filtering, and includes useful CONNECTED/DISCONNECTED info, along with connection metadata like latency and jitter.

The Redux state viewer polls the application state periodically, variable changes aren't guaranteed to display at full rate, and some latency is present.

Performance Testing

To diagnose timing or frame-rate issues, the Performance tab offers a suite of diagnostic tools.

Debugger performance window and flamechart

  1. Click the record button in the top left of the developer tool window, and interact with the UI as needed.
  2. Press stop, and the recorded section displays as a flamegraph.
  3. Drag a selection over the flamegraph or frame-timing bars to focus the horizontal axis over the selected slice.

The performance logging process is resource intense and may have a negative impact on your applications performance during recording.

The Window Manager

The window manager is responsible for creating and managing the render windows, global shortcuts, native menus and dialogs. It can be debugged using a Chrome webbrowser to connect to it remotely.

arc prints some information to the console after launch which looks like:

  1. scott@octagonal $ arc start
  2. ✓ Compiled transport bundle successfully.
  3. ✓ Compiled renderer bundle successfully.
  4. Electron: Debugger listening on ws://127.0.0.1:5858/05e86500-287b-4771-a4f9-0d475b66f034
  5. Electron: For help, see: https://nodejs.org/en/docs/inspector

To access the remote debugger, open a Chrome webbrowser and go to http://<host>:<port>/json/list, using the host and port provided in arc output URL. In this example, <http://127.0.0.1:5858/json/list>.

You should see something like this:

Chrome devtools index

Open the remote debugger for Electric UI's root context by navigating to the devtoolsFrontendUrl listed on the json/list page.

Remote devtools for application's electron context

V8 crashes

In dire circumstances, v8 may crash, usually visible with this in the DevTools.

Remote devtools for application's electron context

The next step is to enable Chromium logs, set the environment variable:

ELECTRON_ENABLE_LOGGING=true

Logs will be printed to the main commandline.