node-module-with-unittests-template

Node Module with Unittests Template

This repository provides scaffolding to promptly bootstrap writing your own node module with unittests. The unittests are run both within node environment and on the browser (which can help you determine if your code works as expected on different browsers). The unittests get full coverage reports.

You also get a fully automated document creation from source code, automatic updating of your final module/library name and version in README.md, and an html version of your README.md file.

Quick Installation

After cloning this scaffolding from github, just type npm install and this scaffolding will install all the necessary dependencies.

Quick Start

Replace ./src/dummy.js with your own module code and ./test/unittests/ with your own unittest. Type grunt and you will get tests running both under node environment and browsers, your documentation, and your full fledged README.md and README.md.html files.

README.md vs. README.md.copy

README.md (this very file) is overwritten when you run "replace:dist" step of your Grunfile.js. "replace:dist" will take your README.md.template, and replace certain varibles and produce your final README.md file which overwrites this file. Thus, there is a copy of this file at README.md.copy. This copy will not be deleted unless you delete it yourself.

Scaffolding Explained

In this section, we describe what each file does in this template and how you can modify them to your needs.

Directory Structure

Once everything is installed, you will see a project structure like below:

├── .flowconfig                                       # Config file for flow static type checker.
├── Gruntfile.js                                      # File of magic. All grunt tasks are in here.
├── README.md                                         # This very file. Gets overwritten by Grunt.
├── README.md.copy                                    # Copy of this file. Does not get overwritten.
├── README.md.html                                    # HTML version of README.md. Generated dynamically from README.md.
├── README.md.template                                # Template file for generating README.md dynamically.
├── dist                                              # Distribution files. Gets generated by Grunt.
│   ├── <pkg name>.<pkg version>.standalone.js        # Browserify output of your module.
│   └── <pkg name>.<pkg version>.standalone.min.js    # Minimized version of the browserify output.
├── docs                                              # Documentation directory. Gets generated dynamically by Grunt.
├── jsdoc.conf                                        # JSDoc configuration file. JSDoc is used for documentation generation.
├── package.json                                      # NPM package.json file.
├── src                                               # Source files for your module.
│   ├── dummy.js                                      # Dummy js. Provided as an example js file.
│   └── node-module-with-unittests-template.js        # Entry file to your module. You should replace this with <pkg name>.js.
└── test                                              # Directory for test related files.
│   ├── index.html.template                           # Template index HTML file for browser tests. No need to modify this.
│   ├── output                                        # Directory for unittest outputs.
│   │   ├── browserified_tests.js                     # Your unittests bundled into one mega file to be tested on the browser.
│   │   ├── coveragereport.html                       # Coverage report for all of your unittests.
│   │   ├── index.html                                # Dynamically generated file from index.html.template. Don't modify.
│   │   └── output.txt                                # Output of your unittest run from node.
│   └── unittests                                     # Unittests directory. Add your unittests here.
│   │   └── dummy-test.js                             # Dummy js unittest. Provided as an example.

./.flowconfig

Configuration file for flow type checker. Flow is a static type checker which is helpful in catching null dereferences and unintentional type conversions. You can read more about it on their website.

./Gruntfile.js

This is where all the magic lives. Gruntfile.js describes all the tasks, and how they interact with each other. It can run your tests, create browser version of your tests, run them in the browser, create their coverage reports, create documentation, create your dynamically generated README.md, and README.md.html files and create your final browserified library along with its minimized version.

./jsdoc.conf

JSDoc configuration file. You can modify this file to change the behaviour of JSDoc which is used to create documentation from the source code.

./package.json

NPM package.json file. You describe your module in this file. The values for 'name' and 'version' fromthis file are later used in producing README.md file.

./README.md.template

This is "almost" your README.md file except you can replace text patterns dynamically during Grunt run. In Grunt.js file, there is a step/task called "replace:dist" which will take this README.md.template, replace text patterns you identify in the task with their produced values, and produce the README.md file. This lets you for example dynamically add the version number to README.md file.

./src/dummy.js

This file is an example for the entry point of your library/module. You can replace it with your own module js file(s). The Grunt.js file assumes that the entry point file to your library will be the same as the name of your module. So, if your library is called 'dummy' in package.json, your entry point file should be named dummy.js.

./test/unittests/dummy-test.js

You can add multiple test files to ./test/unittests/ directory. You probably want to have as many test files under this directory as your source js file under ./src directory. In other words, you want to have one to one mapping to your src files. I suggest for good housekeeping, every single file here should test one and only one js file under ./src.

./test/index.html.template

This file is processed by "replace:browserified_tests_file" task to produce an index.html file. "replace:browserified_tests_file" task writes the location of your browserified unittests into the index.html.template to produce the final index.html file. This 'index.html' file is then used by "mocha_phantomjs:all" task to run the browserified unittests.

./Gruntfile.js and Tasks

Gruntfile.js tasks are closely coupled. Please be careful when you change them.

browserify

Browserifies the library so that your library can run in a browser.

clean

• clean:dist

Deletes the minimized and unminimized final output files.

• clean: docs

Deletes the docs.

• clean:tests

Deletes the output of tests and browserified tests.

connect

Starts a basic web server.

flow

Runs Flow static type checker.

jsdoc

Creates documentation from src files using jsdoc.

jshint

Runs the code through jshint.

markdown

Creates an html version of the README.md file called README.md.html.

mocha_phantomjs

Runs the browserified tests thru PhantomJS.

mochaTest

Runs the unittests.

replace

Replaces text patterns in (template) files.

• replace:browserified_test_file

Replaces text patterns in the index.html.template.

• replace:dist

Replaces text patterns in README.md.template.

uglify

Minimizes the output of browserified library/module.

Custom Tasks

Gruntfile.js comes with a whole set of custom tasks.

browsertest

Runs 'clean:tests', 'jshint', 'flow', 'browserify', 'replace:browserified_tests_file', 'connect:server', 'mocha_phantomjs' respectively.

dist

Runs 'clean:dist', 'browserify', 'uglify' respectively.

docs

Runs 'clean:docs', 'replace:dist', 'markdown', 'jsdoc' respectively.

localtest

Runs 'clean:tests', 'jshint', 'flow', 'mochaTest' respectively.

test

Runs 'localtest', 'browsertest' respectively.

Generated Files and Directories

When you run the Grunt tasks, this scaffolding generates a whole bunch of files. They are explained below.

./docs/*

Generated by 'jsdoc' task. All documentation in the src files should follow jsdoc format so that this task can produce all the documentation.

./dist/*

Generated by browserify and uglify and will have your final minimized and unminimized library.

./README.md

Dynamically generated README.md file from README.md.template.

./README.md.html

Generated from README.md file.

./test/output/browser_tests_results.txt

Test results from the browser run of the browserified unittests.

./test/output/coveragereport.html

This is an important file. It tells you how much your unittests cover your code. I recommend you to have full coverage at >98% as it will help you to catch bugs early on.

./test/output/output.txt

Test results from the node run of the unittests.

'projectparams' section of Gruntfile.js

This section has all the parameters necessary to run the scaffolding correctly. You can change these parameters according to your project's specifics.

Description of the variables in projectparams:

• banner_for_production: The first line for both the browserified output file and the minimized version.
• docs_dir: (Generated) Directory for the docs.
• dist_dir: (Generated) Directory for the distribution files.
• minimized_output_file: Minimized browserified output file of your library.
• output_file: Final browserified output file of your library.
• readme_md_html_file: (Generated) README.md.html file name.
• readme_md_template: README.md.template file name.
• readme_md_text_file: (Generated) README.md file name.
• src_dir: Directory where source files are located.
• test_dir: The root test directory. 'index.html.template' is assumed to be here.
• unittests_also_to_be_browsertested: List of unittests also to be run in the browser.
• unittests_browsertest_index_html: 'index.html' file for browser unittests.
• unittests_browsertest_index_html_template: 'index.html.template' file name.
• unittests_browsertest_results_file: (Generated) Browser unittest run reports.
• unittests_coverage_report_file: (Generated) Coverage reports for unittests.
• unittests_dir: Directory where the unittests are.
• unittests_output_dir: (Generated) Unittest output reports will be written here.
• unittests_text_output_file: (Generated) Node unittest run reports.

License

Apache 2.0 License - © 2015 Baris Yuksel

Bugs, Requests and Support

For bug reports, feature requests and general questions, please feel free to email [e-mail].