Skip to content

Development: Debugging

Jump to bottom
Ben Bucksch edited this page Aug 29, 2025 · 4 revisions

Approaches

Isolate the problem

Before you start with the other debugging techniques, first try to isolate where the error comes from. If you know the start and end of your data flow, you can check the data at the end, start, and somewhere in the middle of the process, whether the data is what you expect. If the data is broken in the middle, the problem must be before that point, and any bugs you see after that point are merely a consequence, not the cause. This avoids that you are chasing the bug in the wrong component.

You can apply this general concept to many aspects: client vs. server (check network trace), frontend vs. logic (check the data in the API between them), etc.

You can apply the same method in a temporal sense when searching the cause of regressions: If you want to know what code change caused a regression, pick one in the start, end, and in the middle, and see when it still worked. This is called "binary search": Find out when it was last working, and when it was first known to be broken, and then pick a git commit in the middle between these two, and test that. If it works there, pick a git commit between that and the end of range, and repeat that process until you isolated a single git commit as culprit.

Stack trace

Get a stack trace of the error, ignore generic functions in it, and see which of the functions might have caused the bug.

Debugger

As discussed above, you can let the debugger break at exceptions/errors, or at given points in the code, and check whether the relevant variables have the values that you expect. Look at previous functions in the stack, and their variables. Walk forward and backwards in time, to see where it goes wrong.

Create reproduction

When you cannot reproduce a bug, see whether other users experienced the same bug. Ask the user to get stack traces, log files, and test data.

See which factors might influence the bug:

  • Type of account (IMAP, EWS etc.)
  • Server (Office365 or Exchange on-premise, the specific Exchange server version, Dovecot or some strange custom IMAP server)
  • Authentication method and server
  • Operating system
  • Virus check or personal firewall installed,
  • Email where the problem occurs
  • Umlauts or other international characters
  • Number of folders or size of the folder or email

etc. See what all users who experience the error have in common. Find the factor that triggers the bug.

The goal is that you can reproduce the bug on your machine, so that you can use the other debugging techniques.

How to run the debugger

Frontend

  1. In the Mustang main window, press F12 or Ctrl-Shift-I to start the Inspector
  2. Tab "Sources"
  3. Set breakpoints, on the bar on the left side of the source line, click on the red dot, which appears on hover
  4. The right panel has the debugger inspection

Backend

  1. Use netstat, look for LISTEN of port 5453 (backend port, on debug builds) or 5355 (release builds), and look for the process ID (PID) of the process.
  2. Use a debugger to connect to that process.

TODO Document how.

Tests

  1. Visual Studio Code
  2. App navigation bar, [Test] button
  3. Left sidebar, hover over a specific test file name
  4. [Debug test] (appears when you hover over the test file name)
  5. Set breakpoints in the source editor, on the left of the line number, clicking the red dot, which appears on hover
  6. Repeat step 4

TODO Alternatives to Visual Studio Code

Clone this wiki locally