TDDforJS ======== A Test Driven Development framework for Javascript. TDD aims to provide a very simple test running environment, that mimics jUnit. It doesn't provide any sort of assertion framework, and it's not going to fold your clothes either. Just a few nice conventions to make testing JS a bit easier. Requirements ======== node and npm Setup ======== 1. `npm install tddforjs` 2. `$(npm bin)/tddforjs` 3. Set the appropritate values in `config/tddforjs.json` 4. `$(npm bin)/tddforjs` It's really that simple. Config ======== TDD uses config-tools to look for a `config/tddforjs.json` file within your project root. The following is a default config file: ```javascript { "reporting":{ "mode":"cli", "available":[ "cli", "junit", "testng" ], "base":"../reports", "output":{ "types":{ "junit":true, "testng":false } } }, "src":{ "base":"../src", "js":"./js", "names":[ ".*\\.js" ] }, "test":{ "base":"../test", "integrations":"./integrations", "units":"./units", "names":{ "units":[".*\\.js"], "integrations":[".*\\.js"] } } } ``` Convention ========= By default, TDD assumes that each file under `src/js` will have an accompanying unit test under the `test/units` directory. A default project structure looks like this: ``` $ProjectRoot/ | | |____src/ | | | |____js/ | | | |__MyFile.js | | |____test/ | |____units/ | | | |__MyFile.js | | |____integrations/ ``` TDD will run tests in `units/MyFile.js` against `src/MyFile.js`. All suites found in `integrations/` will be run as well. Sample Test Suite ======== Here is a sample test suite. The inspiration comes from jUnit 4.x, so the following holds true: * if a function marked `before` exists within your Test Suite, it will be executed before any test * if a function marked `after` exists within your Test Suite, it will be executed after any test * any function prefixed with `//Test` is considered a test. * Errors with the term `assert` in their constructor show as a failure. * Errors not an instanceof Error show as a failure. * Errors that are an instance of Error show as an error. ```javascript var assert = require('assert'); var factory; function before(){ factory = new AppFactory(); } function after(){ } //Test function ImportResolver_should_be_creatable(){ ImportResolver = function(){}; if(!(factory.makeImportResolver() instanceof ImportResolver)){ throw "ImportResolver wasn't created."; } } //Test function TDDforJSEvaluator_should_be_creatable(){ TDDforJSEvaluator = function(){}; if(!(factory.makeTDDforJSEvaluator() instanceof TDDforJSEvaluator)){ throw "TDDforJSEvaluator wasn't created."; } } //Test function TestSuite_should_be_creatable(){ TestSuite = function(){}; if(!(factory.makeTestSuite() instanceof TestSuite)){ assert.fail("TestSuite wasn't created."); } } //Test function TestSuites_should_be_creatable(){ TestSuites = function(){}; if(!(factory.makeTestSuites() instanceof TestSuites)){ assert.fail("TestSuites wasn't created."); } } //Test function SuiteFileResolver_should_be_creatable(){ SuiteFileResolver = function(){}; if(!(factory.makeSuiteFileResolver() instanceof SuiteFileResolver)){ assert.fail("SuiteFileResolver wasn't created."); } } ``` And here's the source file: ```javascript /** * @constructor * @param {Object} fsModule * @param {Object} pathModule * @param {string} hostname */ function AppFactory( fsModule, pathModule, hostname ){ var instance = this; /** * @param {string} sourceBase * @param {string} testBase * @return {ImportResolver} */ this.makeImportResolver=function(sourceBase, testBase){ return new ImportResolver(fsModule, pathModule, sourceBase, testBase); }; /** @return {TDDforJSEvaluator} */ this.makeTDDforJSEvaluator=function(){ return new TDDforJSEvaluator(); }; /** * @param {string} className * @param {string} hostname * @param {number} id * @param {string} source * @returns {TestSuite} */ this.makeTestSuite=function( className, hostname, id, source ){ return new TestSuite( "__$$__", className, hostname, id, source ); }; /** * @param {Array.} files * @param {SuiteFileResolver} fileResolver * @param {ImportResolver} importResolver * @param {TDDforJSEvaluator} evaluator * @param {function(string): string} extraSourceFn * @returns {TestSuites} */ this.makeTestSuites=function( files, fileResolver, importResolver, evaluator, extraSourceFn ){ return new TestSuites( files, instance, hostname, fileResolver, importResolver, pathModule, evaluator, extraSourceFn ); }; /** * @param {string} baseDir * @returns {SuiteFileResolver} */ this.makeSuiteFileResolver=function(baseDir){ return new SuiteFileResolver( fsModule, pathModule, baseDir ); }; } ``` Importing ======== TDD allows your test suites to import any javascript file for the duration of your test. The following paths are searched for a match in order: `test/` `src/` To define imports, you specify comments at the top of your suite like this: ```javascript //import foo //import lib/jsmockito function before(){ } //continue testing... ``` Errors in Source ======== Because TDD is declarative in the sense that you follow a convention to define test cases, TDD can report the number of test cases defined in a suite even when they can't be run due to an uncaught error in your source, suite, or any import. Let's say we have the following source: ```javascript //import foo throw 5; ``` And we're testing it with a unit test: ```javascript //Test function foo_should_foo(){ } ``` We would report 1 test and 1 failure for our unit test, despite the fact that there's clearly an error in our source file when the unit test is run. This feature extends to suites and imported files. Reporting ======== TDD aims to provide support for three types of reports: * CLI * jUnit XML * TestNG XML The two latter types would enable integration with a CI server like Hudson or Jenkins. Here's what a sample report looks like from the CLI: ``` ======================================== UNIT TEST REPORT ======================================== Suites : 6 Tests : 50 Failures : 0 Errors : 0 ======================================== INTEGRATION TEST REPORT ======================================== Suites : 1 Tests : 0 Failures : 0 Errors : 0 ``` Here's what a junit report looks like for hudson and jenkins: ```xml

``` TDD only reports errors and failures, so if we were to do something in our sample suite that would fail a test, the output would look like this for the CLI: ``` ======================================== UNIT TEST REPORT ======================================== Suites : 6 Tests : 50 Failures : 1 Errors : 0 Suite: AppFactory Tests : 5 Failures : 1 Errors : 0 Case : ImportResolver_should_be_creatable Failure : unknown : boo ======================================== INTEGRATION TEST REPORT ======================================== Suites : 1 Tests : 0 Failures : 0 Errors : 0 ``` And in the JUnit report: ```xml

``` Console Logging ========== Console logging can come in handy for debugging purposes. It can also be very difficult to decipher it's output without any context. TDD overrides console and places the messages in the reports. Let's add a `console.log` statement to a test case: ```javascript //Test function ImportResolver_should_be_creatable(){ ImportResolver = function(){}; if(!(factory.makeImportResolver() instanceof ImportResolver)){ throw "ImportResolver wasn't created."; } console.log("calling console.log", "with some arguments", 5, 6, 7) } ``` Here's what the CLI report shows: ``` ======================================== UNIT TEST REPORT ======================================== Suites : 6 Tests : 50 Failures : 0 Errors : 0 Suite: AppFactory Tests : 5 Failures : 0 Errors : 0 Stdout : console.log(calling console.log , with some arguments , 5 , 6 , 7) ======================================== INTEGRATION TEST REPORT ======================================== Suites : 1 Tests : 0 Failures : 0 Errors : 0 ``` Here's what the JUnit report shows: ```xml

console.log(calling console.log , with some arguments , 5 , 6 , 7);

```