diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..6a6eee6 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +node_modules +docs +test/coverage.html diff --git a/Gruntfile.js b/Gruntfile.js new file mode 100644 index 0000000..994763e --- /dev/null +++ b/Gruntfile.js @@ -0,0 +1,95 @@ +var path = require('path'); + +module.exports = function(grunt) { + var TEST_RUNNER = path.join(process.cwd(), 'test', 'test_runner'); + var ALL_TESTS = 'test/**/*_test.js'; + + // NPM tasks, alphabetical + grunt.loadNpmTasks('grunt-contrib-clean'); + grunt.loadNpmTasks('grunt-contrib-watch'); + grunt.loadNpmTasks('grunt-docco'); + grunt.loadNpmTasks('grunt-mocha-test'); + + grunt.initConfig({ + // Clean + clean: { + docs: ['docs'], + coverage: ['test/coverage.html'] + }, + + // Documentation + docco: { + main: { + src: ['lib/**/*.js'], + options: { + output: 'docs/' + } + } + }, + + // Server-side mocha tests + mochaTest: { + // Runs all tests + test: { + options: { + require: TEST_RUNNER, + reporter: 'spec', + ui: 'bdd', + timeout: 200, + recursive: true, + clearRequireCache: true + }, + src: [ALL_TESTS] + }, + + // Instruments code for reporting test coverage + instrument: { + options: { + require: TEST_RUNNER, + reporter: 'spec', + ui: 'bdd', + timeout: 200, + recursive: true, + }, + src: [ALL_TESTS] + }, + + // Reports test coverage + coverage: { + options: { + require: TEST_RUNNER, + reporter: 'html-cov', + ui: 'bdd', + timeout: 200, + recursive: true, + quiet: true, + captureFile: 'test/coverage.html' + }, + src: [ALL_TESTS] + } + }, + + // Watches filesystem for changes to run tasks automatically + watch: { + test: { + options: { + spawn: false + }, + files: [ + 'lib/**/*.js', + 'test/**/*.js' + ], + tasks: ['mochaTest:test'] + } + } + }); + + // Runs all unit tests + grunt.registerTask('test', 'All unit tests', ['mochaTest:test']); + + // Generates test coverage report + grunt.registerTask('coverage', 'Unit test code coverage', ['clean:coverage', 'mochaTest:instrument', 'mochaTest:coverage']); + + // Generates documentation + grunt.registerTask('docs', 'Generate documentation', ['clean:docs', 'docco:main']); +}; diff --git a/README.md b/README.md new file mode 100644 index 0000000..406ba7b --- /dev/null +++ b/README.md @@ -0,0 +1,70 @@ +Tagged NPM Seed +=============== + +A blueprint for creating NPM packages. + +## Files and Directory Structure + +The following describes the various files in this repo and the directory structure. + +**Note:** Files and directories prefixed by `*` are auto-generated and excluded from the +repository via `.gitignore`. + + . + ├── Gruntfile.js # grunt task configuration + ├── README.md # this file + ├── *docs # autogenerated documentation + │   └── *index.html # each JS file in `./lib` has a corresponding HTML file for documentation + ├── lib # all code for this library will be placed here + │   └── index.js # main entry point for your npm package + ├── *node_modules # all dependencies will be installed here by npm + ├── package.json # description of this package for npm, including dependency lists + └── test # unit test configuration, reports, and specs + ├── *coverage.html # code coverage report + ├── lib # specs go here, preferably with a 1:1 mapping to code in `./lib` + │   └── index_test.js # example spec for `./lib/index.js` + ├── mocha.opts # runtime options for mocha + └── test_runner.js # configures mocha environment (e.g. chai, sinon, etc.) + +## What's Included? + +### Grunt + +Grunt is a JavaScript task runner to automate common actions. The Tagged NPM Package Seed +supports the following built-in grunt tasks: + +**test** + +Runs all unit tests through mocha. + + $ grunt test + +**coverage** + +Runs all unit tests and generates a code coverage report in `./test/coverage.html` + + $ grunt coverage + +**watch** + +Automatically runs mocha tests each time a file changes in `./lib` or `./test`. + + $ grunt watch + +**docs** + +Generates documentation for all JS files within `./lib` using docco. Documentation is +written to `./docs`. + + $ grunt docs + +**clean** + +Deletes all auto-generated files, including `./docs` and `./test/coverage.html` + +### Mocha, Sinon, Chai, Blanket + +The ultimate TDD environment for node. Place your specs in `./test/lib`, and run `grunt test` +to run them. + +See `./test/lib/index_test.js` for examples. diff --git a/lib/index.js b/lib/index.js new file mode 100644 index 0000000..b12f3f2 --- /dev/null +++ b/lib/index.js @@ -0,0 +1,2 @@ +// Whatever is exported here will be available to the consumers of your npm module. +module.exports = {}; diff --git a/package.json b/package.json new file mode 100644 index 0000000..4813d47 --- /dev/null +++ b/package.json @@ -0,0 +1,35 @@ +{ + "name": "tagged-npm-seed", + "version": "0.0.0", + "description": "Tagged's seed project for NPM packages", + "main": "lib/index.js", + "scripts": { + "test": "grunt test" + }, + "repository": { + "type": "git", + "url": "http://github.com/tagged/npm-seed.git" + }, + "keywords": [ + "api", + "tagged", + "client" + ], + "author": "Web Team Awesome", + "license": "MIT", + "bugs": { + "url": "https://github.com/tagged/npm-seed/issues" + }, + "homepage": "https://github.com/tagged/npm-seed", + "devDependencies": { + "blanket": "^1.1.6", + "chai": "^1.9.1", + "grunt": "^0.4.5", + "grunt-contrib-clean": "^0.5.0", + "grunt-contrib-watch": "^0.6.1", + "grunt-docco": "^0.3.3", + "grunt-mocha-test": "^0.11.0", + "mocha": "^1.20.1", + "sinon": "^1.10.3" + } +} diff --git a/test/lib/index_test.js b/test/lib/index_test.js new file mode 100644 index 0000000..d72f2b4 --- /dev/null +++ b/test/lib/index_test.js @@ -0,0 +1,10 @@ +/*jshint expr: true*/ + +// Your npm package is accessible by requiring `LIB_DIR`. +var MyNpmPackage = require(LIB_DIR); + +describe('MyNpmPackage', function() { + it('exists', function() { + MyNpmPackage.should.exist; + }); +}); diff --git a/test/mocha.opts b/test/mocha.opts new file mode 100644 index 0000000..c0f394c --- /dev/null +++ b/test/mocha.opts @@ -0,0 +1,5 @@ +--require ./test/test_runner +--reporter dot +--ui bdd +--timeout 200 +--recursive diff --git a/test/test_runner.js b/test/test_runner.js new file mode 100644 index 0000000..ab67f00 --- /dev/null +++ b/test/test_runner.js @@ -0,0 +1,17 @@ +var path = require('path'); + +// Use constant to help with resolving path to lib code within test files +GLOBAL.LIB_DIR = path.join(process.cwd(), 'lib'); + +// Set up in-place instrumentation for code coverage +require('blanket')({ pattern: LIB_DIR }); + +// Set up sinon +GLOBAL.sinon = require('sinon'); + +// Set up chai +GLOBAL.chai = require('chai'); +chai.should(); +GLOBAL.assert = chai.assert; +GLOBAL.expect = chai.expect; +chai.config.includeStack = true;