xunit.TestCase(methodName)

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 repr 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, lib/base, enhances testing with a convenience function to run all TestCases present in module:xunit.testing.testCases. Similarly, this class provides a static method to register such classes.

new TestCase(methodName)
lib/xunit.js, line 502

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();

Classes

Error
module:xunit.TestCase~Error

Fail
module:xunit.TestCase~Fail

Skip
module:xunit.TestCase~Skip

Members

id :string
lib/xunit.js, line 585

typeTool :module:xunit.TypeTool
lib/xunit.js, line 591

Methods

addCleanup(func, …rest)
lib/xunit.js, line 649

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.

addEqualFunc(type, func)
lib/xunit.js, line 891

Parameters:
Name Type Description
type string

As returned from getType.
func module:xunit.TestCase~EqualFunc

Function to call to compare that type.

assertEqual(first, second, msgopt)
lib/xunit.js, line 688

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.

assertFalse(arg, msgopt)
lib/xunit.js, line 725

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.

assertNoRaises(func, msgopt)
lib/xunit.js, line 754

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.

assertNotEqual(first, second, msgopt)
lib/xunit.js, line 700

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.

assertRaises(exc, func, msgopt)
lib/xunit.js, line 741

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.

assertRaisesCause(exc, cause, func, msgopt)
lib/xunit.js, line 772

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.

assertRaisesRegExp(exc, regexp, func, msgopt)
lib/xunit.js, line 806

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.

assertRegExp(target, regexp, msgopt)
lib/xunit.js, line 832

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.

assertTrue(arg, msgopt)
lib/xunit.js, line 711

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.

doCleanups()
lib/xunit.js, line 654

Execute all functions registered with addCleanup.

equalArray(first, second) → {module:xunit.TestCase~EqualOutput}
lib/xunit.js, line 991

Parameters:
Name Type Description
first Array.<object>

First argument.
second Array.<object>

Second argument.
Returns:
module:xunit.TestCase~EqualOutput -

Results of testing equality.

Implements:

equalEqEqEq(first, second) → {module:xunit.TestCase~EqualOutput}
lib/xunit.js, line 903

Parameters:
Name Type Description
first object

First argument.
second object

Second argument.
Returns:
module:xunit.TestCase~EqualOutput -

Results of testing equality.

Implements:

equalMap(first, second) → {module:xunit.TestCase~EqualOutput}
lib/xunit.js, line 1041

Order is ignored.

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

First argument.
second Map.<object, object>

Second argument.
Returns:
module:xunit.TestCase~EqualOutput -

Results of testing equality.

Implements:

equalObject(first, second) → {module:xunit.TestCase~EqualOutput}
lib/xunit.js, line 977

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:
module:xunit.TestCase~EqualOutput -

Results of testing equality.

Implements:

equalRegExp(first, second) → {module:xunit.TestCase~EqualOutput}
lib/xunit.js, line 1149

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

Parameters:
Name Type Description
first object

First argument.
second object

Second argument.
Returns:
module:xunit.TestCase~EqualOutput -

Results of testing equality.

Implements:

equalSet(first, second) → {module:xunit.TestCase~EqualOutput}
lib/xunit.js, line 1102

Order is ignored.

Parameters:
Name Type Description
first Set.<object>

First argument.
second Set.<object>

Second argument.
Returns:
module:xunit.TestCase~EqualOutput -

Results of testing equality.

Implements:

equalString(first, second) → {module:xunit.TestCase~EqualOutput}
lib/xunit.js, line 939

Parameters:
Name Type Description
first object

First argument.
second object

Second argument.
Returns:
module:xunit.TestCase~EqualOutput -

Results of testing equality.

Implements:

equalValueOf(first, second) → {module:xunit.TestCase~EqualOutput}
lib/xunit.js, line 921

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

Parameters:
Name Type Description
first object

First argument.
second object

Second argument.
Returns:
module:xunit.TestCase~EqualOutput -

Results of testing equality.

Implements:

fail(msgopt)
lib/xunit.js, line 677

Immediately fail a test method.

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

Reason for the failure.
Throws:
module:xunit.TestCase~Fail

getEqualFunc(first, second) → {module:xunit.TestCase~EqualFunc}
lib/xunit.js, line 876

Find an equality function appropriate for the arguments.

Parameters:
Name Type Description
first object

First argument.
second object

Second argument.
Returns:
module:xunit.TestCase~EqualFunc -

Function that should be used to test equality.

repr(item) → {string}
lib/xunit.js, line 849

Parameters:
Name Type Description
item object

Anything.
Returns:
string -

String version of item.

Deprecated:
  • Migrate to this.typeTool.repr().

run(resultopt) → {module:xunit~TestResult}
lib/xunit.js, line 604

Execute the test method registered upon instantiation.

Parameters:
Name Type Attributes Description
result module:xunit~TestResult <optional>

Instance for accumulating results. Typically, a test runner will pass in one of these to gather results across multiple tests.
Returns:
module:xunit~TestResult -

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

setUp()
lib/xunit.js, line 639

Called once before each test method.

skip(msgopt)
lib/xunit.js, line 667

Immediately skips a test method.

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

Reason for skipping.
Throws:
module:xunit.TestCase~Skip

static addClassCleanup(func, …rest)
lib/xunit.js, line 572

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.

static doClassCleanups()
lib/xunit.js, line 577

Execute all functions registered with addClassCleanup.

static register()
lib/xunit.js, line 556

Register this class with the default test runner infrastructure.

static setUpClass()
lib/xunit.js, line 561

Called once before any instances are created.

Type Definitions

EqualFunc(first, second) → {module:xunit.TestCase~EqualOutput}
lib/xunit.js, line 860

Parameters:
Name Type Description
first object

First argument.
second object

Second argument.
Returns:
module:xunit.TestCase~EqualOutput -

Results of testing equality.

EqualOutput
lib/xunit.js, line 853

Properties:
Name Type Description
equal boolean

Result of equality test.
detail string

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