--- title: Assert.jsm slug: Mozilla/JavaScript_code_modules/Assert.jsm translation_of: Mozilla/JavaScript_code_modules/Assert.jsm ---

{{ gecko_minversion_header("31") }}

The Assert.jsm JavaScript code module implements the CommonJS Unit Testing specification version 1.1, which provides a basic, standardized interface for performing in-code logical assertions with optional, customizable error reporting. To use it, you first need to import the code module into your JavaScript scope:

Components.utils.import("resource://testing-common/Assert.jsm");

Assert 类提供了执行常见逻辑断言的方法。

Method overview

undefined ok(value, message);
undefined equal(actual, expected, message);
undefined notEqual(actual, expected, message);
undefined deepEqual(actual, expected, message);
undefined notDeepEqual(actual, expected, message);
undefined strictEqual(actual, expected, message);
undefined notStrictEqual(actual, expected, message);
undefined throws(block, expected, message);
Promise rejects(promise, expected, message);
undefined greater(lhs, rhs, message);
undefined greaterOrEqual(lhs, rhs, message);
undefined less(lhs, rhs, message);
undefined lessOrEqual(lhs, rhs, message);
undefined setReporter(reporterFunc);
undefined report(failed, actual, expected, message, operator);

Constructor

Creates a new Assert object.

let assert = new Assert(reporterFunc);

The new Assert instance, assert, uses reporterFunc to report assertion results or throws an AssertionError when an assertion fails, as default behavior.

ok, equal, notEqual, deepEqual, notDeepEqual, strictEqual, notStrictEqual, throws, setReporter, report

Methods

ok()

Pure assertion tests whether a value is truthy, as determined by !!guard.
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);.

undefined ok(
  actual,
  message
);
Parameters
actual
Test subject to be evaluated as truthy
message
Short explanation of the expected result

equal()

The equality assertion tests shallow, coercive equality with ==.

undefined equal(
  actual,
  expected,
  message
);
Parameters
actual
Test subject to be evaluated as equivalent to expected
expected
Test reference to evaluate against actual
message
Short explanation of the expected result

notEqual()

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

undefined notEqual(
  actual,
  expected,
  message
);
Parameters
actual
Test subject to be evaluated as not equivalent to expected
expected
Test reference to evaluate against actual
message
Short explanation of the expected result

deepEqual()

The equivalence assertion tests a deep equality relation.
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.

undefined deepEqual(
  actual,
  expected,
  message
);
Parameters
actual
Test subject to be evaluated as equivalent to expected, including nested properties
expected
Test reference to evaluate against actual
message
Short explanation of the expected result

notDeepEqual()

The non-equivalence assertion tests for any deep inequality.

undefined notDeepEqual(
  actual,
  expected,
  message
);
Parameters
actual
Test subject to be evaluated as not equivalent to expected, including nested properties
expected
Test reference to evaluate against actual
message
Short explanation of the expected result

strictEqual()

The strict equality assertion tests strict equality, as determined by ===.

undefined strictEqual(
  actual,
  expected,
  message
);
Parameters
actual
Test subject to be evaluated as strictly equivalent to expected
expected
Test reference to evaluate against actual
message
Short explanation of the expected result

notStrictEqual()

The strict non-equality assertion tests for strict inequality, as determined by !==.

undefined notStrictEqual(
  actual,
  expected,
  message
);
Parameters
actual
Test subject to be evaluated as not strictly equivalent to expected
expected
Test reference to evaluate against actual
message
Short explanation of the expected result

throws()

Expected to throw an error.

undefined throws(
  block,
  expected,
  message
);
Parameters
block
Function block to evaluate and catch eventual thrown errors
expected
Test reference to evaluate against the thrown result from block
message
Short explanation of the expected result

rejects()

Expected to reject a promise. Returns a Promise that resolves when the promise either resolves or rejects.

Promise rejects(
  promise,
  expected,
  message
);
Parameters
promise
Promise promise to wait for rejection and catch eventual thrown errors
expected
Test reference to evaluate against the thrown result from block
message
Short explanation of the expected result

greater()

The greater than assertion tests two numbers with the > operator.

undefined greater(
  lhs,
  rhs,
  message
);
Parameters
lhs
The left hand side of the operator
rhs
The right hand side of the operator
message
Short explanation of the expected result

greaterOrEqual()

The greater or equal than assertion tests two numbers with the >= operator.

undefined greaterOrEqual(
  lhs,
  rhs,
  message
);
Parameters
lhs
The left hand side of the operator
rhs
The right hand side of the operator
message
Short explanation of the expected result

less()

The lesser than assertion tests two numbers with the < operator.

undefined less(
  lhs,
  rhs,
  message
);
Parameters
lhs
The left hand side of the operator
rhs
The right hand side of the operator
message
Short explanation of the expected result

lessOrEqual()

The lesser or equal than assertion tests two numbers with the <= operator.

undefined lessOrEqual(
  lhs,
  rhs,
  message
);
Parameters
lhs
The left hand side of the operator
rhs
The right hand side of the operator
message
Short explanation of the expected result

setReporter()

Set a custom assertion report handler function.

undefined setReporter(
  reporterFunc
);
Parameters
reporterFunc
Reporter handler function.
Arguments passed in to this function are:
err
An error object when the assertion failed or null when it passed
message
Message describing the assertion
stack
Stack trace of the assertion function.

report()

All of the aforementioned 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.

undefined report(
  failed,
  actual,
  expected,
  message,
  operator
);
Parameters
failed
Indicates if the assertion failed or not
actual
The result of evaluating the assertion
expected
Expected result from the test author
message
Short explanation of the expected result
operator
Operation qualifier used by the assertion method (ex: '==')

Examples

Custom reporter example

Components.utils.import("resource://testing-common/Assert.jsm");

let assert = new Assert();

assert.setReporter(function customReporter(err, message, stack) {
  if (err) {
    do_report_result(false, err.message, err.stack);
  } else {
    do_report_result(true, message, stack);
  }
});

See also