Assert module

For XPCShell tests and mochitests, Assert is already present as an instantiated global to which you can refer - you don’t need to construct it yourself. You can immediately start using Assert.ok and similar methods as test assertions.

The full class documentation follows, but it is perhaps worth noting that this API is largely identical to NodeJS’ assert module, with some omissions/changes including strict mode and string matching.

class Assert(reporterFunc, isDefault)

This module is based on the CommonJS spec

When you see a jsdoc comment that contains a number, it’s a reference to a specific section of the CommonJS spec.

1. The assert module provides functions that throw AssertionError’s when particular conditions are not met.

To use the module you may instantiate it first.

Arguments:

  • reporterFunc (reporterFunc) – Allows consumers to override reporting for this instance.

  • isDefault (boolean) – Used by test suites to set reporterFunc as the default used by the global instance, which is called for example by other test-only modules. This is false when the reporter is set by content scripts, because they may still run in the parent process.

Assert.ok(value, message)

4. Pure assertion tests whether a value is truthy, as determined by !!guard. assert.ok(guard, message_opt); This statement is equivalent to assert.equal(true, !!guard, message_opt);. To test strictly for the value true, use assert.strictEqual(true, guard, message_opt);.

Arguments:

  • value (*) – Test subject to be evaluated as truthy.

  • message (String) – Short explanation of the expected result.

Assert.equal(actual, expected, message)

5. The equality assertion tests shallow, coercive equality with ==. assert.equal(actual, expected, message_opt);

Arguments:

  • actual (*) – Test subject to be evaluated as equivalent to expected.

  • expected (*) – Test reference to evaluate against actual.

  • message (String) – Short explanation of the expected result.

Assert.notEqual(actual, expected, message)

6. The non-equality assertion tests for whether two objects are not equal with !=

Arguments:

  • actual (*) – Test subject to be evaluated as NOT equivalent to expected.

  • expected (*) – Test reference to evaluate against actual.

  • message (String) – Short explanation of the expected result.

Examples:

assert.notEqual(actual, expected, message_opt);
Assert.strictEqual(actual, expected, message)

9. The strict equality assertion tests strict equality, as determined by ===. assert.strictEqual(actual, expected, message_opt);

Arguments:

  • actual (*) – Test subject to be evaluated as strictly equivalent to expected.

  • expected (*) – Test reference to evaluate against actual.

  • message (String) – Short explanation of the expected result.

Assert.notStrictEqual(actual, expected, message)

10. The strict non-equality assertion tests for strict inequality, as determined by !==. assert.notStrictEqual(actual, expected, message_opt);

Arguments:

  • actual (*) – Test subject to be evaluated as NOT strictly equivalent to expected.

  • expected (*) – Test reference to evaluate against actual.

  • message (String) – Short explanation of the expected result.

Assert.deepEqual(actual, expected, message)

7. The equivalence assertion tests a deep equality relation. assert.deepEqual(actual, expected, message_opt);

We check using the most exact approximation of equality between two objects to keep the chance of false positives to a minimum. JSON.stringify is not designed to be used for this purpose; objects may have ambiguous toJSON() implementations that would influence the test.

Arguments:

  • actual (*) – Test subject to be evaluated as equivalent to expected, including nested properties.

  • expected (*) – Test reference to evaluate against actual.

  • message (String) – Short explanation of the expected result.

Assert.notDeepEqual(actual, expected, message)

8. The non-equivalence assertion tests for any deep inequality. assert.notDeepEqual(actual, expected, message_opt);

Arguments:

  • actual (*) – Test subject to be evaluated as NOT equivalent to expected, including nested properties.

  • expected (*) – Test reference to evaluate against actual.

  • message (String) – Short explanation of the expected result.

Assert.greater(lhs, rhs, message)

The lhs must be greater than the rhs. assert.greater(lhs, rhs, message_opt);

Arguments:

  • lhs (Number) – The left-hand side value.

  • rhs (Number) – The right-hand side value.

  • message (String) – Short explanation of the comparison result.

Assert.less(lhs, rhs, message)

The lhs must be less than the rhs. assert.less(lhs, rhs, message_opt);

Arguments:

  • lhs (Number) – The left-hand side value.

  • rhs (Number) – The right-hand side value.

  • message (String) – Short explanation of the comparison result.

Assert.greaterOrEqual(lhs, rhs, message)

The lhs must be greater than or equal to the rhs. assert.greaterOrEqual(lhs, rhs, message_opt);

Arguments:

  • lhs (Number) – The left-hand side value.

  • rhs (Number) – The right-hand side value.

  • message (String) – Short explanation of the comparison result.

Assert.lessOrEqual(lhs, rhs, message)

The lhs must be less than or equal to the rhs. assert.lessOrEqual(lhs, rhs, message_opt);

Arguments:

  • lhs (Number) – The left-hand side value.

  • rhs (Number) – The right-hand side value.

  • message (String) – Short explanation of the comparison result.

Assert.stringContains(lhs, rhs, message)

The lhs must be a string that contains the rhs string.

Arguments:

  • lhs (String) – The string to be tested (haystack).

  • rhs (String) – The string to be found (needle).

  • message (String) – Short explanation of the expected result.

Assert.stringMatches(lhs, rhs, message)

The lhs must be a string that matches the rhs regular expression. rhs can be specified either as a string or a RegExp object. If specified as a string it will be interpreted as a regular expression so take care to escape special characters such as “?” or “(” if you need the actual characters.

Arguments:

  • lhs (String) – The string to be tested.

  • rhs (String|RegExp) – The regular expression that the string will be tested with. Note that if passed as a string, this will be interpreted. as a regular expression.

  • message (String) – Short explanation of the comparison result.

Assert.throws(block, expected, message)

11. Expected to throw an error: assert.throws(block, Error_opt, message_opt);

Example: `js // The following will verify that an error of type TypeError was thrown: Assert.throws(() => testBody(), TypeError); // The following will verify that an error was thrown with an error message matching "hello": Assert.throws(() => testBody(), /hello/); `

Arguments:

  • block (function) – Function to evaluate and catch eventual thrown errors.

  • expected (RegExp|function) – This parameter can be either a RegExp or a function. The function is either the error type’s constructor, or it’s a method that returns a boolean that describes the test outcome.

  • message (String) – Short explanation of the expected result.

Assert.rejects(promise, expected, message)

A promise that is expected to reject: assert.rejects(promise, expected, message);

Arguments:

  • promise (Promise) – A promise that is expected to reject.

  • expected (?) – Test reference to evaluate against the rejection result.

  • message (String) – Short explanation of the expected result.

Assert.report(failed, actual, expected, message, operator, truncate=true, stack)

3. All of the following functions must throw an AssertionError when a corresponding condition is not met, with a message that may be undefined if not provided. All assertion methods provide both the actual and expected values to the assertion error for display purposes.

This report method only throws errors on assertion failures, as per spec, but consumers of this module (think: xpcshell-test, mochitest) may want to override this default implementation.

Arguments:

  • failed (boolean) – Indicates if the assertion failed or not.

  • actual (*) – The result of evaluating the assertion.

  • expected (*) – Expected result from the test author.

  • message (String) – Short explanation of the expected result.

  • operator (String) – Operation qualifier used by the assertion method (ex: ‘==’).

  • truncate (boolean) – Whether or not actual and expected should be truncated when printing.

  • stack (nsIStackFrame) – The stack trace including the caller of the assertion method, if this cannot be inferred automatically (e.g. due to async callbacks).

Examples:

// The following will report an assertion failure.
this.report(1 != 2, 1, 2, "testing JS number math!", "==");
Assert.setReporter(reporterFunc)

Set a custom assertion report handler function.

Arguments:

  • reporterFunc (reporterFunc) – Report handler function.

Examples:

Assert.setReporter(function customReporter(err, message, stack) {
  if (err) {
    do_report_result(false, err.message, err.stack);
  } else {
    do_report_result(true, message, stack);
  }
});
static Assert.AssertionError(options)

  1. The AssertionError is defined in assert.

At present only the four keys mentioned below are used and understood by the spec. Implementations or sub modules can pass other keys to the AssertionError’s constructor - they will be ignored.

Examples:

new assert.AssertionError({
  message: message,
  actual: actual,
  expected: expected,
  operator: operator,
  truncate: truncate,
  stack: stack, // Optional, defaults to the current stack.
});