Debugging Finsemble

This tutorial provides a holistic overview of techniques that will allow you to quickly iterate with Finsemble. If you are in need of targeted support, check out Troubleshooting.

Updating the Finsemble framework

If you're encountering any bugs, please first make certain that you're using the latest version of Finsemble. You can ascertain this through package.json in ../node_modules/@finsemble/finsemble-core/package.json.

Updating the framework

To update the underlying Finsemble framework, run the following commands from your local repository directory:

npm update @finsemble/finsemble-core

Updating the CLI

To update the Finsemble CLI, run the following commands from your local repository directory:

npm update -g @finsemble/finsemble-cli

Updating the entire package

Due to a bug with Gulp 4.0, npm update will not update Gulp correctly. If you need to update the entire package you will need to follow this procedure:

rmdir /S node_modules
npm cache clean
npm install
npm install -g @finsemble/finsemble-cli

Using the Chromium Debugger

Finsemble runs on top of Chromium, which contains the same debugging tools that you are used to in Chrome.

From the Google Chrome browser, enter "chrome://inspect" in the location bar.
Click "Open Dedicated Devtools for Node."
Click the "Connection" tab and add "localhost:9090" as a connection.
A link to debug each Electron window will appear.
Once you've followed these steps, you can press CTRL+SHIFT+I to pop up Chromium's debug tools in a new window.

An alternative debugging method is to open a browser and navigate to http://localhost:9090. Each window in your application is listed on that page. Click on the window you wish to debug and a Chromium Console will be launched for that window. There are some limitations (e.g., you can't evaluate code in the console in a remote session), but it largely acts as you would expect.

You can also force a component to spawn its console window along with itself by adding the appropriate prop to the component's config. More info can be found in the config reference

Note: Only logger errors and warnings are written both to the Central Logger and Chrome Console. All the other logger functions (log, info, debug, verbose) are not captured by the Console.

Webpack

When you open your component code with a debugger, you will see that it has been wrapped in a containing function. Finsemble uses Webpack as part of its build process. This provides automatic isolation of modules, automatic building of React modules, etc. For the purpose of debugging, you can simply ignore this wrapper. Place your breakpoints inside your code and it should behave as expected.

You can modify the Webpack config files, if necessary, for your own component and service code (for instance, if you are using a framework other than React). For more about the build process, see the Build Process tutorial.

Debugging inside the Finsemble Library

The Finsemble Library (FSBL.js) is automatically injected into Chromium. This conveniently allows you to use Finsemble on any page without having to explicitly include the library. Chromium can be persnickety about debugging inside of such files (VM files). To get around this, you can manually include FSBL.js with a script tag:

<script src="/fin/FSBL.js"></script>

Finsemble's log files

Finsemble's log files can be found in AppData\Roaming\Electron\logs.

Debugging a service

Debugging a service can be difficult because the service initialization happens before the Central Logger comes online. This issue can be eliminated by configuring Finsemble to open the service’s Chromium DevTools Console when the service is launched. In the service’s configuration, add a property visible and set it to true. This can also be done to debug core Finsemble services (e.g., Config Service, Storage Service, etc.). The services’ configuration can be found in ../node_modules/@finsemble/finsemble-core/configs/core/services.json. You can either edit the config there or copy it to ..configs/application/services.json.

An example of this configuration for the Storage Service:

{
    "services": {
        "storageService": {
            "spawnAs": "window",
            "name": "storageService",
            "html": "$servicesRoot/storage/storage.html",
            "file": "$servicesRoot/storage/storageService.js",
            "category": "system",
            "visible": true
        }
    }
}

FSBL.debug - Menus and the Toolbar

FSBL.debug is a boolean value. If set to true, menus will not hide on blur, and you will be able to reload the toolbar. Set the value anywhere inside of the menu or toolbar code.

Debugging the Storage Adapter

To debug the Storage Adapter, you should also configure visible to true. Start Finsemble and, when the service is visible, search for the Adapter’s file name (e.g., localStorageAdapter.js). Put breakpoints in the Storage Adapter as desired. To debug initialization, you may need to set breakpoints and restart Finsemble.

If breakpoints are not hit in the Storage Adapter, set breakpoints for Storage Adapter methods (get, save, delete, keys, clearCache and empty) in the Storage Service; it has corresponding methods.

Debugging start-up and the system log

The System Manager Service controls Finsemble's start-up processes. The System Manager also provides a basic but always available system log for diagnostics. Whenever there is a start-up problem, it's best to first check the system log. The system log provides:

The state of the start-up sequence
Catastrophic error messages
A copy of all user notifications since last start-up

You can access the system log in one of three ways:

The log will always be displayed when the manifest’s startup_app.autoShow value is set to true.
The log will be displayed only on startup error when the manifest config has finsemble.bootConfig.onErrorMakeSystemManagerVisible set to true.
The log can be manually displayed by selecting "System Log" in the Finsemble menu.

Depending on the case, more detailed diagnostic information can be found in the Chromium DevTools Console for the System Manager Service (see above).

Iterate quickly

Reload

It isn't necessary to completely quit the application between program iterations. The dev runner automatically watches for code changes and repackages on the fly. Once you make a change and save your code, simply reload the component by right-clicking in the component and choosing "Reload." You can also press CTRL+ALT+R to reload the window that you're focused on.

Resetting your application

As you work on your test application, the application state will be saved to the activeWorkspace. If you need to start from scratch, you can delete this workspace. To clear your storage, you can use the Storage Client:

FSBL.Clients.StorageClient.clearCache(console.log);

Note: Be sure to quit your application without changing the location of any windows! You want to be sure that a new workspace isn't saved before you quit.

Deleting your cache

Note: This will also delete the storage for all of your Finsemble applications!

Navigate to: C:\Users<your user>\AppData\Roaming\Electron
Delete the cache folder

Note: AppData\Roaming\Electron\localStorage is the local storage, while "cache" is cached web pages. AppData\Roaming\Finsemble-Electron\cache is a cache of preload files.

Killing Finsemble

Hitting CTRL+C in your command prompt on your npm run process kills the application immediately. If this action is taken, it's possible that Finsemble may not have had time to save recent workspace changes. In general, choosing Quit in the toolbar will avoid state issues.

Common failure points (and their solutions)

`npm run dev` does nothing

If npm run dev does nothing and the runtime is hung, it may be because you have zombie processes. This can occur, for instance, if you kill off the dev runner before the application has properly started.

To get back to a good state, open your Windows Task Manager and kill AssimilationMain.exe, if it is running. You might also have to kill all processes from your container (usually Electron) that are running. You should then be able to start the dev runner again. You may also delete your cache (see above) to solve this issue.

How can I inspect configuration settings if Finsemble doesn't come up?

- Case 1: The toolbar is up

If the toolbar is up, you launch the Central Logger to view the complete manifest containing Finsemble's configuration. First, bring up the Central Logger and ensure all service and component logging is visible by clicking on "Toggle All." Next, enter "processed manifest" into the "Filter Log" box (as opposed to the "Filter Client List" input box). The filtered log entry includes the complete run-time manifest with Finsemble's complete configuration under the FSBL object.

For this case, the data shown is after configuration has been fully processed on startup (e.g., macro's expanded, configuration files imported) but dynamic configuration changes haven't taken place yet. To see configuration after dynamic configuration changes, filter logs using "revised manifest" to get the revised configuration object.

- Case 2: The toolbar isn't fully up, but the Central Logger is up

In this scenario, Case 1 instructions might be useful; however that data may or may not exist depending on where start-up failed. Therefore, a third log filter, "initial manifest," is available to show the bootstrap configuration, which is the minimal initial configuration pulled from the manifest and Finsemble's core configuration in order to start the essential Finsemble services.

- Case 3: The toolbar isn't up and the Central Logger isn't up

If neither the toolbar nor the Central Logger are available, configuration can be seen using the Chromium Console through http://localhost:9090. If the Config Service exists, its console's output can be filtered using "processed manifest." However, that data may or may not exist depending on where start-up failed.

A more reliable option is to go into the "ServiceManager" window using http://localhost:9090. Click on the Central Logger entry and enter the command showConsole(). Filter on "initial manifest" to see the bootstrap configuration.

For all cases above, the Central Logger's log should also be inspected for configuration-related error messages (by turning off filtering and enabling only error messages).

Finsemble runs on top of a Chromium, which contains the same debugging tools that you're used to in Chrome. Use CTRL+ALT+I on any window to open the debugger.