Assertions

Assertions are the life-blood of unit tests, and this is no different in xUnit.js. Common Assertions are provided via the static Assert class. Custom assertions can be created by throwing instances of xUnit.js.Model.AssertError([message]).

Borrowing again from the concepts of xUnit.net, xUnit.js prefers structured assertions to free-form messages. Messages are reserved for the most ambiguous assertions, Assert.Fail(reason), Assert.True(value,message), and Assert.False(value,message).

The following assertions are included by default:

Assert.AssignableFrom(expected,actual); Verifies that the instance or class specified by actual is a valid instance, interface, or sub-class of the function expected.

Assert.Contains(expected,actual); Verifies that the expected Object or Array contains the actual value. For objects, this represents the value of a key, for arrays, the value of an index position.

Assert.DoesNotContain(expected,actual); Verifies that the expected Object or Array does not contain the actual value. For objects, this represents the value of a key, for arrays, the value of an index position.

Assert.DoesNotThrow(actual); Verifies that the function delegate actual does not throw an Error of any sort.

Assert.Empty(actual); Verifies that actual is an empty Array, Function, Error, String, or Object. Booleans, Dates, and Numbers can never be considered "empty", and will always throw an Error. Arrays and Strings are considered empty when they have a length of zero. Errors are considered empty when they have no message. Functions are considered empty when they consist of only whitespace or comments. Objects are considered empty when they have no public properties.

Assert.Equal(expected,actual); Verifies that expected and actual are trivially equal. "Trivially equal" means that in the case of Booleans, Numbers, and Strings, the values are equivalent, but not necessarily the same reference; in the case of Arrays, Dates, Errors, and Objects, it means that the public properties or index positions are also trivially equal.

Assert.Fail(reason); Throws an xUnit.js.Model.AssertError, with an optional reason. 100% of the time, every time. That's it. No tricks. Keep this out of production code. In fact, the only reason to use this method is to verify that a piece of (test) code was never called.

Assert.False(actual,message); Verifies that actual evaluates to false. This is a strict evaluation, only Boolean values of false will pass. Typical falsey values, such as 0, '', null, undefined will throw an xUnit.js.Model.AssertError.

Assert.InRange(actual,low,high,comparer); Verifies that actual is greater than or equal to low, and less than or equal to high. If comparer is specified, verifies that comparer returns a value below or equal to zero when comparing low to actual and a value below or equal to zero when comparing actual to high.

Assert.NotEmpty(actual); Verifies that actual is not an empty Array, Function, Error, String, or Object. Booleans, Dates, and Numbers can never be considered "empty", and will always pass this test. Arrays and Strings are considered not empty when they have a length greater than zero. Errors are considered not empty when they have an error message. Functions are considered not empty when they consist of more than whitespace and comments. Objects are considered not empty when they have at least one public property.

Assert.NotEqual(expected,actual); Verifies that expected and actual are trivially note equal. "Trivially not equal" means that in the case of Booleans, Numbers, and Strings, the values are not equivalent, and not the same reference; in the case of Arrays, Dates, Errors, and Objects, it means that the public properties or index positions are also trivially not equal.

Assert.NotInRange(actual,low,high,comparer); Verifies that actual is less than low, or greater than high. If comparer is specified, verifies that comparer returns a value greater than zero when comparing low to actual and a value greater than zero when comparing actual to high.

Assert.NotNull(actual); Verifies that actual is not exactly equal to null.

Assert.NotSame(expected,actual); Verifies that expected and actual are not precisely equal. In the case of Booleans, Numbers, and Strings, this means value inequivalence. In the case of Arrays, Dates, Errors, Functions, and Objects, this means reference, or instance inequivalence.

Assert.NotType(expected,actual); Verifies that actual is not of the expected type. This means that the object actual is neither an instance of expected, nor a sub-class thereof.

Assert.NotUndefined(actual); Verifies that actual is not "undefined", as reported by the typeof keyword.

Assert.Null(actual); Verifies that actual is exactly equal to null.

Assert.Same(expected,actual); Verifies that expected and actual are precisely equal. In the case of Booleans, Numbers, and Strings, this means value equivalence. In the case of Arrays, Dates, Errors, Functions, and Objects, this means reference, or instance equivalence.

Assert.Throws(expected,actual); Verifies that the function delegate actual throws an Error of the expected type.

Assert.True(actual,message); Verifies that actual evaluates to true. This is a strict evaluation, only Boolean values of true will pass. Typical truthy values, such as 1, 'string', [], and {} will throw an xUnit.js.Model.AssertError.

Assert.Type(expected,actual); Verifies that actual is of the expected type. This means that the object actual is an instance of expected, or a sub-class thereof.

Assert.Undefined(actual); Verifies that actual is "undefined", as reported by the typeof keyword.