node-module-with-unittests-template
Advanced tools
Node-Module-With-Unittests-Template: template for a generic node module with unittests and coverage reports
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.
Type:
git clone https://github.com/byuksel/node-module-with-unittests-template.git
This will clone the repo. Change to node-module-with-unittests, and type:
npm install
This will install all the necessary dependencies for this scaffolding.
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 (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.
In this section, we describe what each file does in this template and how you can modify them to your needs.
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.
│ └── 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.
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
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.
Configuration file for JSCS coding style checks. We use a modified version of Google JS coding style and full JSDoc3 checks.
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.
The generator puts two links to your README.md.template file, one linking an image to a hypothetical Travis-CI build task under your own github name. The generator does NOT create this build task. You can sign up with Travis-CI to get this working. You can read more on their website.
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 configuration file. You can modify this file to change the behaviour of JSDoc which is used to create documentation from the source code.
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.
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.
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.
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.
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 tasks are closely coupled. Please be careful when you change them.
Browserifies the library so that your library can run in a browser.
Deletes the minimized and unminimized final output files.
Deletes the docs.
Deletes the output of tests and browserified tests.
Starts a basic web server.
Runs Flow static type checker.
Runs the code through jscs for coding style checks. This uses a modified version of Google coding style.
Creates documentation from src files using jsdoc.
Runs the code through jshint.
Creates an html version of the README.md file called README.md.html.
Runs the browserified tests thru PhantomJS.
Runs the unittests.
Replaces text patterns in (template) files.
Replaces text patterns in the index.html.template.
Replaces text patterns in README.md.template.
Minimizes the output of browserified library/module.
Gruntfile.js comes with a whole set of custom tasks.
Runs 'clean:tests', 'jshint', 'jscs', 'flow', 'browserify', 'replace:browserified_tests_file', 'connect:server', 'mocha_phantomjs' respectively.
Runs 'clean:dist', 'browserify', 'uglify' respectively.
Runs 'clean:docs', 'replace:dist', 'markdown', 'jsdoc' respectively.
Runs 'clean:tests', 'jshint', 'jscs', 'flow', 'mochaTest' respectively.
Runs 'localtest', 'browsertest' respectively.
When you run the Grunt tasks, this scaffolding generates a whole bunch of files. They are explained below.
Generated by 'jsdoc' task. All documentation in the src files should follow jsdoc format so that this task can produce all the documentation.
Generated by browserify and uglify and will have your final minimized and unminimized library.
Dynamically generated README.md file from README.md.template.
Generated from README.md file.
Test results from the browser run of the browserified unittests.
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 results from the node run of the unittests.
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:
Apache 2.0 License - © 2015 Baris Yuksel
For bug reports, feature requests and general questions, please feel free to email baris@onehundredyearsofcode.com.
FAQs
Node-Module-With-Unittests-Template: template for a generic node module with unittests and coverage reports
The npm package node-module-with-unittests-template receives a total of 2 weekly downloads. As such, node-module-with-unittests-template popularity was classified as not popular.
We found that node-module-with-unittests-template demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.
Security News
Research
Socket researchers found a malicious Maven package impersonating the legitimate ‘XZ for Java’ library, introducing a backdoor for remote code execution.