Setting up nodejs to unit test dijit widgets is very challenging and not straight forward and there are no documentations on how to achieve this.
This project aims to give guidances on how to accomplish this task and hit the ground running!
Clone this git repository and invoke the following command at the root folder of the project
npm install
Since this README is quite long, I listed out commands that you can use to inspect how to run and inspect Test and Source under Tests in the nodejs and browser environment.
See How-tos section for more details
See more details in How to setup a nodejs test with mocha
$ npm test test/nodejs/runner.js
See more details in How to setup a browser test with mocha
$ npm start
Then navigate to the test page http://127.0.0.1:8080/test/browser/runner.html
Source for the Widget under test can be found in ./src/js/widgets/CustomWidget.js
See more details in How to setup nodejs to render a dijit widget
$ node src/showcase_in_jsdom.js
$ npm start
Then navigate to the test page http://127.0.0.1:8080/src/showcase.html
Dojo/dijit was a popular JavaScript framework in the past and there are many legacy apps that are still running with this framework. Imagine that one fine day, for whatever reason,
"You got a task to enhance legacy apps writen with dojo and dijit frameworks and need to add unit tests and run them in nodejs"
Modern testing frameworks like Jest, Mocha, and Jasmine provide a lot of attractive features to help authoring JavaScript unit tests for your apps and run them in the nodejs environment.
However, most documentations and examples to run tests in those frameworks in nodejs assume that your apps are developed with modern JavaScript frameworks and standards. Setting up tests to run in the nodejs environment is not a trivial task especially when there are no documentations and community support.
I spent a lot of time to figure out how to
- Create a dijit widget in JSDom in the nodejs environment (Thanks to this old article "Server Side Dijit" written by James Thamas on Jan 15th, 2013 and the dojo documentation "Dojo and Node.js" - Those are the only two helpful articles that I found online in July 2019 though)
- Since dojo uses AMD to support packaging and modules but nodejs uses CommonJS for its module system, we need to find a way to configure test environments such as setting up the global window object and other global variables for other required libraries such as chai (assertion library) and jQuery (for UI interaction and dom traversal)
- Reuse the same test implementation and run it in the "browser" and "nodejs" environment
and decided to put together this project in GitHub to help folks who encounter the same challenges so they can hit the ground running :)
This instructions assumes you have some background knowledge of
- nodejs
- AMD system
- dojo/dijit
- mocha
RESOURCES:
- In order to load an AMD module under NodeJS, we need a module loader. The require() that comes default with Node.js can only load CommonJS modules. The Dojo AMD loader (as well as other loaders, like RequireJS) can be "bootstrapped" to allow you to have an "AMD environment"
- Specify modules to bootstrap (aka load it in the dojo environment) and specify them in the deps key in dojoConfig
- Note that since "dojo/domReady" does not work as intended in the nodejs environment (it expects a global window object), we need to patch it (See the #Patch tag in ./lib_patches/dojo/domReady.js) and use this patch by specifying it in the aliases key in dojoConfig
- In the bootstrapped module, create a window object using JSDOM and assign it to the global variable window
- Finally, create a dijit widget in the newly created dom! (See ./src/nodejs/showcase.js)
Execute the command below to see how the dom looks like:
$ node src/showcase_in_jsdom.js
Below is a list of source that will be tested:
- CustomWidget (requires dom in some cases) ./src/js/widgets/CustomWidget.js
- mathops (does not require dom) ./src/js/utils/mathops.js
- Since mocha apis will be available globally when running tests, we don't need to import it (See ./test/twidgets_CustomWidget.js and ./test/tutils_mathops.js)
- Note that we will use the same test script when running test in nodejs and browser
- However, to use other libraries in our tests, i.e. chai (for assertions), jQuery (for dom traversal), we need to make them available globally by importing using
"dojo/node!<package_name>"and setting them in a global variable (See ./test/utils/setup_env.js) - Similar to the previous example, we will need to setup the window object before running test. I put together all required setups in (See ./test/utils/setup_env.js) and import before running the test in ./test/twidgets_CustomWidget.js
- Finally, bootstrap the test file to run it in the AMD environment (See ./test/nodejs/runner.js)
Execute the command below to see how the dom looks like:
$ npm test test/nodejs/runner.js
Note that package.json is configured to run mocha when running npm test
In this case, we will use the same test implement in ./test/twidgets_CustomWidget.js and ./test/tutils_mathops.js but run them in a browser instead.
-
To run mocha test with dojo/dijit in a browser, we need to load required libraries and configure the test/dojo environments+test files. See ./src/browser/runner.html
-
Start a host server to run the test
- Start a host server to run the test file by executing the command below
$ npm start
Note that package.json is configured to run http-server . when running npm start
- Open a browser, Navigate to the test location (The url will look similar to the following):
http://127.0.0.1:8080/test/browser/runner.html
This project is MIT licensed.