tsUnit
Choose a Version!
- If you need ES5 support, please use v2.0.10 view the README for v2.0.10
- v2.0.11 onwards is targeted at ES2015 and above and uses Promises
tsUnit is a unit testing framework for TypeScript, written in TypeScript. It allows you to encapsulate your test functions in classes and modules.
Install via NuGet:
PM> Install-Package tsUnit
Install via NPM
> npm i tsunit.external
NOTE: Version 2.0 has breaking changes, to improve re-use between different module systems. Please read the below to see how to use version 2.0.
tsUnit comes with...
-
Built-in assertion helpers
-
Built-in HTML or TAP output, or raw data
-
A test limiter that lets you click to re-play a test, or group of tests without re-running the whole suite (thanks to Paul Atryda)
-
An easy to use test-double generator
-
Support for async testing (Version >= 2.0.2)
Simple!
It is so easy, you don't even have to download and unzip anything. It is just one file, written in TypeScript... just add tsUnit.ts to your project.
Please start a discussion if you think a feature is missing or doesn't work as expected.
Example
Test modules look like this...
import * as tsUnit from './Scripts/tsUnit/tsUnit';
import * as Calculations from './Scripts/Calculations';
export class SimpleMathTests extends tsUnit.TestClass {
private target = new Calculations.SimpleMath();
addTwoNumbersWith1And2Expect3() {
var result = this.target.addTwoNumbers(1, 2);
this.areIdentical(3, result);
}
addTwoNumbersWith3And2Expect5() {
var result = this.target.addTwoNumbers(3, 2);
this.areIdentical(4, result); // Deliberate error
}
}Composing your test suite goes as follows...
import * as CalculationsTests from './Scripts/CalculationsTests';
// "The One Liner" - you can do this in multiple stages too
var test = new tsUnit.Test(CalculationsTests).run().showResults('results');The multi-line version is also available... in particular this is useful if you want to re-use the result (which you can display as HTML and retrieve TAP output from).
// Create the test suite
var test = new tsUnit.Test(CalculationsTests);
// Run the test
var result = test.run();
// Display in the element with id="results"
result.showResults('results');To run without a browser, you can call test.run() and use the raw result data yourself...
// Handle the results yourself...
var result = new tsUnit.Test(CalculationsTests).run();
var outcome = (result.errors.length === 0) ? 'Test Passed' : 'Test Failed';Or you can use the TAP (Test Anything Protocol) output:
// TAP output...
var tap = new tsUnit.Test(CalculationsTests).run().getTapResults();
console.log(tap);Async testing
To support async tests you must use the TestAsync class and it's test.runAsync() method.
import * as CalculationsTests from './Scripts/CalculationsTests';
// "The One Liner" - you can do this in multiple stages too
var test = new tsUnit.TestAsync(CalculationsTests).runAsync().then((result) => result.showResults('results'));Your test classes do not need to change unless you are writing an async test:
import * as tsUnit from './Scripts/tsUnit/tsUnit';
import * as CalculationsAsync from './Scripts/CalculationsAsync';
export class AsyncMathTests extends tsUnit.TestClass {
private target = new CalculationsAsync.SimpleMath();
addTwoNumbersAsynchronouslyWith1And2Expect3() {
var promise = this.target.addTwoNumbers(1, 2);
// return a promise:
return promise.then((result) => {
this.areIdentical(3, result);
});
}
}Note how the method from your CalculationsAsync module returns a promise
that has to be resolved before the result can be checked.
In order to allow the test runner to detect when your code is finished, your
test must be a chain of promises (using .then) and you must
return the last promise in that chain.
The use of the => operator allows us to access this -- if you use
functions here you must provide access to the this of your test class:
import * as tsUnit from './Scripts/tsUnit/tsUnit';
import * as CalculationsAsync from './Scripts/CalculationsAsync';
export class AsyncMathTests extends tsUnit.TestClass {
private target = new CalculationsAsync.SimpleMath();
addTwoNumbersAsynchronouslyWith1And2Expect3() {
var promise = this.target.addTwoNumbers(1, 2);
// save this:
var self = this;
return promise.then(function (result) {
self.areIdentical(3, result);
});
}
}Since your code is now asynchronous, you will also not be able to use
this.throws() to check that your code threw an exception. If you
want to check that your result is a rejected promise, use test
code like this:
import * as tsUnit from './Scripts/tsUnit/tsUnit';
import * as CalculationsAsync from './Scripts/CalculationsAsync';
export class AsyncMathTests extends tsUnit.TestClass {
private target = new CalculationsAsync.SimpleMath();
divideByZeroAsynchronouslyIsRejected() {
var promise = this.target.divide(1, 0);
// use both parameters of then, second is onRejected callback:
return p.then(() => {
this.fail("expected promise to be rejected, got success");
}, (err:Error) => {
this.areIdentical("division by zero", err.message);
})
}
}More options for async running
Since the one-liner gets a little bit out of hand, this is how a multiline version of the async runner looks.
// Create the test suite
var test = new tsUnit.TestAsync(CalculationsTests);
// Run the test
var promise = test.runAsync();
// await the result and show it
promise.then(function(result) {
// Display in the element with id="results"
result.showResults('results');
});To run without a browser, you can call test.runAsync() and use the raw result data yourself...
// Handle the results yourself...
var promise = new tsUnit.TestAsync(CalculationsTests).runAsync();
promise.then(function(result) {
var outcome = (result.errors.length === 0) ? 'Test Passed' : 'Test Failed';
});Or you can use the TAP (Test Anything Protocol) output:
// TAP output...
// Handle the results yourself...
var promise = new tsUnit.TestAsync(CalculationsTests).runAsync();
promise.then(function(result) {
var tap = result.getTapResults();
console.log(tap);
}Remember, since the tests are run asynchronously, the results can only be delivered asynchronously.
License
Copyright 2012-2016 Steve Fenton, async support was written by and is Copyright 2016 Harald Niesche
Please read the LICENSE file for more details.