Awesome
urequire-ab-specrunner
Automagically generates and runs Specs using mocha, chai & phantomjs after running a lib
and a specs
build in uRequire running on grunt.
Introduction
Manually configuring watch
, mocha
tasks and phantomjs, requirejs/AMD & all their relative paths, configs, shims, HTMLs etc against each different build, can be a huge pain. You 'll find repeating your self too much, fiddling with what paths work and what breaks, instead of writing awesome libs and specs.
Here comes urequire-ab-specrunner, an afterBuild
-er that is build around urequire's (>= v0.7) afterBuild
facility: with a single declaration and no other configuration, it generates HTML and specs invocations for nodejs & browser and runs them each time you build!
It basically uses uRequire's bundle
& build
information already in the urequire config (and the materialized bundle & build) to do its magic. It relies on urequire auto discovery of dependencies paths (using bower and npm behind the scenes) and it automagically generates, configures and runs your specs against the lib using node's mocha
and mocha-phantomjs
(which are assumed to be installed and working on your machine).
It works perfectly with watching through grunt-contrib-watch
, which you dont need to configure at all (but is assumed to be locally installed along grunt). The best parts is that because uRequire really knows if your bundle sources really changed (not just some white space or some comments changed in your javascript or coffeescript, but the actual AST) or if a build failed, urequire-ab-specrunner wont run the specs until the errors are resolved and only if sources really changed.
It even auto generates the SpecRunner HTML with the RequireJs config & paths (or depending on the templates used if AMD isn't available/needed it uses the <script src='../../../tedious/paths/to/somedep.js'/>
that still respect the requirejs config's shim
) and runs them!
Usage
Assuming you already have some configs of your lib, for example libUMD
, libMin
etc and some for the specs against it, for example spec
, All you 'll need is:
libUMD: {...}
libMin: {...}
spec: {...}
specRun:
derive: ['spec']
dependencies: paths: bower: true
afterBuild: require('urequire-ab-specrunner')
and hit $ grunt libUMD specRun
or $ grunt libMin specRun
etc - just remember to invoke them in pairs of a lib
build followed by a spec
build. You can add the afterBuild: require('urequire-ab-specrunner')
to spec
so that all specXXX
inherit it, and then hit $ grunt libUMD specMin
.
Add a watch: true
to either your lib
or spec
config (or both), and watch
-ing starts automatically after the first successful build (it actually auto configures and invokes grunt-contrib-watch
).
See urequire-example for a full working example.
Options
You can pass options by invoking
afterBuild: require('urequire-ab-specrunner').options({
someOption: someValue })
and passing an options object. The actual options are :
injectCode
/ injectRaw
You can add arbitrary code / HTML in the generated HTML, usually to setup globals or other things not covered by urequire-ab-specrunner. The code is injected before any other libraries are loaded, just after mocha.js
& chai.js
are loaded.
injectCode
injects its content inside a <script>
tag, while injectRaw
injects the contents as it is in the HTML. You can use both, injectCode
where comes 1st.
Example
afterBuild: require('urequire-ab-specrunner').options({
injectCode: """
// test `noConflict()`: create a global that 'll be 'hijacked' by rootExports
window.urequireExample = 'Old global `urequireExample`';
"""})
mochaSetup
By default a mocha.setup('bdd')
is called - you can pass a String
or an {}
to change that default:
Example
mochaSetup: { ui: 'bdd', ignoreLeaks: false }
mochaOptions
You can pass options to the mocha
or mocha-phantomjs
CLI executables - just note that not all options are supported on mocha-phantomjs
- check its docs.
Example
mochaOptions: "-R dot -t 200"
globals
By default mocha.run().globals([...])
are automatically detected by your urequire config, locals, shims etc. You can add some of your own:
Example
globals: ['someGlobal', 'anotherOne']
runOnErrors
By default its false
, but you can change to true
if you're impatient.
specRunners
There are 2 + 1 spec runners called mocha-cli
, mocha-phantomjs
and the +1 is grunt-mocha
.
By default urequire-ab-specrunner runs only the first two (cause grunt-mocha
is veeeery slow and not really needed) in these cases:
-
If your build's templates are anything but
nodejs
andAMD
, bothmocha-cli
,mocha-phantomjs
run (ie you automatically test onnodejs
andbrowser
). -
If your build's templates are
nodejs
orAMD
, specs run only on eithermocha-cli
ormocha-phantomjs
(ie you test on either onnodejs
orbrowser
).
If you force it to use an incompatible one with your template (eg AMD
on mocha-cli
) it'll complain. Best left on default setting.
Example
specRunners: ['mocha-cli', 'mocha-phantomjs']
which is the soft default, meaning it will uncomplainingly skip incompatible runtime tests (i.e nodejs
template builds on mocha-phantomjs
).
exec
If exec: truthy
it uses require('child_process').exec
instead of require('child_process').spawn
(the default).
Spawn is preferred cause it taps mocha output (and assertion failures) as its generated. Use it only if you get ENOENT
problems while running mocha
or mocha-phantomjs
(which you shouldn't, even on windows).
tidy
If tidy: truthy
it uses htmltidy
to beautify the resulted HTML. By default its off.
Note that htmltidy has a couple of known breaking issues especially on x64 linux distros (spawn ENOENT) cause its just a nodejs wrapper to an outdated 32bit binary, but there are workarounds. Also its author considers it experimental on darwin (Mac).
debugLevel
Prints debug info, goes from 0
(default) to 100
.
License
The MIT License
Copyright (c) 2014 Agelos Pikoulas (agelos.pikoulas@gmail.com)
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.