Skip to content

Commit

Permalink
chore(docs): updates to documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@laurelnaiad
laurelnaiad committed Oct 1, 2013
1 parent dce5c10 commit 7caed05
Show file tree
Hide file tree
Showing 4 changed files with 378 additions and 42 deletions.
7 changes: 4 additions & 3 deletions CONTRIBUTING.md
View file
Expand Up @@ -3,9 +3,10 @@ Contributions, as feedback in the [issues list](issues) or as pull requests, are
For pull requests:

* In lieu of a formal styleguide, take care to maintain the existing
coding style. Add unit tests for any new or changed functionality.
coding style. ~~Add unit tests for any new or changed functionality.~~
* Yes, please use CoffeeScript.
* Yes, please ensure that all code is **covered** by tests! It's a very simple grunt task, people -- setting
~~* Yes, please ensure that all code is **covered** by tests! It's a very simple grunt task, people -- setting
up the test framework was more work than authoring the task -- coverage
is a walk in the park. :) Just run `grunt test` -- unit tests are reported to the console, and if they succeed,
then coverage stats are also reported in the console and the html report is made available at `'./test/coverage.html'`.
then coverage stats are also reported in the console and the html report is made available at `'./test/coverage.html'`.~~
* As of now, youi're off the hook on unit tests until a (real) testing suite is in place! :)
213 changes: 190 additions & 23 deletions README.md
View file
Expand Up @@ -87,35 +87,35 @@ grunt.loadNpmTasks('grunt-blanket-mocha-server');
## Overview
[[Back To Top]](#jump-to-section)

Below you will find the standard Grunt plugin documentation for the task. For
the impatient, this is a typical configuration (using primarily defaults for configurable
options):
The `blanket-mocha-server` task is primarily a shortcut to creating
and a means for programmatically controlling a test runner html file. *By default,
it also serves the test runner using `grunt-contrib-connect`, but you can disable this.*

```
It works by allowing you to specify paths and options that are inserted using
Grunt's JST template system into a test runner template.

A typical basic configuration follows. More information can be found in the
[Options](#options) section.

```javascript
blanket_mocha_server: {
demo: {
options: {
port: 3001,
testConfig: {
htmlFile: 'demo/test-runner.html',
// system-under-test will be all js files below demo/src
sutFiles: [ 'demo/src/**/*.js' ],
// test files are *.spec.js files found under demo/test
testFiles: [ 'demo/test/**/*.spec.js' ]
blanketOptions: {
// only demo/src files will be coverage-tested
'data-cover-only': '//demo\/src\//'
}
htmlFile: 'demo/test-runner.html', // the file to create (and serve as the test runner)
sutFiles: [ 'demo/src/**/*.js' ], // system-under-test will be all js files below demo/src
testFiles: [ 'demo/test/**/*.spec.js' ], // test files are *.spec.js files found under demo/test
blanketOptions: {
'data-cover-only': '//demo\/src\//' // only demo/src files will be evaluated for coverage
}
}
}
},
// basic blanket_mocha configuration -- note that the path
// corresponds to the one specified for the server to serve
blanket_mocha: {

blanket_mocha: { // basic config for the grunt-blanket-mocha task
demo: {
options: {
urls: [ 'http://localhost:3001/demo/test-runner.html' ],
urls: [ 'http://localhost:3001/demo/test-runner.html' ], // the file created by blanket_mocha_server
reporter: 'Nyan',
threshold: 80
}
Expand All @@ -127,7 +127,173 @@ blanket_mocha: {
## Options
[[Back To Top]](#jump-to-section)

options here
### In General

*Don't let the number of options intimidate you.* Almost all of them
have sane defaults and need not be modified.

If you don't specify `server: false`, then this task will run a grunt-
contrib-connect server after generating the test runner. Any options
that you specify which apply to grunt-contrib-connect will be passed
through to that task -- so, for example, you can (and might want to)
set the `port` to something other than the default (3000).

<a id="optionsIndex">**Index**</a>:

* [Note on Default Paths](####Note-On-Default-Paths)
* [assertionLibs](#assertionLibs)
* [assertionsSetupScript](#assertionsSetupScript)
* [blanketOptions](#blanketOptions)
* [blanketPath](#blanketPath)
* [blanketPhantomOptions](#blanketPhantomOptions)
* [gruntReporterPath](#gruntReporterPath)
* [htmlFile](#htmlFile)

---

#### Note On Default Paths

Many of the default values for options are relative to three directories:

* **gbmsLib**: `__dirname + '/../lib/'`. The lib directory of this package.
* **gbmsSupport**: `__dirname + '/support/'`. The support tasks/support directory of this package.
* **gbmSupport**: `process.cwd() + '/node_modules/grunt-blanket-mocha/support/'`. The `grunt-blanket-mocha` support directory. It is assumed that `grunt-blanket-mocha` is installed as a peer of this task.

In general, you can use the defaults and the files they specify. If you specify your own paths, they will be interpreted as relative to the directory from which you run grunt (i.e. `process.cwd()`).

Aside from assertion libraries, the primary reason that you might
override default paths is to bring your own copy of blanket, mocha or
grunt-blanket-mocha files -- if you want to use a version that is not
bundled with this plugin, for example. As of this release, the mocha, blanket and chai libraries
are included as js files in this plugin distribution. Feedback is welcome as to whether to npm-depend
on their packages or use bower so that they are more likely to stay up-to-date. Including the libraries directly was
chosen because it dramatically reduces the resulting footprint of using the plugin. You can always use
bower or npm dependencies and manually assign the paths.

[Return to Index](#optionsIndex)

#### <a id="assertionLibs">options.assertionLibs</a>

Type: `{(string|Array.<string>)}` Default value: `gbmsLib + 'chai.js'`

The path to one or more assertion libraries. As it is the most popular choice with mocha, chai is included as the only default.

If you are testing in IE8, you may wish to override this default and specify <a href="https://github.com/LearnBoost/expect.js" target="_blank">expect.js</a> as the assertion library because chai is not compatible with IE8.

[Return to Index](#optionsIndex)

#### <a id="assertionsSetupScript">options.assertionsSetupScript</a>

Type: `{string}` Default value: `'window.expect = chai.expect; var should = chai.should();'`

Script to configure an assertion library (or libraries). The default script makes chai's expect function globally available and installs chai's should decorator to Object (see chai should documentation).

[Return to Index](#optionsIndex)

#### <a id="blanketOptions">options.blanketOptions</a>

Type: `{?Object.<string, string>}` Default value: `null`

Name value pairs to be assigned to blanket as options. **You will probably at a minimum
want to set data-cover-only to inform blanket of which files should be covered.
Make sure to escape your backslashes!**

If you set:

```js
blanketOptions: {
'data-cover-only': '//build\\/.*/',
'data-cover-modulepattern': 'build\\/(.*)\\/[^\\/]+$'
}
```
Then in the test runner you will have:

```html
<script type="text/javascript" charset="utf-8"
src="<%= gbmsLib + 'blanket.js' %>"
data-cover-only: "//build\/.*/"
data-cover-modulepattern="build\/(.*)\/[^\/]+$"
</script>
```
[Return to Index](#optionsIndex)
#### <a id="blanketPath">options.blanketPath</a>
Type: `{string}` Default value: `gbmsLib + 'blanket.js'`
The path to blanket.js.
[Return to Index](#optionsIndex)
#### <a id="blanketPhantomOptions">options.blanketPhantomOptions</a>
Type: `{?Object.<string, string>}` Default value: `null`
Name value pairs to be assigned to blanket as options **only when running tests from grunt** (which
uses PhantomJS). The options specified here will have no impact on tests that run in your browser.
Note that the `reporter` option is set for you by default in a separate configuration property --
[gruntReporterPath](#gruntReporterPath).
If you set:
```js
blanketPhantomOptions: {
'dataCoverFlags': 'branchTracking'
}
```
Then in the test runner you will have:
```html
<script type="text/javascript" charset="utf-8">
if (window.PHANTOMJS) {
blanket.options( // reporter is set set by default
"reporter",
"<%= gbmSupport + 'grunt-reporter.js' %>"
);
blanket.options(
"dataCoverFlags",
"branchTracking"
);
}
</script>
```
[Return to Index](#optionsIndex)
#### <a id="gruntReporterPath">options.gruntReporterPath</a>
Type: `{string}` Default value: `<%= gbmSupport + 'grunt-reporter.js' %>`
The path to grunt-blanket-mocha's grunt reporter.
[Return to Index](#optionsIndex)
#### <a id="htmlFile">options.htmlFile</a>
Type: `{string}` Default value: `null`
The path where the HTML file that this task generates will be saved. You must specify this option.
The combination of this path and the port on which you serve the test runner should match the
grunt-blanket-mocha configuration if you are using grunt-blanket-mocha.
Example:
```js
htmlFile: 'test/test-runner.html'
```
[Return to Index](#optionsIndex)
mochaBlanketPath: gbmSupport + 'mocha-blanket.js'
mochaCssPath: gbmsLib + 'mocha.css'
mochaPath: gbmsLib + 'mocha.js'
mochaSetupScript: 'mocha.setup(\'bdd\');'
noCoverage: false
runnerTemplate: gbmsSupport + 'test-runner-template.html'
server: true
sutFiles: null
testFiles: null
## Contributing
Expand All @@ -138,12 +304,13 @@ Contributions, as feedback in the [issues list](issues) or as pull requests, are
For pull requests:
* In lieu of a formal styleguide, take care to maintain the existing
coding style. Add unit tests for any new or changed functionality.
coding style. ~~Add unit tests for any new or changed functionality.~~
* Yes, please use CoffeeScript.
* Yes, please ensure that all code is **covered** by tests! It's a very simple grunt task, people -- setting
~~* Yes, please ensure that all code is **covered** by tests! It's a very simple grunt task, people -- setting
up the test framework was more work than authoring the task -- coverage
is a walk in the park. :) Just run `grunt test` -- unit tests are reported to the console, and if they succeed,
then coverage stats are also reported in the console and the html report is made available at `'./test/coverage.html'`.
then coverage stats are also reported in the console and the html report is made available at `'./test/coverage.html'`.~~
* As of now, youi're off the hook on unit tests until a (real) testing suite is in place! :)
## FAQ
Expand Down Expand Up @@ -186,4 +353,4 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
--------
<small>_This readme has been automatically generated by [readme generator](https://github.com/aponxi/grunt-readme-generator) on Mon Sep 23 2013 12:49:25 GMT-0700 (PDT)._</small>
<small>_This readme has been automatically generated by [readme generator](https://github.com/aponxi/grunt-readme-generator) on Tue Oct 01 2013 09:45:50 GMT-0700 (PDT)._</small>

0 comments on commit 7caed05

Please sign in to comment.