deadunit

Status: API finalized, needs testing

deadunit

A dead-simple nesting unit testing module for node.js (and someday the browser!). This repository provides default visual representations for the output of deadunit-core, as well as a formatter that can be used to easily create custom test visualizations.

'Now with both console and HTML output!'

Why use it over...

• Jasmine / Node-Unit / Wizek's Tree
• deadunit's dead-simple API only has two major ways to assert behavior (ok and count) making it easy to learn.
• deadunit prints the lines of code of asserts in the test results!
• deadunit just uses javascript! It doesn't have an awkward sentence-like api.
• deadunit's count method elegantly solves various issues like expecting exceptions and asynchronous asserts - just count up the number of oks!
• deadunit follows best practices for modular design rather than creating global variables and functions
• deadunit doesn't provide spies. The use of spies is bad practice as tests should treat the modules they test as black boxes by only testing the public API. The internals of these APIs should be left alone.
• deadunit is simpler to use because it doesn't provide needless sugar (e.g. Tree's always-pass/always-fail asserts)
• deadunit doesn't proscribe synchronization for you - it only expects that you tell it when all the tests are complete (using this.done()).
• deadunit supports testing code that uses node fibers
• deadunit's output is easier to visually parse than jasmine, or wizek's tree, and much easier than node-unit

Deadunit doesn't work in the browser yet tho, whereas Jasmine and Tree do.

Example

var Unit = require('deadunit')

var test = Unit.test('some test name', function() {
    this.count(5) // expect all 5 `ok` assertions

    var obj = someFunctionToTest()
    this.ok(obj.x === 5)
    this.ok(obj.y === 'y')

    this.test('nested test', function() {
        this.ok(obj.go() > 4)
    })

    try {
    	doSomethingBad()
    } catch(e) {
    	this.ok(true) // expect an exception
    }

    doSomethingAsynchronous(function(result) {
        this.ok(result === 'good')
    })
})

test.writeConsole() // writes colorful output!
test.html()         // returns pretty html!

Install

npm install deadunit

Usage

Unit Tester

var Unit = require('deadunit')

Unit.test([<name>, ]<testFunction>) - runs a suite of unit tests. Returns an ExtendedUnitTest object.

Unit.error(<handler>) - see deadunit-core

Unit.format(<unitTest>, <format>) - creates custom formatted output for test results according to the passed in <format>.

Unit.string(<results>, <colorize>) - returns a string containing formatted test results for the passed in. The format of the results is the format returned by deadunit-core's results method. See below for screenshots.

• <unitTest> is a UnitTest (or ExtendedUnitTest) object
• <format> - an object containing functions that format the various types of results. Each formater function should return a String.
  • format.assert(result, testName)
    • result is a deadunit-core assert result object
    • testName is the name of the test the assert is under
  • format.exception(exception)
    • exception is an exception object (could be any object that was thrown)
  • format.group(name, totalDuration, totalSynchronousDuration, testCaseSuccesses, testCaseFailures, assertSuccesses, assertFailures, exceptions, results, exceptionResults, nestingLevel)
    • name is the test group name
    • totalDuration - the total duration the test took from start to the last test-action
    • totalSynchronousDuration - the time it took for the test function to complete synchronously (ignores all asynchronous parts)
    • testCaseSuccesses - the number of successful asserts (the ok method) and groups in this test group. Does not count asserts and test-groups inside subtest groups
    • testCaseFailures - the number of failed asserts and groups in this test group. Does not count asserts and test-groups inside subtest groups
    • assertSuccesses - the number of successful asserts in this test group and all subgroups.
    • assertFailures - the number of failed asserts in this test group and all subgroups.
    • exceptions - the number of exceptions in this test group and all subgroups.
    • results - an array of already-formatted test results.
    • exceptionResults - an array of already-formatted exceptions.
    • nestingLevel is what level of test group this is. The top-level test is at level 0.
  • format.log(values)
    • values is an array of logged values

For documentation on how to write unit tests, see deadunit-core.

ExtendedUnitTest

This object extends UnitTest from deadunit-core. Also has the following methods:

test.string(<colorize>) - returns a future that resolves to a string containing formatted test results. See below for screenshots.

test.writeConsole(<hangingTimeout>) - writes colorized text output to the console. Returns a future that resolves when the console writing is complete. <hangingTimeout> is optional (default 100), and if non-zero, a warning will be displayed if the script doesn't exit before <hangingTimeout> number of milliseconds has passed. If zero, no warning happens. See below for screenshots.

test.html() - returns a string containing html-formatted test results. See below for screenshots.

test.results() - see deadunit-core

Screenshots

Passing tests are closed and failling tests are open by default. Clicking on the bars toggles sections open or closed.

Note about tests with asynchronous parts

Javascript (and node.js especially) has a lot of asynchronous parts. Deadunit allows your tests to run asychronously/concurrently, but you have to manage that concurrency.

I recommend that you use either:

• fibers/futures,
• or my own async-futures

Todo

• add the ability to stream test results to a browser
• make deadunit work on browsers (standalone)
• Once colors supports a safe mode (where it doesn't modify the String prototype), use that. Modifying builtins is dangerous.
• Also see the todos for deadunit-core

How to Contribute!

Anything helps:

• Creating issues (aka tickets/bugs/etc). Please feel free to use issues to report bugs, request features, and discuss changes.
• Updating the documentation: ie this readme file. Be bold! Help create amazing documentation!
• Submitting pull requests.

How to submit pull requests:

1. Please create an issue and get my input before spending too much time creating a feature. Work with me to ensure your feature or addition is optimal and fits with the purpose of the project.
2. Fork the repository
3. clone your forked repo onto your machine and run npm install at its root
4. If you're gonna work on multiple separate things, its best to create a separate branch for each of them
5. edit!
6. If it's a code change, please add to the unit tests (at test/testDeadunit.js) to verify that your change works
7. When you're done, run the unit tests and ensure they all pass
8. Commit and push your changes
9. Submit a pull request: https://help.github.com/articles/creating-a-pull-request

Change Log

• 2.0.1
  • added a note when a test times out
  • added the ability to warn if the script is hanging after test.writeConsole prints out the test
• 2.0.0 - Breaking Change
  • incorporating changes in deadunit-core 2.0.0
  • added test.results
  • test.writeConsole and test.html only return when the test is done (or times out)
  • test.writeConsole outputs test results as they happen in addition to outputting the final output
  • removed test.toString
  • test.string and test.html now return futures
• 1.0.7
  • Pretty printing logs other places objects are printed
  • html output
  • handling properties on exceptions

License

Released under the MIT license: http://opensource.org/licenses/MIT