path: root/files/zh-cn/mozilla/javascript_code_modules/assert.jsm/index.html

---
title: Assert.jsm
slug: Mozilla/JavaScript_code_modules/Assert.jsm
translation_of: Mozilla/JavaScript_code_modules/Assert.jsm
---
<p>{{ gecko_minversion_header("31") }}</p>

<p>The <code>Assert.jsm</code> JavaScript code module implements the <a href="http://wiki.commonjs.org/wiki/Unit_Testing/1.1" title="http://wiki.commonjs.org/wiki/Unit_Testing/1.1">CommonJS Unit Testing specification version 1.1</a>, 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:</p>

<pre class="brush: js">Components.utils.import("resource://testing-common/Assert.jsm");
</pre>

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

<h2 id="Method_overview">Method overview</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <td><code><a href="/en-US/JavaScript/Reference/Global_Objects/undefined" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/undefined">undefined</a> <a href="#ok()" title="en/JavaScript code modules/Assert.jsm#ok()">ok</a>(value, message);</code></td>
  </tr>
  <tr>
   <td><code><a href="/en-US/JavaScript/Reference/Global_Objects/undefined" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/undefined">undefined</a> <a href="#equal()" title="en/JavaScript code modules/Assert.jsm#equal()">equal</a>(actual, expected, message);</code></td>
  </tr>
  <tr>
   <td><code><a href="/en-US/JavaScript/Reference/Global_Objects/undefined" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/undefined">undefined</a> <a href="#notEqual()" title="en/JavaScript code modules/Assert.jsm#notEqual()">notEqual</a>(actual, expected, message);</code></td>
  </tr>
  <tr>
   <td><code><a href="/en-US/JavaScript/Reference/Global_Objects/undefined" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/undefined">undefined</a> <a href="#deepEqual()" title="en/JavaScript code modules/Assert.jsm#deepEqual()">deepEqual</a>(actual, expected, message);</code></td>
  </tr>
  <tr>
   <td><code><a href="/en-US/JavaScript/Reference/Global_Objects/undefined" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/undefined">undefined</a> <a href="#notDeepEqual()" title="en/JavaScript code modules/Assert.jsm#notDeepEqual()">notDeepEqual</a>(actual, expected, message);</code></td>
  </tr>
  <tr>
   <td><code><a href="/en-US/JavaScript/Reference/Global_Objects/undefined" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/undefined">undefined</a> <a href="#strictEqual()" title="en/JavaScript code modules/Assert.jsm#strictEqual()">strictEqual</a>(actual, expected, message);</code></td>
  </tr>
  <tr>
   <td><code><a href="/en-US/JavaScript/Reference/Global_Objects/undefined" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/undefined">undefined</a> <a href="#notStrictEqual()" title="en/JavaScript code modules/Assert.jsm#notStrictEqual()">notStrictEqual</a>(actual, expected, message);</code></td>
  </tr>
  <tr>
   <td><code><a href="/en-US/JavaScript/Reference/Global_Objects/undefined" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/undefined">undefined</a> <a href="#throws()" title="en/JavaScript code modules/Assert.jsm#throws()">throws</a>(block, expected, message);</code></td>
  </tr>
  <tr>
   <td><code><a href="/en/Web/JavaScript/Reference/Global_Objects/Promise" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/undefined">Promise</a> <a href="#rejects()" title="en/JavaScript code modules/Assert.jsm#rejects()">rejects</a>(promise, expected, message);</code></td>
  </tr>
  <tr>
   <td><code><a href="/en-US/JavaScript/Reference/Global_Objects/undefined" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/undefined">undefined</a> <a href="#greater()" title="en/JavaScript code modules/Assert.jsm#greater()">greater</a>(lhs, rhs, message);</code></td>
  </tr>
  <tr>
   <td><code><a href="/en-US/JavaScript/Reference/Global_Objects/undefined" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/undefined">undefined</a> <a href="#greaterOrEqual()" title="en/JavaScript code modules/Assert.jsm#greaterOrEqual()">greaterOrEqual</a>(lhs, rhs, message);</code></td>
  </tr>
  <tr>
   <td><code><a href="/en-US/JavaScript/Reference/Global_Objects/undefined" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/undefined">undefined</a> <a href="#less()" title="en/JavaScript code modules/Assert.jsm#less()">less</a>(lhs, rhs, message);</code></td>
  </tr>
  <tr>
   <td><code><a href="/en-US/JavaScript/Reference/Global_Objects/undefined" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/undefined">undefined</a> <a href="#lessOrEqual()" title="en/JavaScript code modules/Assert.jsm#lessOrEqual()">lessOrEqual</a>(lhs, rhs, message);</code></td>
  </tr>
  <tr>
   <td><code><a href="/en-US/JavaScript/Reference/Global_Objects/undefined" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/undefined">undefined</a> <a href="#setReporter()" title="en/JavaScript code modules/Assert.jsm#setReporter()">setReporter</a>(reporterFunc);</code></td>
  </tr>
  <tr>
   <td><code><a href="/en-US/JavaScript/Reference/Global_Objects/undefined" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/undefined">undefined</a> <a href="#report()" title="en/JavaScript code modules/Assert.jsm#report()">report</a>(failed, actual, expected, message, operator);</code></td>
  </tr>
 </tbody>
</table>

<h2 id="Constructor">Constructor</h2>

<p>Creates a new <code>Assert</code> object.</p>

<pre>let assert = new Assert(reporterFunc);
</pre>

<p>The new Assert instance, <code>assert</code>, uses <code>reporterFunc</code> to <a href="/en/JavaScript_code_modules/Assert.jsm#report()" title="en/JavaScript code modules/Assert.jsm#report()">report</a> assertion results or throws an <a href="/en/JavaScript_code_modules/Assert.jsm#AssertionError" title="en/JavaScript code modules/Assert.jsm#AssertionError">AssertionError</a> when an assertion fails, as default behavior.</p>

<p>ok, equal, notEqual, deepEqual, notDeepEqual, strictEqual, notStrictEqual, throws, setReporter, report</p>

<h2 id="Methods">Methods</h2>

<h3 id="ok()">ok()</h3>

<p>Pure assertion tests whether a value is truthy, as determined by !!guard.<br>
 This statement is equivalent to <code>assert.<a href="/en/JavaScript_code_modules/Assert.jsm#equal()" title="en/JavaScript code modules/Assert.jsm#equal()">equal</a>(true, !!guard, message_opt);</code>. To test strictly for the value true, use <code>assert.<a href="/en/JavaScript_code_modules/Assert.jsm#strictEqual()" title="en/JavaScript code modules/Assert.jsm#strictEqual()">strictEqual</a>(true, guard, message_opt);</code>.</p>

<pre>undefined ok(
  actual,
  message
);
</pre>

<h6 id="Parameters">Parameters</h6>

<dl>
 <dt><code>actual</code></dt>
 <dd>Test subject to be evaluated as truthy</dd>
 <dt><code>message</code></dt>
 <dd>Short explanation of the expected result</dd>
</dl>

<h3 id="equal()">equal()</h3>

<p>The equality assertion tests shallow, coercive equality with ==.</p>

<pre>undefined equal(
  actual,
  expected,
  message
);
</pre>

<h6 id="Parameters_2">Parameters</h6>

<dl>
 <dt><code>actual</code></dt>
 <dd>Test subject to be evaluated as equivalent to <code>expected</code></dd>
 <dt><code>expected</code></dt>
 <dd>Test reference to evaluate against <code>actual</code></dd>
 <dt><code>message</code></dt>
 <dd>Short explanation of the expected result</dd>
</dl>

<h3 id="notEqual()">notEqual()</h3>

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

<pre>undefined notEqual(
  actual,
  expected,
  message
);
</pre>

<h6 id="Parameters_3">Parameters</h6>

<dl>
 <dt><code>actual</code></dt>
 <dd>Test subject to be evaluated as <strong>not</strong> equivalent to <code>expected</code></dd>
 <dt><code>expected</code></dt>
 <dd>Test reference to evaluate against <code>actual</code></dd>
 <dt><code>message</code></dt>
 <dd>Short explanation of the expected result</dd>
</dl>

<h3 id="deepEqual()">deepEqual()</h3>

<p>The equivalence assertion tests a deep equality relation.<br>
 We check using the most exact approximation of equality between two objects to keep the chance of false positives to a minimum.<br>
 <code>JSON.stringify</code> is not designed to be used for this purpose; objects may have ambiguous <code>toJSON()</code> implementations that would influence the test.</p>

<pre>undefined deepEqual(
  actual,
  expected,
  message
);
</pre>

<h6 id="Parameters_4">Parameters</h6>

<dl>
 <dt><code>actual</code></dt>
 <dd>Test subject to be evaluated as equivalent to <code>expected</code>, including nested properties</dd>
 <dt><code>expected</code></dt>
 <dd>Test reference to evaluate against <code>actual</code></dd>
 <dt><code>message</code></dt>
 <dd>Short explanation of the expected result</dd>
</dl>

<h3 id="notDeepEqual()">notDeepEqual()</h3>

<p>The non-equivalence assertion tests for any deep inequality.</p>

<pre>undefined notDeepEqual(
  actual,
  expected,
  message
);
</pre>

<h6 id="Parameters_5">Parameters</h6>

<dl>
 <dt><code>actual</code></dt>
 <dd>Test subject to be evaluated as <strong>not</strong> equivalent to <code>expected</code>, including nested properties</dd>
 <dt><code>expected</code></dt>
 <dd>Test reference to evaluate against <code>actual</code></dd>
 <dt><code>message</code></dt>
 <dd>Short explanation of the expected result</dd>
</dl>

<h3 id="strictEqual()">strictEqual()</h3>

<p>The strict equality assertion tests strict equality, as determined by ===.</p>

<pre>undefined strictEqual(
  actual,
  expected,
  message
);
</pre>

<h6 id="Parameters_6">Parameters</h6>

<dl>
 <dt><code>actual</code></dt>
 <dd>Test subject to be evaluated as strictly equivalent to <code>expected</code></dd>
 <dt><code>expected</code></dt>
 <dd>Test reference to evaluate against <code>actual</code></dd>
 <dt><code>message</code></dt>
 <dd>Short explanation of the expected result</dd>
</dl>

<h3 id="notStrictEqual()">notStrictEqual()</h3>

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

<pre>undefined notStrictEqual(
  actual,
  expected,
  message
);
</pre>

<h6 id="Parameters_7">Parameters</h6>

<dl>
 <dt><code>actual</code></dt>
 <dd>Test subject to be evaluated as <strong>not</strong> strictly equivalent to <code>expected</code></dd>
 <dt><code>expected</code></dt>
 <dd>Test reference to evaluate against <code>actual</code></dd>
 <dt><code>message</code></dt>
 <dd>Short explanation of the expected result</dd>
</dl>

<h3 id="throws()">throws()</h3>

<p>Expected to throw an error.</p>

<pre>undefined throws(
  block,
  expected,
  message
);
</pre>

<h6 id="Parameters_8">Parameters</h6>

<dl>
 <dt><code>block</code></dt>
 <dd><a href="/en/JavaScript/Reference/Global_Objects/Function" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function">Function</a> block to evaluate and catch eventual thrown errors</dd>
 <dt><code>expected</code></dt>
 <dd>Test reference to evaluate against the thrown result from <code>block</code></dd>
 <dt><code>message</code></dt>
 <dd>Short explanation of the expected result</dd>
</dl>

<h3 id="rejects()">rejects()</h3>

<p>Expected to reject a promise. Returns a <a href="/en/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a> that resolves when the promise either resolves or rejects.</p>

<pre>Promise rejects(
  promise,
  expected,
  message
);
</pre>

<h6 id="Parameters_9">Parameters</h6>

<dl>
 <dt><code>promise</code></dt>
 <dd><a href="/en/Web/JavaScript/Reference/Global_Objects/Promise" title="https://developer.mozilla.org/en/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a> promise to wait for rejection and catch eventual thrown errors</dd>
 <dt><code>expected</code></dt>
 <dd>Test reference to evaluate against the thrown result from <code>block</code></dd>
 <dt><code>message</code></dt>
 <dd>Short explanation of the expected result</dd>
</dl>

<h3 id="greater()">greater()</h3>

<p>The greater than assertion tests two numbers with the &gt; operator.</p>

<pre>undefined greater(
  lhs,
  rhs,
  message
);
</pre>

<h6 id="Parameters_10">Parameters</h6>

<dl>
 <dt><code>lhs</code></dt>
 <dd>The left hand side of the operator</dd>
 <dt><code>rhs</code></dt>
 <dd>The right hand side of the operator</dd>
 <dt><code>message</code></dt>
 <dd>Short explanation of the expected result</dd>
</dl>

<h3 id="greaterOrEqual()">greaterOrEqual()</h3>

<p>The greater or equal than assertion tests two numbers with the &gt;= operator.</p>

<pre>undefined greaterOrEqual(
  lhs,
  rhs,
  message
);
</pre>

<h6 id="Parameters_11">Parameters</h6>

<dl>
 <dt><code>lhs</code></dt>
 <dd>The left hand side of the operator</dd>
 <dt><code>rhs</code></dt>
 <dd>The right hand side of the operator</dd>
 <dt><code>message</code></dt>
 <dd>Short explanation of the expected result</dd>
</dl>

<h3 id="less()">less()</h3>

<p>The lesser than assertion tests two numbers with the &lt; operator.</p>

<pre>undefined less(
  lhs,
  rhs,
  message
);
</pre>

<h6 id="Parameters_12">Parameters</h6>

<dl>
 <dt><code>lhs</code></dt>
 <dd>The left hand side of the operator</dd>
 <dt><code>rhs</code></dt>
 <dd>The right hand side of the operator</dd>
 <dt><code>message</code></dt>
 <dd>Short explanation of the expected result</dd>
</dl>

<h3 id="lessOrEqual()">lessOrEqual()</h3>

<p>The lesser or equal than assertion tests two numbers with the &lt;= operator.</p>

<pre>undefined lessOrEqual(
  lhs,
  rhs,
  message
);
</pre>

<h6 id="Parameters_13">Parameters</h6>

<dl>
 <dt><code>lhs</code></dt>
 <dd>The left hand side of the operator</dd>
 <dt><code>rhs</code></dt>
 <dd>The right hand side of the operator</dd>
 <dt><code>message</code></dt>
 <dd>Short explanation of the expected result</dd>
</dl>

<h3 id="setReporter()">setReporter()</h3>

<p>Set a custom assertion report handler function.</p>

<pre>undefined setReporter(
  reporterFunc
);
</pre>

<h6 id="Parameters_14">Parameters</h6>

<dl>
 <dt><code>reporterFunc</code></dt>
 <dd>Reporter handler <a href="/en/JavaScript/Reference/Global_Objects/Function" title="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function">function</a>.<br>
 Arguments passed in to this function are:
 <dl>
  <dt><code>err</code></dt>
  <dd>An error object when the assertion failed or null when it passed</dd>
  <dt><code>message</code></dt>
  <dd>Message describing the assertion</dd>
  <dt><code>stack</code></dt>
  <dd>Stack trace of the assertion function.</dd>
 </dl>
 </dd>
</dl>

<h3 id="report()">report()</h3>

<p>All of the aforementioned functions must throw an <code>AssertionError</code> when a corresponding condition is not met, with a message that may be <code>undefined</code> if not provided.<br>
 All assertion methods provide both the actual and expected values to the assertion error for display purposes.<br>
 <br>
 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.</p>

<pre>undefined report(
  failed,
  actual,
  expected,
  message,
  operator
);
</pre>

<h6 id="Parameters_15">Parameters</h6>

<dl>
 <dt><code>failed</code></dt>
 <dd>Indicates if the assertion failed or not</dd>
 <dt><code>actual</code></dt>
 <dd>The result of evaluating the assertion</dd>
 <dt><code>expected</code></dt>
 <dd>Expected result from the test author</dd>
 <dt><code>message</code></dt>
 <dd>Short explanation of the expected result</dd>
 <dt><code>operator</code></dt>
 <dd>Operation qualifier used by the assertion method (ex: '==')</dd>
</dl>

<h2 id="Examples">Examples</h2>

<h3 id="Custom_reporter_example">Custom reporter example</h3>

<pre class="brush: js">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);
  }
});
</pre>

<h2 id="See_also">See also</h2>

<ul>
 <li><a class="internal" href="/en-US/docs/JavaScript_code_modules/Using" title="en-US/docs/JavaScript code modules/Using JavaScript code modules">Using JavaScript code modules</a></li>
 <li><a class="internal" href="/en-US/docs/Mozilla/JavaScript_code_modules" title="en-US/docs/Mozilla/JavaScript code modules">JavaScript code modules</a></li>
 <li><a class="internal" href="/en-US/docs/Components.utils.import" title="en-US/docs/Components.utils.import"><code>Components.utils.import</code></a></li>
 <li><a href="/en-US/docs/Browser_chrome_tests" title="/en-US/docs/Browser_chrome_tests">Browser Chrome tests</a></li>
 <li><a href="/en-US/docs/Mozilla/QA/Writing_xpcshell-based_unit_tests" title="/en-US/docs/Mozilla/QA/Writing_xpcshell-based_unit_tests">Writing xpcshell-based unit tests</a></li>
</ul>