Reporting Bugs

When something goes wrong in your IC application, the first step is collecting information. The framework has a built-in logging system that captures frontend activity and makes it accessible from MATLAB. This article covers how to enable it, read the logs, and put together a useful bug report.

Enabling the logger

Logging is off by default. Set Debug to true on the Frame to start capturing frontend log entries. While debug mode is active, every log entry is also printed to the MATLAB command window as it arrives:

frame.Debug = true;

You can narrow down what gets captured by setting the LogLevel property. The four levels, from lowest to highest priority, are: debug, info, warn, and error. Setting a level filters out everything below it:

frame.LogLevel = "debug";   % everything (default)
frame.LogLevel = "info";    % skip debug messages
frame.LogLevel = "warn";    % only warnings and errors
frame.LogLevel = "error";   % only errors

For general debugging, leave the level at "debug" to capture everything. If the volume is too high, switch to "warn" to focus on problems:

frame.Debug = true;
frame.LogLevel = "warn";

Reading the logs

The frame.logs() method returns the ic.core.Logger instance that collects all frontend entries. The logger stores up to 1000 entries in a circular buffer: when the buffer is full, the oldest entry is dropped.

The quickest way to inspect logs is show(), which prints the most recent entries to the command window:

frame.logs().show(10);

Each entry includes a timestamp, the log level, the source module (the part of the framework that generated the message), and the message itself. If the entry carries additional context (component IDs, shortcut names, error details), it is printed indented below the message:

>> frame.logs().show(5)
14:32:01.123 [DEBUG] [Bridge] Dispatching event
14:32:01.145 [INFO]  [Logger] Debug mode enabled
14:32:01.200 [WARN]  [Container] @remove: Child not found
              childId: ic-btn-42
14:32:01.312 [ERROR] [EffectManager] Effect execution failed
              effectId: a3f1-...
              expression: (s, b) => { ... }
14:32:02.001 [INFO]  [KeyboardManager] Added shortcut
              componentId: ic-editor-1
              shortcut: Ctrl+S

Filing a bug report

When you encounter a bug in the IC framework, a good report helps fix it quickly. Here is a checklist:

1. Collect logs and environment info

% 1. Enable logging
frame.Debug = true;
frame.LogLevel = "debug"; % or higher to reduce noise

% 2. Reproduce the bug
% ... interact with your app ...

% 3. Collect the logs
logs = frame.logs().all();

% 4. Save to file
writetable(logs, "bug-report-logs.csv");

When you enable debug mode, the logger automatically captures the Chromium version used by MATLAB’s embedded browser. This shows up as one of the first entries.

2. Note your environment

The key details to include:

  • MATLAB version: the output of ver (release name and number)
  • Operating system: Windows, macOS, or Linux, and the version
  • IC framework version: the commit hash or release tag you are using
  • Chromium version: you can find it in the first few log entries under the “Logger” source, when logging at debug level is enabled. 
    % collect MATLAB version
ver

% check Chromium version (logged on debug enable)
frame = ic.Frame();
frame.Debug = true;
frame.LogLevel = "debug";
wait(2);
frame.logs().filter(Source="Logger", Limit=3);

3. Open an issue

File the bug at github.com/LordTumnus/ic/issues. Include:

  • A short description of what you expected vs. what happened
  • Steps to reproduce (ideally a minimal MATLAB script)
  • The exported log file or the output of frame.logs().show()
  • Your MATLAB version and OS

The more specific the reproduction steps, the faster the fix. If the bug is visual (layout glitches, rendering artifacts), a screenshot helps too.