mirror of
https://github.com/MichMich/MagicMirror.git
synced 2025-06-27 19:53:36 +00:00
Large edit to reorganize, include additional details, introduce the difference between automated & manual testing, and highlight the most useful information.
John Fisher
parent
960c38137d
commit
77fe849312
@ -1,48 +1,77 @@
|
||||
### How to debug your module while in development?
|
||||
### General Debug Tips ###
|
||||
* Remove (or disable) all other modules (except clock) to make it start/run faster and to isolate your module under development.
|
||||
* Run your MM in *server mode*, allowing you to still use your RPi (or what have) in GUI mode. CPU resource utilization is also somewhat reduced in server mode.
|
||||
* To prevent unnecessary headaches, utilize automated "linters" when possible before deploying and running your code.
|
||||
* Create automated unit and integration tests to protect against unintentional breakages of working features and regression defects.
|
||||
|
||||
As it can take several seconds and even minutes to restart your MM, it may be a bottleneck for development efficiency. Here are a (very) few suggestions to help debug your MM Module while under development.
|
||||
|
||||
There are at least 2-3 ways to [test modules](https://forum.magicmirror.builders/topic/86/how-to-troubleshoot/7):
|
||||
### Automated Testing vs. Manual Debugging ###
|
||||
There is a distinction between the terms "testing" and "debugging". Usually, debugging refers to manually interacting with the application to provoke and analyze its behavior in an attempt to find defects or missing requirements. Conversely, automated testing involves the creation or utilization of code which validates the syntax and function of your application.
|
||||
|
||||
### Automated Testing & Validations ###
|
||||
Static code analysis (commonly referred to as "linting") involves a scan and validation of your files against a set of specific set of rules - usually common violations. These scans can be conducted either with a locally installed or a website "linter".
|
||||
|
||||
#### Automated config file validation ####
|
||||
There is already a local linter installed which can automatically check the MM configuration file. It is invoked with `npm run config:check`, example output below:
|
||||
|
||||
```bash
|
||||
user@hostmachine:~/MagicMirror$ npm run config:check
|
||||
|
||||
> magicmirror@2.1.3 config:check /home/daddle/MagicMirror
|
||||
> node tests/configs/check_config.js
|
||||
|
||||
Checking file... /home/daddle/MagicMirror/config/config.js
|
||||
Line 30 col 9 Expected '}' to match '{' from line 28 and instead saw 'distance'.
|
||||
Line 30 col 17 Expected '}' to match '{' from line 25 and instead saw ':'.
|
||||
Line 30 col 19 Expected ']' to match '[' from line 24 and instead saw 'miles'.
|
||||
Line 35 col 6 Missing semicolon.
|
||||
Line 35 col 5 Unrecoverable syntax error. (55% scanned).
|
||||
user@hostmachine:~/MagicMirror$
|
||||
```
|
||||
|
||||
#### Automated JS file validation ####
|
||||
Utilize a JS linter, such as [jslint.com](http://jslint.com/) and the [jslint on npm](https://www.npmjs.com/package/jslint).
|
||||
|
||||
|
||||
----
|
||||
|
||||
### Manual Debugging ###
|
||||
|
||||
This method is tedious, time-consuming, and usually the most frustrating method of troubleshooting. As it can take several seconds and even minutes to restart your MM, it may be a bottleneck for development efficiency. Automated testing and validation are faster, cheaper, and reusable.
|
||||
|
||||
There are at least 2-3 methods to [debugging modules](https://forum.magicmirror.builders/topic/86/how-to-troubleshoot/7):
|
||||
|
||||
1. Directly on MM itself (native mode)
|
||||
2. Directly on MM itself (server mode)
|
||||
3. As a node server or on a different machine [TBA]
|
||||
|
||||
* It's especially beneficial while debugging at runtime to isolate the module under development by disabling all other modules (except clock). Isolation avoids the startup and performance impact of other modules.
|
||||
|
||||
#### Server-mode debugging
|
||||
|
||||
* Run your MM in *server mode*, allowing you to still use your RPi (or what have) in GUI mode. CPU resource utilization is also somewhat reduced in server mode.
|
||||
* To debug your JS and view `console.log()` output, use your browser's `Developer Tools` (usually activated by `CTRL-SHIFT-i`).
|
||||
|
||||
|
||||
----
|
||||
|
||||
#### General Debug Tips
|
||||
### Logging ###
|
||||
|
||||
* Run your MM in *server mode*, so that you still can use your RPi (or what have) in GUI mode, this also reduces it's CPU resources somewhat.
|
||||
* Disable all other modules (except clock) to make it start/run faster and to isolate your Dev Module
|
||||
* Use your browsers' `Developer Tools` (usually activated by `CTRL-SHIFT-i`) to check/debug JS etc.
|
||||
* Check your JS code with some external site, like [jslint](http://jslint.com/)
|
||||
* Check your JS code with some GUI (*Visual Studio*?) or command line utility... [TBA]
|
||||
* Check your PM2 logs with `pm2 logs mm` or check the log files in their locations:
|
||||
#### Logging Errors and Info to the "console" ####
|
||||
|
||||
- `/home/pi/.pm2/pm2.log`
|
||||
- `/home/pi/.pm2/logs/mm-error-0.log`
|
||||
- `/home/pi/.pm2/logs/mm-out-0.log`
|
||||
It is usually unclear to first-time users what or where the "console" is. The primary reason for this is that it depends on what, where, and how the log call gets produced.
|
||||
|
||||
* Finally, and most useful, check the entire *npm* configuration with: `npm run config:check`
|
||||
|
||||
```bash
|
||||
cd ~/MagicMirror/
|
||||
npm run config:check
|
||||
```
|
||||
|
||||
#### Logging Errors and info to "console"
|
||||
|
||||
It's not clear to first time users what is the "console" or where it is. The reason is that it depends on what is producing the log call, where it is produced and how.
|
||||
|
||||
To keep things as brief as possible, to debug using the JS `console.log()` calls, there are various variations available. In the MM core there are some logging wrappers that can be used in your core *MMM-something.js* code. These are:
|
||||
##### Logging From *MMM-your-module.js* ####
|
||||
Although there are several variations of JS `console.log()` calls, to keep things as simple as possible, MM core provides a few logging wrappers that you can use in your core *MMM-something.js* code. These are:
|
||||
|
||||
```js
|
||||
Log.info('error'); # To log to stderr
|
||||
Log.info('info'); # To log to stdout
|
||||
Log.log('log'); # To log to stdout
|
||||
Log.error('info'); # To log to stdout
|
||||
Log.error('error'); # To log to stderr
|
||||
```
|
||||
|
||||
However, from within your *node_helper.js*, if you have one, these are not available (AFAIK), so there you have to use the standard JS loggers. There are quite a [few variations](https://console.spec.whatwg.org/#namespacedef-console) of those, with various success rates, depending on where you want the message to appear.
|
||||
##### Logging From *node-helper.js*
|
||||
These are not available (AFAIK) if you are using a *node_helper.js*, so you'll have to use the standard JS loggers there. As mentioned, there are quite a [few variations](https://console.spec.whatwg.org/#namespacedef-console) of these (and they result in varying success rates) depending on where you want the message to appear.
|
||||
|
||||
* Do you want your log message to go to the Browser (DevTools) log?
|
||||
* Do you want your log message to go to the MagicMirror debug log?
|
||||
@ -56,12 +85,20 @@ console.error(any... data)
|
||||
console.dir(any item, optional object? options)
|
||||
```
|
||||
|
||||
#### Reviewing logs written to disk ####
|
||||
Check your PM2 logs with `pm2 logs mm` or check the log files in their locations:
|
||||
- `/home/pi/.pm2/pm2.log`
|
||||
- `/home/pi/.pm2/logs/mm-error-0.log`
|
||||
- `/home/pi/.pm2/logs/mm-out-0.log`
|
||||
|
||||
|
||||
---
|
||||
|
||||
### Conclusion ###
|
||||
There are probably many other and better ways to check and debug. So please add and edit this page or file an issue with info for improving debugging.
|
||||
|
||||
For further reading:
|
||||
|
||||
### Further Reading ###
|
||||
|
||||
- [how-to-troubleshoot](https://forum.magicmirror.builders/topic/86/how-to-troubleshoot)
|
||||
- [how-to-check-your-config](https://forum.magicmirror.builders/topic/5399/how-to-check-your-config-for-errors-for-absolute-beginners)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user