generator-node-module-with-unittests

Node Module With Unittests Generator

Yeoman generator for a generic node module with unittests - lets you quickly set up a project with unittests, coverage reports, browserified and minimized versions of the module.

Quick Installation

Install yo and generator-node-module-with-unittests:

npm install -g yo generator-node-module-with-unittests

Usage

Make a new directory, and cd into it:

mkdir my-new-project && cd $_

Run yo node-module-with-unittests:

yo node-module-with-unittests

Variables the generator uses

• generatorModuleName: Module Name. The generator will try to generate a proper name with dashes from this name.
• generatorModuleClass: (Generated but can be changed) Module class name derived from module name. It is the main exported class from your main file.
• generatorModuleNameWithDashes: (Generated but can be changed) Derived name from module name, used as your module's name in package.json, and when creating your entry javascript file under src directory.
• generatorModuleDescription: Module Description. Goes into package.json of your project.
• generatorUserEmail: Your email. Goes into package.json file and all the copyright notices in your source files.
• generatorUserName: Your name. Goes into package.json file and all the copyright notices in your source files.
• generatorUserGithubName: Your github account name. Goes into package.json file.
• generatorModuleWebsite: The website for your module. You may want to register this thru a domain registrar.

Questions that the generator asks

• 'What is your module's name ?': sets 'generatorModuleName'
• 'What is your module's dasherized name ? Will use this as the main module name': sets 'generatorModuleNameWithDashes'
• 'What is your module's main exported class ?': sets 'generatorModuleClass'.
• 'What is your module's description ?': sets 'generatorModuleDescription'.
• 'What is your email ?': sets 'generatorUserEmail'.
• 'What is your name ?': sets 'generatorUserName'.
• 'What is your github username ?': sets 'generatorUserGithubName'.
• 'What is your module's own website ?': sets 'generatorModuleWebsite'.

In-depth Explanation

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 Start

Type:

grunt

This should build your project into dist/ directory. You can type grunt watch and this will continously build y
our sources into dist/ directory. You will also get tests running both under node environment and browsers, your documentation, and your full fledged README.md and README.md.html files.

Replace ./src/dummy.js with your own module code and ./test/unittests/ with your own unittest.

README.md

README.md is recreated and 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.

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:

├── .editorconfig                                     # EditorConfig file for unifying settings across multiple editors.
├── .flowconfig                                       # Config file for flow static type checker.
├── .jscsrc                                           # Config file for jscs coding style checker.
├── .travis.yml                                       # Config file for travis-ci continous integration testing infrastructure.
├── 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.
│   └── < pkg name>.js                                # Entry file to your module. Add your own code here.
└── 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.
│   │   └── <pkg name>-test.js                        # Unittest for your entry file.

./.editorconfig

From their website, "EditorConfig is a file format and collection of text editor plugins for maintaining consistent coding styles between different editors and IDEs." This file has a bunch of settings that various editors can read and adjust their behaviour accordingly. You can read more about it on their website

./.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.

./.jscsrc

Configuration file for JSCS coding style checks. We use a modified version of Google JS coding style and full JSDoc3 checks.

./.travis.yml

Wikipedia says "Travis CI is a FOSS, hosted, distributed continuous integration service used to build and test projects hosted at GitHub". I strongly recommend that you connect your node module to Travis-CI through Github to run continuous builds and integration tests. You can read more 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 file of your library/module. You can replace it with your own code.

./src/<%= generatorModuleNameWithDashes %>.js

This file is an entry point of your library/module. You can replace it with your own code. 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 '<%= generatorModuleNameWithDashes %>' in package.json (refer to "name" field in package.json"), your entry point file should be named <%= generatorModuleNameWithDashes %>.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/unittests/<%= generatorModuleNameWithDashes %>-test.js

This unittest file tests your ./src/<%= generatorModuleNameWithDashes %>.js file.

./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.

jscs

Runs the code through jscs for coding style checks. This uses a modified version of Google coding style.

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', 'jscs', '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', 'jscs', '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]