Assert.jsm 编辑

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

The Assert class offers methods for performing common logical assertions.

Method overview

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

• Using JavaScript code modules
• JavaScript code modules
• Components.utils.import
• Browser Chrome tests
• Writing xpcshell-based unit tests