1. Home
  2. Classes
  3. NexusHoratio.xunit.TestCase

new TestCase( methodName )

Description

An xUnit style test framework.

Many expected methods exist, such as setUp, setUpClass, addCleanup, addClassCleanup, etc. No tearDown methods, however; use addCleanup.

Assertion methods should always take a plain text string, typically named msg, as the last parameter. This string should be added to the assertion specific error message in case of a failure.

JavaScript does not have portable access to things like line numbers and stack traces (and in the case of userscripts, those may be inaccurate anyway). So it can be difficult to track down a particular test failure. The failure messages do include the name of the test class and test method, but, if the method happens to have several assertions in it, it may not be obvious which one failed. These extra descriptive messages can help with differentiation. This system will emit a debug message if any test method calls more than one assert method without a descriptive message.

While the assertEqual method will handle many cases by looking up special functions comparing by type. There may be times when what it can handle needs to be enhanced. There are currently two ways to make such enhancements.

First, the method addEqualFunc will allow the test method to register an additional function for comparing two identical instances.

Second, the property defaultEqual points to whatever equalX() function should be used if one cannot be found, or if instances differ by type. This fallback defaults to equalEqEqEq which uses the strict equality (===) operator. This can be explicitly set in the test method. The method equalValueOf will use the instance's valueOf method to get comparable values, and may be useful in such cases.

In many languages, order does not matter for some built-in container types (e.g., Map, Set). The JavaScript standard explicitly specifies that order DOES matter for these types. However, for this test library, the default equalX() methods explicitly IGNORE order.

Implementations for built-in types will be added as needed.

All assertX() and equalX() methods should use typeTool to turn values into strings for these error messages.

TestCases should run only one test method per instance. The name of the method is registered during instantiation and invoked by calling the run method. Generally, a system, like TestRunner is used to register a number of TestCases, discover the test methods, and invoke all of them in turn.

The sibling library, NexusHoratio.base, enhances NexusHoratio.xunit.testing with a convenience function to run all TestCases present in testCases. Similarly, this class provides a static method to register such classes.

Parameters
Name Type Description
methodName string

The method to run on this instantiation.
Examples
class FooTestCase extends TestCase {
			  testMethod() {
			    // Assemble
			    // Act
			
			    // Assert
			    this.assertEqual(actual, expected, 'extra message');
			  }
			}
			
			const test = new FooTestCase('testMethod');
			const result = test.run();
class BarTestCase extends TestCase {
			  testMethod() {
			    // Assemble
			    // Act
			
			    // Assert
			    this.assertEqual(actual, expected, 'extra message');
			  }
			
			  static { this.register(); }
			}
			
			testing.run();
Details

lib/xunit.js, line 522

Classes

new Error()

new Fail()

new Skip()

Members

defaultEqual :NexusHoratio.xunit.TestCase~EqualFunc

Description

Points to the current equalX() function.

Details
NexusHoratio.xunit.TestCase~EqualFunc

lib/xunit.js, line 609

id :string

Details
string

lib/xunit.js, line 612

typeTool :NexusHoratio.xunit.TypeTool

Details
NexusHoratio.xunit.TypeTool

lib/xunit.js, line 618

Methods

<static> register()

Description

Register this class with the default test runner infrastructure.

Details

lib/xunit.js, line 576

<static> setUpClass()

Description

Called once before any instances are created.

Details

lib/xunit.js, line 581

<static> addClassCleanup( func, ...rest )

Description

Register a function with arguments to run after all tests in the class have ran.

Parameters
Name Type Attributes Description
func function

Function to call.
rest object <repeatable>

Arbitrary arguments to func.
Details

lib/xunit.js, line 592

<static> doClassCleanups()

Description

Execute all functions registered with addClassCleanup.

Details

lib/xunit.js, line 597

run( [ result ] ) → {NexusHoratio.xunit~TestResult}

Description

Execute the test method registered upon instantiation.

Parameters
Name Type Attributes Description
result NexusHoratio.xunit~TestResult <optional>

Instance for accumulating results. Typically, a test runner will pass in one of these to gather results across multiple tests.
Returns

Accumulated results (one is created if not passed in).

Details

lib/xunit.js, line 631

setUp()

Description

Called once before each test method.

Details

lib/xunit.js, line 666

addCleanup( func, ...rest )

Description

Register a function with arguments to run after a test.

Parameters
Name Type Attributes Description
func function

Function to call.
rest object <repeatable>

Arbitrary arguments to func.
Details

lib/xunit.js, line 676

doCleanups()

Description

Execute all functions registered with addCleanup.

Details

lib/xunit.js, line 681

skip( [ msg ] )

Description

Immediately skips a test method.

Parameters
Name Type Attributes Default Description
msg string <optional>
 ''

Reason for skipping.
Throws
Details

lib/xunit.js, line 694

fail( [ msg ] )

Description

Immediately fail a test method.

Parameters
Name Type Attributes Default Description
msg string <optional>
 ''

Reason for the failure.
Throws
Details

lib/xunit.js, line 704

assertEqual( first, second [, msg ] )

Description

Asserts that two arguments are equal.

Parameters
Name Type Attributes Default Description
first object

First argument.
second object

Second argument.
msg string <optional>
 ''

Text to complement the failure message.
Details

lib/xunit.js, line 715

assertNotEqual( first, second [, msg ] )

Description

Asserts that two arguments are NOT equal.

Parameters
Name Type Attributes Default Description
first object

First argument.
second object

Second argument.
msg string <optional>
 ''

Text to complement the failure message.
Details

lib/xunit.js, line 727

assertTrue( arg [, msg ] )

Description

Asserts that the argument is a boolean true.

Parameters
Name Type Attributes Default Description
arg object

Argument to test.
msg string <optional>
 ''

Text to complement the failure message.
Details

lib/xunit.js, line 738

assertFalse( arg [, msg ] )

Description

Asserts that the argument is a boolean false.

Parameters
Name Type Attributes Default Description
arg object

Argument to test.
msg string <optional>
 ''

Text to complement the failure message.
Details

lib/xunit.js, line 752

assertRaises( exc, func [, msg ] )

Description

Asserts the expected exception is raised.

Parameters
Name Type Attributes Default Description
exc function

Expected Error class.
func function

Function to call.
msg string <optional>
 ''

Text to complement the failure message.
Details

lib/xunit.js, line 768

assertNoRaises( func [, msg ] )

Description

Asserts that no exception is raised.

Useful for supplying descriptive text when verifying an error does not occur.

Parameters
Name Type Attributes Default Description
func function

Function to call.
msg string <optional>
 ''

Text to complement the failure message.
Details

lib/xunit.js, line 781

assertRaisesCause( exc, cause, func [, msg ] )

Description

Asserts the expected exception is raised with matching cause.

Parameters
Name Type Attributes Default Description
exc function

Expected Error class.
cause object

Cause to match.
func function

Function to call.
msg string <optional>
 ''

Text to complement the failure message.
Details

lib/xunit.js, line 799

assertRaisesRegExp( exc, regexp, func [, msg ] )

Description

Asserts the expected exception is raised and the message matches the regular expression.

Parameters
Name Type Attributes Default Description
exc function

Expected Error class.
regexp RegExp

Regular expression to match.
func function

Function to call.
msg string <optional>
 ''

Text to complement the failure message.
Details

lib/xunit.js, line 833

assertRegExp( target, regexp [, msg ] )

Description

Asserts the target matches the regular expression.

Parameters
Name Type Attributes Default Description
target string

Target string to check.
regexp RegExp

Regular expression to match.
msg string <optional>
 ''

Text to complement the failure message.
Details

lib/xunit.js, line 859

repr( item ) → {string}

Parameters
Name Type Description
item object

Anything.
Returns

String version of item.

Details

<p>Migrate to NexusHoratio.xunit.TestCase#typeTool.repr.</p>

lib/xunit.js, line 877

getEqualFunc( first, second ) → {NexusHoratio.xunit.TestCase~EqualFunc}

Description

Find an equality function appropriate for the arguments.

Parameters
Name Type Description
first object

First argument.
second object

Second argument.
Returns

Function that should be used to test equality.

Details

lib/xunit.js, line 904

addEqualFunc( type, func )

Parameters
Name Type Description
type string

As returned from getType.
func NexusHoratio.xunit.TestCase~EqualFunc

Function to call to compare that type.
Details

lib/xunit.js, line 919

equalEqEqEq( first, second ) → {NexusHoratio.xunit.TestCase~EqualOutput}

Parameters
Name Type Description
first object

First argument.
second object

Second argument.
Returns

Results of testing equality.

Details

NexusHoratio.xunit.TestCase~EqualFunc

lib/xunit.js, line 931

equalValueOf( first, second ) → {NexusHoratio.xunit.TestCase~EqualOutput}

Description

For those cases when '===' is too strict.

Parameters
Name Type Description
first object

First argument.
second object

Second argument.
Returns

Results of testing equality.

Details

NexusHoratio.xunit.TestCase~EqualFunc

lib/xunit.js, line 949

equalString( first, second ) → {NexusHoratio.xunit.TestCase~EqualOutput}

Parameters
Name Type Description
first object

First argument.
second object

Second argument.
Returns

Results of testing equality.

Details

NexusHoratio.xunit.TestCase~EqualFunc

lib/xunit.js, line 967

equalObject( first, second ) → {NexusHoratio.xunit.TestCase~EqualOutput}

Description

This currently only tests Object.entries().

Order is ignored.

Other tests, like frozen and sealed states may be implemented later.

Parameters
Name Type Description
first object

First argument.
second object

Second argument.
Returns

Results of testing equality.

Details

NexusHoratio.xunit.TestCase~EqualFunc

lib/xunit.js, line 1005

equalArray( first, second ) → {NexusHoratio.xunit.TestCase~EqualOutput}

Parameters
Name Type Description
first Array.<object>

First argument.
second Array.<object>

Second argument.
Returns

Results of testing equality.

Details

NexusHoratio.xunit.TestCase~EqualFunc

lib/xunit.js, line 1019

equalMap( first, second ) → {NexusHoratio.xunit.TestCase~EqualOutput}

Description

Order is ignored.

Parameters
Name Type Description
first Map.<object, object>

First argument.
second Map.<object, object>

Second argument.
Returns

Results of testing equality.

Details

NexusHoratio.xunit.TestCase~EqualFunc

lib/xunit.js, line 1069

equalSet( first, second ) → {NexusHoratio.xunit.TestCase~EqualOutput}

Description

Order is ignored.

Parameters
Name Type Description
first Set.<object>

First argument.
second Set.<object>

Second argument.
Returns

Results of testing equality.

Details

NexusHoratio.xunit.TestCase~EqualFunc

lib/xunit.js, line 1130

equalRegExp( first, second ) → {NexusHoratio.xunit.TestCase~EqualOutput}

Description

This converts to strings for comparisons as that encodes all flags.

Parameters
Name Type Description
first object

First argument.
second object

Second argument.
Returns

Results of testing equality.

Details

NexusHoratio.xunit.TestCase~EqualFunc

lib/xunit.js, line 1177

<private> countAsserts( msg )

Description

Count how many asserts are called per test method.

Each assertX() method should call this first this along with its optional msg parameter.

Parameters
Name Type Description
msg string

The message the assert method was given.
Details

lib/xunit.js, line 1202

<private> assertBase( first, second, expected [, msg ] )

Description

Asserts that two arguments have the expected equality

Parameters
Name Type Attributes Default Description
first object

First argument.
second object

Second argument.
expected boolean

Expectation of equality.
msg string <optional>
 ''

Text to complement the failure message.
Details

lib/xunit.js, line 1233

<private> normalizeContainer( container ) → {Map.<object, object>|Set.<object>}

Description

Turn all keys and values in a container into a string via repr().

Containers must meet the following criteria:

  • Have an entries() method that returns [key, value] pairs.
  • Have at least one of set(key, value) or add(value) method.
  • Support a constructor taking own type that results in a copy.
Parameters
Name Type Description
container Map.<object, object> | Set.<object>

Or any type with similar signatures.
Returns

Clone of container with all keys and values transformed into a string.

Details

lib/xunit.js, line 1263

<private> failMsgs( ...messages )

Description

Immediately fail while combining messages.

Parameters
Name Type Attributes Description
messages string <repeatable>

Messages to join.
Details

lib/xunit.js, line 1286

Type Definitions

EqualOutput

Properties
Name Type Description
equal boolean

Result of equality test.
detail string

Details appropriate to the test (e.g., where items differed).
Details
object

lib/xunit.js, line 881

EqualFunc( first, second ) → {NexusHoratio.xunit.TestCase~EqualOutput}

Parameters
Name Type Description
first object

First argument.
second object

Second argument.
Returns

Results of testing equality.

Details
function

lib/xunit.js, line 888