From f1b1997e6ab49ffd27b5d5a1fa65b69f0efa1230 Mon Sep 17 00:00:00 2001 From: Joshua Kriegshauser Date: Sun, 31 Dec 2023 12:45:38 -0800 Subject: [PATCH 1/7] Rename development -> module-development --- .vuepress/config.js | 16 ++++++++-------- .../core-module-file.md | 0 .../documentation.md | 0 .../helper-methods.md | 0 .../introduction.md | 0 {development => module-development}/logger.md | 0 .../node-helper.md | 0 .../notifications.md | 6 +++--- .../weather-provider.md | 0 modules/animate.md | 6 +++--- modules/introduction.md | 2 +- modules/weather.md | 2 +- 12 files changed, 16 insertions(+), 16 deletions(-) rename {development => module-development}/core-module-file.md (100%) rename {development => module-development}/documentation.md (100%) rename {development => module-development}/helper-methods.md (100%) rename {development => module-development}/introduction.md (100%) rename {development => module-development}/logger.md (100%) rename {development => module-development}/node-helper.md (100%) rename {development => module-development}/notifications.md (94%) rename {development => module-development}/weather-provider.md (100%) mode change 100755 => 100644 diff --git a/.vuepress/config.js b/.vuepress/config.js index 74e2bcec..3016a524 100644 --- a/.vuepress/config.js +++ b/.vuepress/config.js @@ -60,14 +60,14 @@ module.exports = { title: "Module Development", collapsable: true, children: [ - "development/introduction.md", - "development/core-module-file.md", - "development/node-helper.md", - "development/helper-methods.md", - "development/logger.md", - "development/notifications.md", - "development/weather-provider.md", - "development/documentation.md", + "module-development/introduction.md", + "module-development/core-module-file.md", + "module-development/node-helper.md", + "module-development/helper-methods.md", + "module-development/logger.md", + "module-development/notifications.md", + "module-development/weather-provider.md", + "module-development/documentation.md", ], }, { diff --git a/development/core-module-file.md b/module-development/core-module-file.md similarity index 100% rename from development/core-module-file.md rename to module-development/core-module-file.md diff --git a/development/documentation.md b/module-development/documentation.md similarity index 100% rename from development/documentation.md rename to module-development/documentation.md diff --git a/development/helper-methods.md b/module-development/helper-methods.md similarity index 100% rename from development/helper-methods.md rename to module-development/helper-methods.md diff --git a/development/introduction.md b/module-development/introduction.md similarity index 100% rename from development/introduction.md rename to module-development/introduction.md diff --git a/development/logger.md b/module-development/logger.md similarity index 100% rename from development/logger.md rename to module-development/logger.md diff --git a/development/node-helper.md b/module-development/node-helper.md similarity index 100% rename from development/node-helper.md rename to module-development/node-helper.md diff --git a/development/notifications.md b/module-development/notifications.md similarity index 94% rename from development/notifications.md rename to module-development/notifications.md index 3627ddf2..1b68f88e 100644 --- a/development/notifications.md +++ b/module-development/notifications.md @@ -8,10 +8,10 @@ The MagicMirror core has the ability to send notifications to modules. Or even better: the modules have the possibility to send notifications to other modules. Additional technical information on the notifications can be found in the -[modules' documentation](/development/introduction.md#general-advice): +[modules' documentation](/module-development/introduction.md#general-advice): -- [notificationReceived](/development/core-module-file.md#subclassable-module-methods) -- [sendNotification](/development/core-module-file.md#module-instance-methods) +- [notificationReceived](/module-development/core-module-file.md#subclassable-module-methods) +- [sendNotification](/module-development/core-module-file.md#module-instance-methods) # System notifications diff --git a/development/weather-provider.md b/module-development/weather-provider.md old mode 100755 new mode 100644 similarity index 100% rename from development/weather-provider.md rename to module-development/weather-provider.md diff --git a/modules/animate.md b/modules/animate.md index a89c1d51..f6b78947 100644 --- a/modules/animate.md +++ b/modules/animate.md @@ -9,9 +9,9 @@ check the [animate.css](https://animate.style/) library to see a preview of the ::: warning Where animation can be used? - [global module configuration](configuration.html#animated) of a module - - [this.hide()](../development/core-module-file.html#this-hide-speed-callback-options) function in core module file - - [this.show()](../development/core-module-file.html#this-show-speed-callback-options) function in core module file - - [this.updateDom()](../development/core-module-file.html#this-updatedom-speed-options) function in core module file + - [this.hide()](../module-development/core-module-file.html#this-hide-speed-callback-options) function in core module file + - [this.show()](../module-development/core-module-file.html#this-show-speed-callback-options) function in core module file + - [this.updateDom()](../module-development/core-module-file.html#this-updatedom-speed-options) function in core module file ::: ## animateIn diff --git a/modules/introduction.md b/modules/introduction.md index d0c131c6..c3da7abf 100644 --- a/modules/introduction.md +++ b/modules/introduction.md @@ -17,7 +17,7 @@ The following modules are installed by default. For more available modules, check out out the wiki page [MagicMirror² 3rd Party Modules](https://github.com/MagicMirrorOrg/MagicMirror/wiki/3rd-party-modules). If you want to build your own modules, check out the -[MagicMirror² Module Development Documentation](/development/introduction.md) +[MagicMirror² Module Development Documentation](/module-development/introduction.md) and don't forget to add it to the [wiki](https://github.com/MagicMirrorOrg/MagicMirror/wiki) and the [forum](https://forum.magicmirror.builders/category/7/showcase)! diff --git a/modules/weather.md b/modules/weather.md index 976b406c..3b733c89 100755 --- a/modules/weather.md +++ b/modules/weather.md @@ -229,4 +229,4 @@ update. ## API Provider Development If you want to add another API provider checkout the -[Guide](/development/weather-provider.md). +[Guide](/module-development/weather-provider.md). From e093521253b44e30126f9cbc9712409726687965 Mon Sep 17 00:00:00 2001 From: Joshua Kriegshauser Date: Sun, 31 Dec 2023 13:42:46 -0800 Subject: [PATCH 2/7] Initial core documentation --- .vuepress/config.js | 9 ++++++ core-development/debugging.md | 47 ++++++++++++++++++++++++++++++ core-development/introduction.md | 39 +++++++++++++++++++++++++ core-development/testing.md | 30 +++++++++++++++++++ module-development/introduction.md | 2 ++ 5 files changed, 127 insertions(+) create mode 100644 core-development/debugging.md create mode 100644 core-development/introduction.md create mode 100644 core-development/testing.md diff --git a/.vuepress/config.js b/.vuepress/config.js index 3016a524..2e107f5a 100644 --- a/.vuepress/config.js +++ b/.vuepress/config.js @@ -70,6 +70,15 @@ module.exports = { "module-development/documentation.md", ], }, + { + title: "Core Development", + collapsable: true, + children: [ + "core-development/introduction.md", + "core-development/testing.md", + "core-development/debugging.md", + ], + }, { title: "About", collapsable: true, diff --git a/core-development/debugging.md b/core-development/debugging.md new file mode 100644 index 00000000..909178d1 --- /dev/null +++ b/core-development/debugging.md @@ -0,0 +1,47 @@ +--- +title: Debugging +--- + +# Core Development Documentation: Debugging + +Tips and tricks for debugging MagicMirror², + +## Breakpoints + +Node.js has support for [built-in breakpoints](https://nodejs.org/api/debugger.html), or [VSCode](https://code.visualstudio.com/) allows for +visual breakpoints and inspecting of objects. + +## Date + +It can be very useful to set the current date to debug calendar issues. In order to do this, override `Date.now` with a lambda in *config/config.js*: + +```js +Date.now = () => new Date('2023-12-31T14:05:32'); +``` + +This will cause every request for the current time to return the specified time, at least for the core and built-in modules. + +**NOTE:** Some modules may use `new Date()` to get the current date/time, though this is not recommended. If this is the case, +the external module will not work correctly for date debugging. + +## Timezone + +The `TZ` environment variable can be used to specify a valid [canonical timezone name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) +from the [tz database](https://en.wikipedia.org/wiki/Tz_database). + +Several tests do this, such as this example in *tests/electron/helpers/global-setup.js*: + +```js +process.env.TZ = "GMT"; +``` + +The *package.json* could also be modified to force a timezone for a given script, such as `start:dev`: + +```json +"start:dev": "TZ=Europe/Madrid ./node_modules/.bin/electron js/electron.js dev" +``` + +Or when running from the command line (Linux example): +```sh +TZ=Europe/Madrid npm run start:dev +``` diff --git a/core-development/introduction.md b/core-development/introduction.md new file mode 100644 index 00000000..ed8bdf5b --- /dev/null +++ b/core-development/introduction.md @@ -0,0 +1,39 @@ +--- +title: Introduction +--- + +# Core Development Documentation + +This documentation describes core MagicMirror² development. + +## General + +MagicMirror² is a community-driven development effort, and [contributions](../about/contributing.md) are +welcome! + +In general, new features and bug fixes should be tracked against an [issue in the MagicMirror repo](https://github.com/MichMich/MagicMirror/issues). +It is always a good idea to search existing issues to see if a problem you're experiencing has already been reported, +or if someone has already suggested a feature you'd like to propose. Creating or finding an issue also starts the +discussion and helps build consensus around your proposed fix or feature. + +The MagicMirror² core is [developed on GitHub](https://github.com/MichMich/MagicMirror/) out of the +*develop* branch. To begin developing MagicMirror² core, please fork the GitHub project and +create a new branch based off of the *develop* branch. + +When your development is ready for review and testing, create a new *Pull Request* targeting the *develop* branch. +The development team and other contributors will be able to review your changes and provide feedback, and +the test system will run automated tests against your changes. Make sure to mention the issue(s) that your Pull +Request solves. + +## Development Environment + +Although Node.js applications are typically platform-independent, many of the scripts created for MagicMirror² are +Linux-based. While Windows/Mac development is possible, you may run into issues. (Improvements here are welcome!) + +You will need to have [Node.js installed](https://nodejs.org/en/download). When doing Linux development, on newer +distributions Node.js is available from package managers. + +Many Node.js or experienced Javascript developers have an environment that works for them. New developers +to Node.js / Electron can download [VSCode for free](https://code.visualstudio.com/download) and use many extensions available for debugging and developing Javascript. + +Also checkout [Building Node.js Apps with VSCode](https://code.visualstudio.com/docs/nodejs/nodejs-tutorial). diff --git a/core-development/testing.md b/core-development/testing.md new file mode 100644 index 00000000..64487f55 --- /dev/null +++ b/core-development/testing.md @@ -0,0 +1,30 @@ +--- +title: Testing +--- + +# Core Development Documentation: Testing + +Unit tests are important to ensure the quality of the project as changes occur. + +All tests are located in the [*tests* top-level directory](https://github.com/MichMich/MagicMirror/tree/master/tests). + +## Hierarchy of Tests + +Below the *tests* directory are other directories that organize the tests: + +* *configs* - Configuration files for tests. +* *e2e* - End-to-end tests that start and run MagicMirror² in various configurations. +* *electron* - Electron application tests. +* *mocks* - Mock-up data for tests. +* *unit* - Unit tests for utilities and smaller portions of MagicMirror². +* *utils* - Testing utilities. + +## Writing a Test + +Almost all pull requests must have test coverage of changes. Usually, it is easier to find an existing test and +extend it to test your new functionality. + +For example, if you were writing a test for a fix in the Calendar module, you might locate *tests/e2e/modules/calendar_spec.js* +and add an additional test there. + +If you have questions about how to write a test, you can also ask in the [MagicMirror forums](https://forum.magicmirror.builders/). diff --git a/module-development/introduction.md b/module-development/introduction.md index 33fccb2b..ca4368f4 100644 --- a/module-development/introduction.md +++ b/module-development/introduction.md @@ -21,6 +21,8 @@ information in your README file.** - What external API's it depends upon, including web links to those - Whether the API/request require a key and the user limitations of those. (Is it free?) +- **Do not use `new Date()` for the current timestamp, instead prefer `Date.now()` + as it can be more [easily overridden for debugging](..\core-development\debugging.md#Date)**. Surely this also help you get better recognition and feedback for your work. From 2aaec0fd098e5b44a3b21d4e248f9d50f3c48592 Mon Sep 17 00:00:00 2001 From: Joshua Kriegshauser Date: Mon, 1 Jan 2024 19:15:08 -0800 Subject: [PATCH 3/7] Corrections --- core-development/debugging.md | 2 +- module-development/introduction.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/core-development/debugging.md b/core-development/debugging.md index 909178d1..20ae1e2b 100644 --- a/core-development/debugging.md +++ b/core-development/debugging.md @@ -16,7 +16,7 @@ visual breakpoints and inspecting of objects. It can be very useful to set the current date to debug calendar issues. In order to do this, override `Date.now` with a lambda in *config/config.js*: ```js -Date.now = () => new Date('2023-12-31T14:05:32'); +Date.now = () => new Date('2023-12-31T14:05:32').valueOf(); ``` This will cause every request for the current time to return the specified time, at least for the core and built-in modules. diff --git a/module-development/introduction.md b/module-development/introduction.md index ca4368f4..32d4700b 100644 --- a/module-development/introduction.md +++ b/module-development/introduction.md @@ -21,7 +21,7 @@ information in your README file.** - What external API's it depends upon, including web links to those - Whether the API/request require a key and the user limitations of those. (Is it free?) -- **Do not use `new Date()` for the current timestamp, instead prefer `Date.now()` +- **Do not use `new Date()` for the current timestamp, instead prefer `new Date(Date.now())` as it can be more [easily overridden for debugging](..\core-development\debugging.md#Date)**. Surely this also help you get better recognition and feedback for your work. From 0ffe867477ecba3e001749498a447039ef13fde8 Mon Sep 17 00:00:00 2001 From: Joshua Kriegshauser Date: Mon, 8 Jan 2024 17:36:14 -0800 Subject: [PATCH 4/7] Fix links --- core-development/introduction.md | 4 ++-- core-development/testing.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/core-development/introduction.md b/core-development/introduction.md index ed8bdf5b..15911224 100644 --- a/core-development/introduction.md +++ b/core-development/introduction.md @@ -11,12 +11,12 @@ This documentation describes core MagicMirror² development. MagicMirror² is a community-driven development effort, and [contributions](../about/contributing.md) are welcome! -In general, new features and bug fixes should be tracked against an [issue in the MagicMirror repo](https://github.com/MichMich/MagicMirror/issues). +In general, new features and bug fixes should be tracked against an [issue in the MagicMirror repo](https://github.com/MagicMirrorOrg/MagicMirror/issues). It is always a good idea to search existing issues to see if a problem you're experiencing has already been reported, or if someone has already suggested a feature you'd like to propose. Creating or finding an issue also starts the discussion and helps build consensus around your proposed fix or feature. -The MagicMirror² core is [developed on GitHub](https://github.com/MichMich/MagicMirror/) out of the +The MagicMirror² core is [developed on GitHub](https://github.com/MagicMirrorOrg/MagicMirror/) out of the *develop* branch. To begin developing MagicMirror² core, please fork the GitHub project and create a new branch based off of the *develop* branch. diff --git a/core-development/testing.md b/core-development/testing.md index 64487f55..46787322 100644 --- a/core-development/testing.md +++ b/core-development/testing.md @@ -6,7 +6,7 @@ title: Testing Unit tests are important to ensure the quality of the project as changes occur. -All tests are located in the [*tests* top-level directory](https://github.com/MichMich/MagicMirror/tree/master/tests). +All tests are located in the [*tests* top-level directory](https://github.com/MagicMirrorOrg/MagicMirror/tree/master/tests). ## Hierarchy of Tests From 0f6e29688b5a6d5f23856c9f24263f7f7188984c Mon Sep 17 00:00:00 2001 From: Joshua Kriegshauser Date: Fri, 2 Feb 2024 14:57:27 -0800 Subject: [PATCH 5/7] Additional debugging info --- core-development/debugging.md | 45 +++++++++++++++++++++++++++++++++-- 1 file changed, 43 insertions(+), 2 deletions(-) diff --git a/core-development/debugging.md b/core-development/debugging.md index 20ae1e2b..57368c69 100644 --- a/core-development/debugging.md +++ b/core-development/debugging.md @@ -6,10 +6,49 @@ title: Debugging Tips and tricks for debugging MagicMirror², +## Make sure dependencies are up-to-date + +When you pull a branch, exceptions can be thrown when running MagicMirror²: +``` +App threw an error during load +Error: Cannot find module 'ansis' +Require stack: +``` + +If this happens, make sure that dependencies have been updated to latest by executing `npm install`. + ## Breakpoints -Node.js has support for [built-in breakpoints](https://nodejs.org/api/debugger.html), or [VSCode](https://code.visualstudio.com/) allows for -visual breakpoints and inspecting of objects. +Node.js has support for [built-in breakpoints](https://nodejs.org/api/debugger.html), or [VSCode](https://code.visualstudio.com/) allows for visual breakpoints and inspecting of objects. + +Developer consoles in browsers and the Electron app (typically CTRL+SHIFT+I to toggle open/close) can be used to set client-side breakpoints, step through scripts and inspect variables. + +## Logging + +While there are no log files produced by the server, info is reported in two different places: +* The console when running from `npm run start` or `npm run server`. + * This is separated into two streams, `console.log()` is output as the `stdout` stream, and + * `console.error()` is output as the `stderr` stream. + * These can be redirected to files when starting the server. `>` will redirect `stdout`, and `2>` will redirect `stderr`. `2>&1` will combine both streams: `npm run start > out.log 2>&1` +* The browser's developer console (typically CTRL+SHIFT+I to toggle open/close) will have output from scripts that run on the browser. + +The [MMM-Logging](https://github.com/shbatm/MMM-Logging) module can help to gather logs and output to a file, but at a performance cost. + +Debug logging is disabled by default, and can be very verbose. It can be enabled in the *config/config.js* file by adding `"DEBUG"` to the `logLevel` key: +```js +let config = { + // ... + logLevel: ["INFO", "LOG", "WARN", "ERROR", "DEBUG"], // Add "DEBUG" for even more logging + // ... +}; +``` + +If you are using `pm2` to launch MagicMirror², you can use the `logs` command to display lines from each of the `stderr` and `stdout` streams, but not interlaced by time: +```sh +pm2 logs --lines=15 # will show 15 lines each from stdout and stderr +``` + +There is no capability to identify the module that is producing console output. However, most browsers have the ability to filter logs by a string. ## Date @@ -21,6 +60,8 @@ Date.now = () => new Date('2023-12-31T14:05:32').valueOf(); This will cause every request for the current time to return the specified time, at least for the core and built-in modules. +Several tests use this to override the current time for the test. See `startApplication()` in *tests/electron/helpers/global-setup.js* as it has a `systemDate` argument to override the system date for tests. + **NOTE:** Some modules may use `new Date()` to get the current date/time, though this is not recommended. If this is the case, the external module will not work correctly for date debugging. From ddad6b56108bb88ef37d538d6d0d9d1e5ee00e10 Mon Sep 17 00:00:00 2001 From: veeck Date: Sat, 3 Feb 2024 22:59:14 +0100 Subject: [PATCH 6/7] Added redirects --- .vuepress/enhanceApp.js | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 .vuepress/enhanceApp.js diff --git a/.vuepress/enhanceApp.js b/.vuepress/enhanceApp.js new file mode 100644 index 00000000..199f3979 --- /dev/null +++ b/.vuepress/enhanceApp.js @@ -0,0 +1,12 @@ +export default ({ router }) => { + router.addRoutes([ + { path: '/development/introduction.html', redirect: '/module-development/introduction.html' }, + { path: '/development/core-module-file.html', redirect: '/module-development/core-module-file.html' }, + { path: '/development/node-helper.html', redirect: '/module-development/node-helper.html' }, + { path: '/development/helper-methods.html', redirect: '/module-development/helper-methods.html' }, + { path: '/development/logger.html', redirect: '/module-development/logger.html' }, + { path: '/development/notifications.html', redirect: '/module-development/notifications.html' }, + { path: '/development/weather-provider.html', redirect: '/module-development/weather-provider.html' }, + { path: '/development/documentation.html', redirect: '/module-development/documentation.html' } + ]) +} From 7044b63b2a1e026c963de1c1d8f6539a5e3768e9 Mon Sep 17 00:00:00 2001 From: veeck Date: Sat, 3 Feb 2024 23:02:10 +0100 Subject: [PATCH 7/7] Lint new pages --- core-development/debugging.md | 79 ++++++++++++++++++++++---------- core-development/introduction.md | 49 ++++++++++++-------- core-development/testing.md | 30 ++++++------ 3 files changed, 100 insertions(+), 58 deletions(-) diff --git a/core-development/debugging.md b/core-development/debugging.md index 57368c69..fbe92468 100644 --- a/core-development/debugging.md +++ b/core-development/debugging.md @@ -9,80 +9,109 @@ Tips and tricks for debugging MagicMirror², ## Make sure dependencies are up-to-date When you pull a branch, exceptions can be thrown when running MagicMirror²: + ``` App threw an error during load Error: Cannot find module 'ansis' Require stack: ``` -If this happens, make sure that dependencies have been updated to latest by executing `npm install`. +If this happens, make sure that dependencies have been updated to latest by +executing `npm install`. ## Breakpoints -Node.js has support for [built-in breakpoints](https://nodejs.org/api/debugger.html), or [VSCode](https://code.visualstudio.com/) allows for visual breakpoints and inspecting of objects. +Node.js has support for +[built-in breakpoints](https://nodejs.org/api/debugger.html), or +[VSCode](https://code.visualstudio.com/) allows for visual breakpoints and +inspecting of objects. -Developer consoles in browsers and the Electron app (typically CTRL+SHIFT+I to toggle open/close) can be used to set client-side breakpoints, step through scripts and inspect variables. +Developer consoles in browsers and the Electron app (typically CTRL+SHIFT+I to +toggle open/close) can be used to set client-side breakpoints, step through +scripts and inspect variables. ## Logging -While there are no log files produced by the server, info is reported in two different places: -* The console when running from `npm run start` or `npm run server`. - * This is separated into two streams, `console.log()` is output as the `stdout` stream, and - * `console.error()` is output as the `stderr` stream. - * These can be redirected to files when starting the server. `>` will redirect `stdout`, and `2>` will redirect `stderr`. `2>&1` will combine both streams: `npm run start > out.log 2>&1` -* The browser's developer console (typically CTRL+SHIFT+I to toggle open/close) will have output from scripts that run on the browser. +While there are no log files produced by the server, info is reported in two +different places: + +- The console when running from `npm run start` or `npm run server`. + - This is separated into two streams, `console.log()` is output as the + `stdout` stream, and + - `console.error()` is output as the `stderr` stream. + - These can be redirected to files when starting the server. `>` will redirect + `stdout`, and `2>` will redirect `stderr`. `2>&1` will combine both streams: + `npm run start > out.log 2>&1` +- The browser's developer console (typically CTRL+SHIFT+I to toggle open/close) + will have output from scripts that run on the browser. + +The [MMM-Logging](https://github.com/shbatm/MMM-Logging) module can help to +gather logs and output to a file, but at a performance cost. -The [MMM-Logging](https://github.com/shbatm/MMM-Logging) module can help to gather logs and output to a file, but at a performance cost. +Debug logging is disabled by default, and can be very verbose. It can be enabled +in the _config/config.js_ file by adding `"DEBUG"` to the `logLevel` key: -Debug logging is disabled by default, and can be very verbose. It can be enabled in the *config/config.js* file by adding `"DEBUG"` to the `logLevel` key: ```js let config = { - // ... - logLevel: ["INFO", "LOG", "WARN", "ERROR", "DEBUG"], // Add "DEBUG" for even more logging - // ... + // ... + logLevel: ["INFO", "LOG", "WARN", "ERROR", "DEBUG"], // Add "DEBUG" for even more logging + // ... }; ``` -If you are using `pm2` to launch MagicMirror², you can use the `logs` command to display lines from each of the `stderr` and `stdout` streams, but not interlaced by time: +If you are using `pm2` to launch MagicMirror², you can use the `logs` command to +display lines from each of the `stderr` and `stdout` streams, but not interlaced +by time: + ```sh pm2 logs --lines=15 # will show 15 lines each from stdout and stderr ``` -There is no capability to identify the module that is producing console output. However, most browsers have the ability to filter logs by a string. +There is no capability to identify the module that is producing console output. +However, most browsers have the ability to filter logs by a string. ## Date -It can be very useful to set the current date to debug calendar issues. In order to do this, override `Date.now` with a lambda in *config/config.js*: +It can be very useful to set the current date to debug calendar issues. In order +to do this, override `Date.now` with a lambda in _config/config.js_: ```js -Date.now = () => new Date('2023-12-31T14:05:32').valueOf(); +Date.now = () => new Date("2023-12-31T14:05:32").valueOf(); ``` -This will cause every request for the current time to return the specified time, at least for the core and built-in modules. +This will cause every request for the current time to return the specified time, +at least for the core and built-in modules. -Several tests use this to override the current time for the test. See `startApplication()` in *tests/electron/helpers/global-setup.js* as it has a `systemDate` argument to override the system date for tests. +Several tests use this to override the current time for the test. See +`startApplication()` in _tests/electron/helpers/global-setup.js_ as it has a +`systemDate` argument to override the system date for tests. -**NOTE:** Some modules may use `new Date()` to get the current date/time, though this is not recommended. If this is the case, -the external module will not work correctly for date debugging. +**NOTE:** Some modules may use `new Date()` to get the current date/time, though +this is not recommended. If this is the case, the external module will not work +correctly for date debugging. ## Timezone -The `TZ` environment variable can be used to specify a valid [canonical timezone name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) +The `TZ` environment variable can be used to specify a valid +[canonical timezone name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) from the [tz database](https://en.wikipedia.org/wiki/Tz_database). -Several tests do this, such as this example in *tests/electron/helpers/global-setup.js*: +Several tests do this, such as this example in +_tests/electron/helpers/global-setup.js_: ```js process.env.TZ = "GMT"; ``` -The *package.json* could also be modified to force a timezone for a given script, such as `start:dev`: +The _package.json_ could also be modified to force a timezone for a given +script, such as `start:dev`: ```json "start:dev": "TZ=Europe/Madrid ./node_modules/.bin/electron js/electron.js dev" ``` Or when running from the command line (Linux example): + ```sh TZ=Europe/Madrid npm run start:dev ``` diff --git a/core-development/introduction.md b/core-development/introduction.md index 15911224..2aa82d41 100644 --- a/core-development/introduction.md +++ b/core-development/introduction.md @@ -8,32 +8,41 @@ This documentation describes core MagicMirror² development. ## General -MagicMirror² is a community-driven development effort, and [contributions](../about/contributing.md) are -welcome! - -In general, new features and bug fixes should be tracked against an [issue in the MagicMirror repo](https://github.com/MagicMirrorOrg/MagicMirror/issues). -It is always a good idea to search existing issues to see if a problem you're experiencing has already been reported, -or if someone has already suggested a feature you'd like to propose. Creating or finding an issue also starts the +MagicMirror² is a community-driven development effort, and +[contributions](../about/contributing.md) are welcome! + +In general, new features and bug fixes should be tracked against an +[issue in the MagicMirror repo](https://github.com/MagicMirrorOrg/MagicMirror/issues). +It is always a good idea to search existing issues to see if a problem you're +experiencing has already been reported, or if someone has already suggested a +feature you'd like to propose. Creating or finding an issue also starts the discussion and helps build consensus around your proposed fix or feature. -The MagicMirror² core is [developed on GitHub](https://github.com/MagicMirrorOrg/MagicMirror/) out of the -*develop* branch. To begin developing MagicMirror² core, please fork the GitHub project and -create a new branch based off of the *develop* branch. +The MagicMirror² core is +[developed on GitHub](https://github.com/MagicMirrorOrg/MagicMirror/) out of the +_develop_ branch. To begin developing MagicMirror² core, please fork the GitHub +project and create a new branch based off of the _develop_ branch. -When your development is ready for review and testing, create a new *Pull Request* targeting the *develop* branch. -The development team and other contributors will be able to review your changes and provide feedback, and -the test system will run automated tests against your changes. Make sure to mention the issue(s) that your Pull -Request solves. +When your development is ready for review and testing, create a new _Pull +Request_ targeting the _develop_ branch. The development team and other +contributors will be able to review your changes and provide feedback, and the +test system will run automated tests against your changes. Make sure to mention +the issue(s) that your Pull Request solves. ## Development Environment -Although Node.js applications are typically platform-independent, many of the scripts created for MagicMirror² are -Linux-based. While Windows/Mac development is possible, you may run into issues. (Improvements here are welcome!) +Although Node.js applications are typically platform-independent, many of the +scripts created for MagicMirror² are Linux-based. While Windows/Mac development +is possible, you may run into issues. (Improvements here are welcome!) -You will need to have [Node.js installed](https://nodejs.org/en/download). When doing Linux development, on newer -distributions Node.js is available from package managers. +You will need to have [Node.js installed](https://nodejs.org/en/download). When +doing Linux development, on newer distributions Node.js is available from +package managers. -Many Node.js or experienced Javascript developers have an environment that works for them. New developers -to Node.js / Electron can download [VSCode for free](https://code.visualstudio.com/download) and use many extensions available for debugging and developing Javascript. +Many Node.js or experienced Javascript developers have an environment that works +for them. New developers to Node.js / Electron can download +[VSCode for free](https://code.visualstudio.com/download) and use many +extensions available for debugging and developing Javascript. -Also checkout [Building Node.js Apps with VSCode](https://code.visualstudio.com/docs/nodejs/nodejs-tutorial). +Also checkout +[Building Node.js Apps with VSCode](https://code.visualstudio.com/docs/nodejs/nodejs-tutorial). diff --git a/core-development/testing.md b/core-development/testing.md index 46787322..65bf30d8 100644 --- a/core-development/testing.md +++ b/core-development/testing.md @@ -6,25 +6,29 @@ title: Testing Unit tests are important to ensure the quality of the project as changes occur. -All tests are located in the [*tests* top-level directory](https://github.com/MagicMirrorOrg/MagicMirror/tree/master/tests). +All tests are located in the +[_tests_ top-level directory](https://github.com/MagicMirrorOrg/MagicMirror/tree/master/tests). ## Hierarchy of Tests -Below the *tests* directory are other directories that organize the tests: +Below the _tests_ directory are other directories that organize the tests: -* *configs* - Configuration files for tests. -* *e2e* - End-to-end tests that start and run MagicMirror² in various configurations. -* *electron* - Electron application tests. -* *mocks* - Mock-up data for tests. -* *unit* - Unit tests for utilities and smaller portions of MagicMirror². -* *utils* - Testing utilities. +- _configs_ - Configuration files for tests. +- _e2e_ - End-to-end tests that start and run MagicMirror² in various + configurations. +- _electron_ - Electron application tests. +- _mocks_ - Mock-up data for tests. +- _unit_ - Unit tests for utilities and smaller portions of MagicMirror². +- _utils_ - Testing utilities. ## Writing a Test -Almost all pull requests must have test coverage of changes. Usually, it is easier to find an existing test and -extend it to test your new functionality. +Almost all pull requests must have test coverage of changes. Usually, it is +easier to find an existing test and extend it to test your new functionality. -For example, if you were writing a test for a fix in the Calendar module, you might locate *tests/e2e/modules/calendar_spec.js* -and add an additional test there. +For example, if you were writing a test for a fix in the Calendar module, you +might locate _tests/e2e/modules/calendar_spec.js_ and add an additional test +there. -If you have questions about how to write a test, you can also ask in the [MagicMirror forums](https://forum.magicmirror.builders/). +If you have questions about how to write a test, you can also ask in the +[MagicMirror forums](https://forum.magicmirror.builders/).