coveraje v0.2.4

coveraje

a simple javascript code coverage tool...

Usage

coveraje provides only few public functions

coveraje.cover(code, runner, options, callback)

code string || function
the code that should be tested. if it's a function, it should return a string this function is called, everytime the page is refreshed (F5)

runner function | { key: function }
This parameter takes a runner-function, or an object with multiple runners.
If it's an object with multiple runners, the key should be descriptive (it's used to distinguish between the runners). The runner/s is/are called from coveraje.

function runner(context, instance){
  // code to run
}

Each runner is called with two arguments.
- context the global scope of the executed code
- instance the coveraje instance
In order to get asynchronous tests run until the end, you have to use

return coveraje.runHelper.createEmitter(function (event) {
  // test code, e.g.
  require("fs").readFile("path", function (err, data) {
      event.complete();
  })
})

as your runner code. Don't use setTimeout/setInterval in your test directly. Use context.setTimeout/context.setInterval instead.
Don't forget event.complete();.

options { key: value }
Currently, there are the following options

beautify boolean
if true, the code to inspect will be beautified (by uglifyjs) first
All comments are stripped by the beautifier.
default: false

colorizeShell boolean
if true, uses ANSI escape sequences to color the console output
In case you get wierd text in your console, turn it off...
default: true

globals "node", "browser", or any combination
defines, which global objects are defined. the modes can be combined (separated with blanks).
"browser" requires jsdom (which has some known problems on windows (contextify))
default: ""

prefix string
while injecting code, also some variables has to be defined. These are prefixed so they don't interfere with the variables defined in code. Usually, you don't have to change this prefix, unless you have variables starting with _cj$_.
default: "_cj$_"

quiet boolean
if true, suppress output to console
default: false

resolveRequires string - array
if globals contains "node" and you use require in your source, this array is used to determine if the loaded module should be covered, too.
for now, this only works for relative or absolute paths as the require-parameter
you can also add "*" to this array, so it resolves every required file
default: []

serverHost string
the host to use if useServer = true
default: "127.0.0.1"

serverPort int
the port to use if useServer = true
default: 13337

stripFirstComments boolean
removes all starting comments from the code. You won't always scroll to the first line of code ;)
default: true

stripSheBang boolean
removes \#!... if it's in the first line
default: true

useServer boolean
starts a web server to provide the results in your favorite browser.
You are able to start every or a single runner and see the results
default: false

wait int
if the code uses setTimeout/setInterval, you can wait some time before the results are generated.
It's better to use coveraje.runHelper.createEmitter().
default: 0

callback
the callback function is called after all requested runners are finished.
it takes one argument, the coveraje instance. With this you can e.g. create reports

function onComplete(instance) {
    console.log(instance.report("default"));
}

Dependencies:

coveraje needs

• Node.js
  The runtime. A version that runs in browsers only is on the agenda.

• UglifyJS

Sometimes-Dependencies

• JQuery
  The web interface uses jquery (latest version is loaded from jQuery CDN)

• JSDom
  Depending on the configuration (option globals), jsdom (and its dependencies) is used.
  Currently it does not work well on Windows (blame on contextify) - but it should work in the near future (promised for version 0.3.0)

• expresso
  if you choose the expresso helper, you will need expresso ;)

• nodeunit
  if you choose the nodeunit helper, you will need nodeunit...

• mocha
  if you choose the mocha helper, you will need mocha...

Development-Dependencies

• JSHint
  all js-files are linted by jshint, so it's needed for the tests

TDD Frameworks:

If you have unit tests (you should) and want to know how they cover your source code, you may try it with a helper to create a test runner.
Currently there are helpers for expresso, nodeunit, and mocha.

To use such a helper, you have to define runners like in the following example.

function test() {                       // the runner, has to be used in cover() function
    return function (context) {
        return coveraje.runHelper(      // It's vital to return the result
            "name",                     // name of the helper, e.g. "mocha"
            options                     // helper options, see comment in lib/helper/... for more details
        ).run(relativePathToTestFile);  // the (unmodified) test file you created
    };
}

Take a look at examples/*, too.

The expresso-helper modifies the expresso-source code on the fly (not permanent). This can lead to bugs in future versions of expresso (will say: please report bugs as soon as possible *g*).