further docs

Author: ShMcK

_posts/2016-01-05-tests.md

@@ -7,26 +7,54 @@ file: 2016-01-05-tests.md
 
 Unit tests are used to determine:
 
-* if a task passes
-* which feedback a user gets when a test fails
+* if a task passes or fails
+* feedback a user gets when a test fails
 
-### Loading the User File
+Tests are loaded in their order from the tutorial markdown files, and concat together into one temporary file. This means that any import or require statements placed at the top of the first file will be shared by all tests for that page.
 
-### Data Files
+Tests should indicate which task they are, in order to quickly determine which task index has failed. For the *mocha-coderoad* test runner, this is as easy as adding the task number to describe block.
 
-### Test Examples
+    describe('01 first task', function () { ... });
+    describe('04 fourth task', function () { ... });
 
-* exists
-* type
-* params
-* equals
-* deep equals
-* regex
-* property
-* spies
 
-### Dynamic Tests
+### Test Statements
 
-* task position
+It makes sense to write test statements using 'should', 'must' or negative statements. Remember, the failing test message will be delivered as feedback to the user.
 
-### Future Testing Tool
+    it('should be a function')
+    it('must be a function')
+    it('isn\'t a function')
+
+
+### Loaders
+
+Use a **loader** to run the user saved file in the context of your file. Think of a loader as a way to place the file your testing inside of your test file. Import your loader and run it on a specific user file.
+
+    var loadJS = require('path/to/loadJS').default;
+    loadJS('user-file.js');
+    // adds file contents here
+
+You'll have to roll your own loader to fit your project, but there are example [loaders](#loaders) included later in the docs.
+
+*Note: When using spies, stubs or mocks, initiate them above your loader call.*
+
+
+
+### Loading Data Files
+
+Data can be loaded in the user's file by setting it as a global within the test. Remember, the top of the test file (above the loader), acts as the top of the user's page.
+
+Although bad practice, it can be easiest to set data to the global scope.
+
+    if (!global.data) {
+      global.data = 43;
+    }
+
+    if (!global.data2) {
+      global.data2 = JSON.parse(JSON.stringify(require('./data2.json')));
+    }
+
+Users can access global data by name in their file.
+
+    var secret = data - 1;

_posts/2016-01-06-loaders.md

@@ -0,0 +1,66 @@
+---
+layout: docs
+title: Loaders
+id: loaders
+file: 2016-01-06-loading.md
+---
+
+Tutorials may be written in different programming languages or for different compilers, so there isn't yet a standard way to load data from user created files. Instead, you'll have to load your own solution into your tutorial and link to them from your test file. Rolling your own solution allows you to load data in a way that fits your project.
+
+These snippets should help:
+
+
+#### loadJS (JavaScript)
+
+    var vm = require('vm'),
+      fs = require('fs'),
+      path = require('path');
+    function loadJS(pathToContext) {
+      var absPath = path.join(process.env.DIR, pathToContext);
+      var code = fs.readFileSync(absPath, 'utf8');
+      vm.runInThisContext(code);
+    }
+    Object.defineProperty(exports, "__esModule", { value: true });
+    exports.default = loadJS;
+
+#### loadBabel (Babel)
+
+See the [Babel documentation](https://babeljs.io/docs/setup/#node) on how to install Babel & the selected [presets](http://babeljs.io/docs/plugins/#presets). Set the [options](http://babeljs.io/docs/usage/options/) you need.
+
+`> npm i -s babel-core` + presets
+
+    var vm = require('vm'),
+      fs = require('fs'),
+      path = require('path'),
+      babel = require('babel'),
+      options = {
+        presets: ['es2015']
+    };
+    function loadBabel(pathToContext) {
+      var absPath = path.join(process.env.DIR, pathToContext);
+      var code = fs.readFileSync(absPath, 'utf8');
+      var js = babel.transform(code, options);
+      vm.runInThisContext(js);
+    }
+    Object.defineProperty(exports, "__esModule", { value: true });
+    exports.default = loadBabel;
+
+#### loadTS (TypeScript)
+
+To use TypeScript, install the package as a tutorial dependency.
+
+`> npm i -s typescript`
+
+    var ts = require('typescript'),
+      options = {
+        module: 'commonjs',
+        target: 'ES5'
+    };
+    function loadTS(pathToContext) {
+      var absPath = path.join(process.env.DIR, pathToContext);
+      var code = fs.readFileSync(absPath, 'utf8');
+      var js = ts.transpile(code, options);
+      vm.runInThisContext(js);
+    }
+    Object.defineProperty(exports, "__esModule", { value: true });
+    exports.default = loadTS;

_posts/2016-01-07-publish.md

@@ -0,0 +1,103 @@
+---
+layout: docs
+title: Test Examples
+id: test-examples
+file: 2016-01-07-test-examples.md
+---
+
+Here are examples using *mocha* with *chai*'s *expect*. See the [docs](http://chaijs.com/api/bdd/).
+
+##### exists
+
+    it('doesn\'t exist', function() {
+      expect(target).to.not.be.undefined;
+    });
+
+##### type
+
+    it('should be a function', function() {
+      expect(target).to.be.a('function');
+    });
+
+##### function params
+
+    it('should have two parameters', function() {
+      expect(target).to.have.length(2);
+    });
+
+##### function returns
+
+    it('should add one to the number', function () {
+      expect(addOne(1)).to.equal(2);
+    });
+
+##### equals
+
+    it('should be 42', function () {
+      expect(target).to.equal(42);
+    });
+
+##### deep equals (with objects or arrays)
+
+    it('should be {a: 42}', function () {
+      expect(target).to.deep.equal({a: 42});
+    });
+
+##### regex
+
+    it('should access the property "prop"', function () {
+      var regex1 = /\.prop/;            // dot notation
+      var regex2 = /\[["']prop["']\]/;  // bracket notation
+      var string = target.toString();
+      var result = !!string.match(regex1) && !!string.match(regex2);
+      expect(result).to.be.true;
+    });
+
+##### spies
+
+You can use [*sinon*](http://sinonjs.org/docs/) or [*chai-spies*](https://github.com/chaijs/chai-spies) to create a spy. See an example below:
+
+`> npm i -s chai-spies`
+
+    var chai = require('chai');
+    var spies = require('chai-spies');
+    var expect = chai.expect;
+    chai.use(spies);
+
+    var spy = chai.spy.on(console, 'log');
+    loadJS('04-forEach.js');
+
+    it('should write "hello world" to the console', function () {
+      expect(spy).to.have.been.called.with('hello world');
+    });
+
+
+### Dynamic Tests
+
+There are situations where you might want to change data based on the current task. In this case, be careful, as all earlier tests must continue to pass.
+
+Some variables are passed into the test runner through the node environment *process.env*.
+
+See an example of dynamic data based on the task position below:
+
+    var data = [1, 2, 3];
+
+    if (process.env.TASK_POSITION === '4') {
+      data = [1, 2, 3, 4];
+    }
+
+Tests can also change based on the task position.
+
+    if (process.env.TASK_POSITION !== '4') {
+      it('should do this', function () { ... });
+    } else {
+      it('should to that', function () { ... });
+    }
+
+See a full [example](https://github.com/coderoad/coderoad-functional-school/blob/master/tutorial/1/04/01-forEach.spec.js).
+
+### Test Writing Tool
+
+It's entirely possible to create a simplified testing tool that could make writing tests faster & easier.
+
+The easiest solution would be to use editor snippets to generate a page of tests from a simple configuration object. This does not yet exist.

_posts/2016-01-07-test-examples.md

@@ -0,0 +1,7 @@
+---
+layout: docs
+title: Config
+id: config
+file: 2016-01-08-config.md
+---
+coming soon

_posts/2016-01-08-config.md

@@ -0,0 +1,47 @@
+---
+layout: docs
+title: Publishing
+id: publish
+file: 2016-01-09-publish.md
+---
+Make sure your tutorial is ready and user tested before publishing to NPM.
+
+In the future this process will be further simplified by `> coderoad publish [version]`.
+
+### Completing your *package.json*
+
+* "name" - beginning with 'coderoad-'
+* "description" - about your tutorial
+* "author" or "authors" information
+* "keywords" - about your tutorial
+* "repository" - if added, *Atom-CodeRoad* can allow edits
+* "bugs" - if added, *Atom-CodeRoad* can provide a link to your github issues
+* "dependencies" - including your test runner, and test framework tools
+* "config" - see [config](#config)
+
+See an [example](https://github.com/coderoad/coderoad-functional-school/blob/master/package.json) of a complete *package.json* file.
+
+### Versioning
+
+Versioning is handled by:
+
+* the *package.json* declared "version"
+* the [git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging)
+
+      > git tag 0.1.0
+      > git push --tags
+
+Try to make sure the two specified versions match.
+
+### Publishing to NPM
+
+Publishing to NPM is easy, which may be one of the reasons why the NPM registry is so crowded with packages. Please ensure your package name is prefixed with `coderoad-` to limit package registry cluttering.
+
+Have an [NPM account](https://www.npmjs.com/signup) before running publish.
+
+    > npm publish
+
+
+### Promoting your Tutorial
+
+As CodeRoad is a new project, there is not yet a place to display tutorials. If you create something for CodeRoad please send an email to [email protected], or tweet at @coderoadapp.

_posts/2016-01-09-publish.md

@@ -2,7 +2,7 @@
 layout: docs
 title: Test Runners
 id: test-runner
-file: 2016-01-06-testRunner.md
+file: 2016-01-10-testRunner.md
 ---
 coming soon