Initial Release

v0.1.0

.gitignore

@@ -0,0 +1 @@
+node_modules

LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2013 Open Web Stack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,4 +1,103 @@
-gruntacular
-===========
+#gruntacular
+Grunt plugin for [Testacular](http://vojtajina.github.com/testacular/)
+NOTE: this plugin requires Grunt 0.4.x
 
-Grunt plugin for testacular
+##Getting Started
+From the same directory as your project's Gruntfile and package.json, install this plugin with the following command:
+
+`npm install gruntacular --save-dev`
+
+Once that's done, add this line to your project's Gruntfile:
+
+```js
+grunt.loadNpmTasks('gruntacular');
+```
+
+##Config
+Inside your `Gruntfile.js` file, add a section named *testacular*, containing any number of configurations for running testacular. The only required option is the path to the [testacular config file](https://github.com/vojtajina/testacular/wiki/Configuration-File-Overview). Here's a simple example:
+
+```js
+testacular: {
+  unit: {
+    configFile: 'testacular.conf.js'
+  }
+}
+```
+
+You can override any of the config file's settings directly:
+
+```js
+testacular: {
+  unit: {
+    configFile: 'testacular.conf.js',
+    runnerPort: 9999,
+    singleRun: true,
+    browsers: ['PhantomJS']
+  }
+}
+```
+
+##Running tests
+There are three ways to run your tests with testacular:
+
+###Testacular Server with Auto Runs on File Change
+Setting the `autoWatch` option to true will instruct testacular to start a server and watch for changes to files, running tests automatically:
+
+```js
+testacular: {
+  unit: {
+    configFile: 'testacular.conf.js',
+    autoWatch: true
+  }
+}
+```
+Now run `$ grunt testacular`
+
+However, usually Grunt projects watch many types of files using [grunt-contrib-watch](https://github.com/gruntjs/grunt-contrib-watch), so this option isn't preferred. 
+
+###Testacular Server with Grunt Watch
+Config testacular like usual (without the autoWatch option):
+
+```js
+testacular: {
+  unit: {
+    configFile: 'testacular.conf.js'
+  }
+}
+```
+
+Config your `watch` task to run the testacular task with the `:run` flag. For example:
+
+```js
+watch: {
+  //run unit tests with testacular (server needs to be already running)
+  testacular: {
+    files: ['app/js/**/*.js', 'test/browser/**/*.js'],
+    tasks: ['testacular:unit:run'] //NOTE the :run flag
+  }
+},
+```
+
+In one terminal window start the testacular server by running `$ grunt testacular`. In another terminal window start grunt watch by running `$ grunt watch`. Now when grunt watch detects a change to one of those files, it will run the testacular tests using the already running testacular server. This is the preferred method for development.  
+
+###Single Run
+Keeping a browser window & testacular server running during development is productive, but not a good solution for build processes. For that reason testacular provides a "continuous integration" mode, which will launch the specified browser(s), run the tests, and close the browser(s). It also supports running tests in [PhantomJS](http://phantomjs.org/), a headless webkit browser which is great for running tests as part of a build. To run tests in continous integration mode just add the `singleRun` option:
+
+```js
+testacular: {
+  unit: {
+    configFile: 'config/testacular.conf.js',
+  },
+  //continuous integration mode: run tests once in PhantomJS browser.
+  continuous: {
+    configFile: 'config/testacular.conf.js',
+    singleRun: true,
+    browsers: ['PhantomJS']
+  },
+}
+```
+
+The build would then run `grunt testacular:continuous` to start PhantomJS, run tests, and close PhantomJS.
+
+##License
+MIT License

package.json

@@ -0,0 +1,24 @@
+{
+  "name": "gruntacular",
+  "version": "0.1.0",
+  "description": "grunt plugin for testacular",
+  "main": "testacularServer.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OpenWebStack/gruntacular.git"
+  },
+  "keywords": [
+    "gruntplugin",
+    "testacular",
+    "test"
+  ],
+  "author": "Dave Geddes",
+  "license": "MIT",
+  "readmeFilename": "README.md",
+  "dependencies": {
+    "testacular": "~0.5.7"
+  }
+}

tasks/gruntacular.js

@@ -0,0 +1,19 @@
+var runner = require('testacular').runner;
+var server = require('testacular').server;
+
+module.exports = function(grunt) {
+  grunt.registerMultiTask('testacular', 'run testacular.', function() {
+    var done = this.async();
+    if (this.data.configFile) {
+      this.data.configFile = grunt.template.process(this.data.configFile);
+    }
+    //support `testacular run`, useful for grunt watch
+    if (this.flags.run){
+      runner.run(this.data, finished.bind(done));
+      return;
+    }
+    server.start(this.data, finished.bind(done));
+  });
+};
+
+function finished(code){ return this(code === 0); }