Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

chore(docs): updates to documentation

  • Loading branch information...
commit 7caed0546a965c3ec3b69b701562152c6da2bfc9 1 parent dce5c10
@laurelnaiad authored
View
7 CONTRIBUTING.md
@@ -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! :)
View
213 README.md
@@ -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
}
@@ -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
@@ -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
@@ -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>
View
168 docs/readme/options.md
@@ -1 +1,167 @@
-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
View
32 docs/readme/overview.md
@@ -1,30 +1,32 @@
-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,
- 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' ],
+ 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: {
- // only demo/src files will be coverage-tested
- 'data-cover-only': '//demo\/src\//'
+ '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
}
Please sign in to comment.
Something went wrong with that request. Please try again.