unexpected
Version:
Extensible BDD assertion toolkit
488 lines (459 loc) • 47.4 kB
HTML
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1,user-scalable=0">
<link rel="stylesheet" href="../../static/normalize.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../static/main.css" type="text/css" media="screen" />
<link rel="shortcut icon" type="image/vnd.microsoft.icon" href="../../static/bug-icon-black.ico">
<title>addAssertion</title>
</head>
<body class="sidebar-hidden has-sidebar">
<header>
<div class="logo-icon"></div>
<nav>
<ul>
<li class="menu-toggle-item">
<button class="menu-toggle" onclick="toggleSidebar()"></button>
</li>
<li class=""><a href="../..">Unexpected</a></li>
<li class=""><a href="../../assertions/any/to-be">Assertions</a></li>
<li class="active"><a href="">API</a></li>
<li class=""><a href="../../plugins">Plugins</a></li>
</ul>
</nav>
<div class="search" style="visibility: hidden">
<input id="search" placeholder="Search..." value="">
<div id="searchDropDown" class="dropDown">
<ul id="searchResults"></ul>
</div>
</div>
</header>
<section id="api">
<nav id="api-menu" class="sidebar js-remember-scroll-position">
<ul>
<li class="active">
<a href="">addAssertion</a>
</li>
<li class="">
<a href="../addType">addType</a>
</li>
<li class="">
<a href="../async">async</a>
</li>
<li class="">
<a href="../clone">clone</a>
</li>
<li class="">
<a href="../expect">expect</a>
</li>
<li class="">
<a href="../fail">fail</a>
</li>
<li class="">
<a href="../promise">promise</a>
</li>
<li class="">
<a href="../promise-all">promise.all</a>
</li>
<li class="">
<a href="../promise-any">promise.any</a>
</li>
<li class="">
<a href="../promise-settle">promise.settle</a>
</li>
<li class="">
<a href="../toString">toString</a>
</li>
<li class="">
<a href="../UnexpectedError">UnexpectedError</a>
</li>
<li class="">
<a href="../use">use</a>
</li>
<li class="">
<a href="../withError">withError</a>
</li>
</ul>
</nav>
<div class="main" tabindex="-1">
<div class="content">
<h1 id="expect-addassertion-">expect.addAssertion(...)</h1>
<p>Signature:</p>
<div class="code lang-javascript">
<div>expect<span style="color: #000000">.</span><span style="color: #000000">addAssertion</span><span style="color: #000000">(</span>pattern<span style="color: #000000">,</span> handler<span style="color: #000000">);</span></div>
<div>expect<span style="color: #000000">.</span><span style="color: #000000">addAssertion</span><span style="color: #000000">([</span>pattern<span style="color: #000000">,</span> <span style="color: #000000">...]],</span> handler<span style="color: #000000">);</span></div>
<div>expect<span style="color: #000000">.</span><span style="color: #000000">addAssertion</span><span style="color: #000000">(</span>typeName<span style="color: #000000">,</span> pattern<span style="color: #000000">,</span> handler<span style="color: #000000">);</span></div>
<div>expect<span style="color: #000000">.</span><span style="color: #000000">addAssertion</span><span style="color: #000000">(</span>typeName<span style="color: #000000">,</span> <span style="color: #000000">[</span>pattern<span style="color: #000000">,</span> <span style="color: #000000">...],</span> handler<span style="color: #000000">);</span></div>
<div>expect<span style="color: #000000">.</span><span style="color: #000000">addAssertion</span><span style="color: #000000">([</span>typeName<span style="color: #000000">,</span> <span style="color: #000000">...],</span> pattern<span style="color: #000000">,</span> handler<span style="color: #000000">);</span></div>
<div>expect<span style="color: #000000">.</span><span style="color: #000000">addAssertion</span><span style="color: #000000">([</span>typeName<span style="color: #000000">,</span> <span style="color: #000000">...],</span> <span style="color: #000000">[</span>pattern<span style="color: #000000">,</span> <span style="color: #000000">...],</span> handler<span style="color: #000000">);</span></div>
</div><p>New assertions can be added to Unexpected the following way.</p>
<div class="code lang-javascript">
<div><span style="color: #a71d5d">var</span> errorMode <span style="color: #a71d5d">=</span> <span style="color: #df5000">'default'</span><span style="color: #000000">;</span><span style="color: #969896"> // use to control the error mode later in the example</span></div>
<div>expect<span style="color: #000000">.</span><span style="color: #000000">addAssertion</span><span style="color: #000000">(</span><span style="color: #df5000">'array'</span><span style="color: #000000">,</span> <span style="color: #df5000">'[not] to be (sorted|ordered)'</span><span style="color: #000000">,</span> <span style="color: #a71d5d">function</span><span style="color: #000000">(</span>expect<span style="color: #000000">,</span> subject<span style="color: #000000">,</span> cmp<span style="color: #000000">)</span> <span style="color: #000000">{</span></div>
<div> <span style="color: #a71d5d">this</span><span style="color: #000000">.</span>errorMode <span style="color: #a71d5d">=</span> errorMode<span style="color: #000000">;</span></div>
<div> <span style="color: #000000">expect</span><span style="color: #000000">(</span>subject<span style="color: #000000">,</span> <span style="color: #df5000">'[not] to equal'</span><span style="color: #000000">,</span> <span style="color: #000000">[].</span><span style="color: #000000">concat</span><span style="color: #000000">(</span>subject<span style="color: #000000">).</span><span style="color: #000000">sort</span><span style="color: #000000">(</span>cmp<span style="color: #000000">));</span></div>
<div><span style="color: #000000">});</span></div>
</div><p>The above assertion definition makes the following expects possible:</p>
<div class="code lang-javascript">
<div><span style="color: #000000">expect</span><span style="color: #000000">([</span><span style="color: #0086b3">1</span><span style="color: #000000">,</span><span style="color: #0086b3">2</span><span style="color: #000000">,</span><span style="color: #0086b3">3</span><span style="color: #000000">],</span> <span style="color: #df5000">'to be sorted'</span><span style="color: #000000">);</span></div>
<div><span style="color: #000000">expect</span><span style="color: #000000">([</span><span style="color: #0086b3">1</span><span style="color: #000000">,</span><span style="color: #0086b3">2</span><span style="color: #000000">,</span><span style="color: #0086b3">3</span><span style="color: #000000">],</span> <span style="color: #df5000">'to be ordered'</span><span style="color: #000000">);</span></div>
<div><span style="color: #000000">expect</span><span style="color: #000000">([</span><span style="color: #0086b3">2</span><span style="color: #000000">,</span><span style="color: #0086b3">1</span><span style="color: #000000">,</span><span style="color: #0086b3">3</span><span style="color: #000000">],</span> <span style="color: #df5000">'not to be sorted'</span><span style="color: #000000">);</span></div>
<div><span style="color: #000000">expect</span><span style="color: #000000">([</span><span style="color: #0086b3">2</span><span style="color: #000000">,</span><span style="color: #0086b3">1</span><span style="color: #000000">,</span><span style="color: #0086b3">3</span><span style="color: #000000">],</span> <span style="color: #df5000">'not to be ordered'</span><span style="color: #000000">);</span></div>
<div><span style="color: #000000">expect</span><span style="color: #000000">([</span><span style="color: #0086b3">3</span><span style="color: #000000">,</span><span style="color: #0086b3">2</span><span style="color: #000000">,</span><span style="color: #0086b3">1</span><span style="color: #000000">],</span> <span style="color: #df5000">'to be sorted'</span><span style="color: #000000">,</span> <span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>x<span style="color: #000000">,</span> y<span style="color: #000000">)</span> <span style="color: #000000">{</span> <span style="color: #a71d5d">return</span> y <span style="color: #a71d5d">-</span> x<span style="color: #000000">;</span> <span style="color: #000000">});</span></div>
</div><p>Let's dissect the different parts of the custom assertion we just
introduced.</p>
<p>The first parameter to <code>addAssertion</code> is a string or an array
specifying which types the assertion should be defined on. In this
case the assertion in only defined for arrays. In case the type is not
specified the assertion will be defined for the type <code>any</code>, and would
be applicable any type. See the <code>Extending Unexpected with new types</code>
section for more information about the type system in Unexpected.</p>
<p>The second parameter to <code>addAssertion</code> is a string or an array stating
the patterns this assertion should match. A pattern has the following
syntax. A word in square brackets represents a flag that can either be
there or not. If the flag is present <code>this.flags[flag]</code> will contain
the value <code>true</code>. In this case <code>not</code> is a flag. When a flag it present
in a nested <code>expect</code> it will be inserted if the flag is present;
otherwise it will be removed. Text that is in parentheses with
vertical bars between them are treated as alternative texts that can
be used. In this case you can write <em>ordered</em> as an alternative to
<em>sorted</em>.</p>
<p>The last parameter to <code>addAssertion</code> is function that will be called
when <code>expect</code> is invoked with an expectation matching the type and
pattern of the assertion.</p>
<p>So in this case, when <code>expect</code> is called the following way:</p>
<div class="code lang-javascript">
<div><span style="color: #000000">expect</span><span style="color: #000000">([</span><span style="color: #0086b3">3</span><span style="color: #000000">,</span><span style="color: #0086b3">2</span><span style="color: #000000">,</span><span style="color: #0086b3">1</span><span style="color: #000000">],</span> <span style="color: #df5000">'to be sorted'</span><span style="color: #000000">,</span> reverse<span style="color: #000000">);</span></div>
</div><p>The handler to our assertion will be called with the values the
following way, where the <em>not</em> flag in the nested expect will be
removed:</p>
<div class="code lang-javascript">
<div>expect<span style="color: #000000">.</span><span style="color: #000000">addAssertion</span><span style="color: #000000">(</span><span style="color: #df5000">'array'</span><span style="color: #000000">,</span> <span style="color: #df5000">'[not] to be (sorted|ordered)'</span><span style="color: #000000">,</span> <span style="color: #a71d5d">function</span><span style="color: #000000">(</span>expect<span style="color: #000000">,</span> <span style="color: #000000">[</span><span style="color: #0086b3">3</span><span style="color: #000000">,</span><span style="color: #0086b3">2</span><span style="color: #000000">,</span><span style="color: #0086b3">1</span><span style="color: #000000">],</span> reverse<span style="color: #000000">){</span></div>
<div> <span style="color: #000000">expect</span><span style="color: #000000">([</span><span style="color: #0086b3">3</span><span style="color: #000000">,</span><span style="color: #0086b3">2</span><span style="color: #000000">,</span><span style="color: #0086b3">1</span><span style="color: #000000">],</span> <span style="color: #df5000">'[not] to equal'</span><span style="color: #000000">,</span> <span style="color: #000000">[].</span><span style="color: #000000">concat</span><span style="color: #000000">([</span><span style="color: #0086b3">3</span><span style="color: #000000">,</span><span style="color: #0086b3">2</span><span style="color: #000000">,</span><span style="color: #0086b3">1</span><span style="color: #000000">]).</span><span style="color: #000000">sort</span><span style="color: #000000">(</span>reverse<span style="color: #000000">));</span></div>
<div><span style="color: #000000">});</span></div>
</div><h3 id="overriding-the-standard-error-message">Overriding the standard error message</h3>
<p>When you create a new assertion Unexpected will generate an error
message from the assertion text and the input arguments. In some cases
it can be preferable to tweak the output instead of creating
completely custom output using <a href="../fail/">expect.fail</a>.</p>
<p>You can override how the <code>subject</code> is displayed by providing a
<code>subjectOutput</code> on the assertion. You can also override the output of
the arguments by overriding parts of <code>argsOutput</code> or provide a
completely custom output for the arguments by setting <code>argsOutput</code> to
an output function on the assertion.</p>
<p>Here is a few examples:</p>
<div class="code lang-javascript">
<div>expect<span style="color: #000000">.</span><span style="color: #000000">addAssertion</span><span style="color: #000000">(</span><span style="color: #df5000">'number'</span><span style="color: #000000">,</span> <span style="color: #df5000">'to be contained by'</span><span style="color: #000000">,</span> <span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>expect<span style="color: #000000">,</span> subject<span style="color: #000000">,</span> start<span style="color: #000000">,</span> finish<span style="color: #000000">)</span> <span style="color: #000000">{</span></div>
<div> <span style="color: #a71d5d">this</span><span style="color: #000000">.</span>subjectOutput <span style="color: #a71d5d">=</span> <span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>output<span style="color: #000000">)</span> <span style="color: #000000">{</span></div>
<div> output<span style="color: #000000">.</span><span style="color: #000000">text</span><span style="color: #000000">(</span><span style="color: #df5000">'point '</span><span style="color: #000000">).</span><span style="color: #000000">jsNumber</span><span style="color: #000000">(</span>subject<span style="color: #000000">);</span></div>
<div> <span style="color: #000000">};</span></div>
<div> <span style="color: #a71d5d">this</span><span style="color: #000000">.</span>argsOutput <span style="color: #a71d5d">=</span> <span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>output<span style="color: #000000">)</span> <span style="color: #000000">{</span></div>
<div> output<span style="color: #000000">.</span><span style="color: #000000">text</span><span style="color: #000000">(</span><span style="color: #df5000">'interval '</span><span style="color: #000000">).</span><span style="color: #000000">text</span><span style="color: #000000">(</span><span style="color: #df5000">'['</span><span style="color: #000000">).</span><span style="color: #000000">appendInspected</span><span style="color: #000000">(</span>start<span style="color: #000000">).</span><span style="color: #000000">text</span><span style="color: #000000">(</span><span style="color: #df5000">';'</span><span style="color: #000000">).</span><span style="color: #000000">appendInspected</span><span style="color: #000000">(</span>finish<span style="color: #000000">).</span><span style="color: #000000">text</span><span style="color: #000000">(</span><span style="color: #df5000">']'</span><span style="color: #000000">);</span></div>
<div> <span style="color: #000000">};</span></div>
<div> <span style="color: #000000">expect</span><span style="color: #000000">(</span>subject <span style="color: #a71d5d">>=</span> start && subject <span style="color: #a71d5d"><=</span> finish<span style="color: #000000">,</span> <span style="color: #df5000">'[not] to be truthy'</span><span style="color: #000000">);</span></div>
<div><span style="color: #000000">});</span></div>
<div> </div>
<div><span style="color: #000000">expect</span><span style="color: #000000">(</span><span style="color: #0086b3">4</span><span style="color: #000000">,</span> <span style="color: #df5000">'to be contained by'</span><span style="color: #000000">,</span> <span style="color: #0086b3">8</span><span style="color: #000000">,</span> <span style="color: #0086b3">10</span><span style="color: #000000">);</span></div>
</div><div class="output">
<div><span style="color: red; font-weight: bold">expected</span> point <span style="color: #0086b3">4</span> <span style="color: red; font-weight: bold">to be contained by</span> interval [<span style="color: #0086b3">8</span>;<span style="color: #0086b3">10</span>]</div>
</div><div class="code lang-javascript">
<div>expect<span style="color: #000000">.</span><span style="color: #000000">addAssertion</span><span style="color: #000000">(</span><span style="color: #df5000">'number'</span><span style="color: #000000">,</span> <span style="color: #df5000">'to be similar to'</span><span style="color: #000000">,</span> <span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>expect<span style="color: #000000">,</span> subject<span style="color: #000000">,</span> value<span style="color: #000000">,</span> epsilon<span style="color: #000000">)</span> <span style="color: #000000">{</span></div>
<div> <span style="color: #a71d5d">if</span> <span style="color: #000000">(</span><span style="color: #a71d5d">typeof</span> epsilon <span style="color: #a71d5d">!==</span> <span style="color: #df5000">'number'</span><span style="color: #000000">)</span> <span style="color: #000000">{</span></div>
<div> epsilon <span style="color: #a71d5d">=</span> <span style="color: #0086b3">1e-9</span><span style="color: #000000">;</span></div>
<div> <span style="color: #000000">}</span></div>
<div> <span style="color: #a71d5d">this</span><span style="color: #000000">.</span>argsOutput<span style="color: #000000">[</span><span style="color: #0086b3">2</span><span style="color: #000000">]</span> <span style="color: #a71d5d">=</span> <span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>output<span style="color: #000000">)</span> <span style="color: #000000">{</span></div>
<div> output<span style="color: #000000">.</span><span style="color: #000000">text</span><span style="color: #000000">(</span><span style="color: #df5000">'(epsilon: '</span><span style="color: #000000">).</span><span style="color: #000000">jsNumber</span><span style="color: #000000">(</span>epsilon<span style="color: #000000">.</span><span style="color: #000000">toExponential</span><span style="color: #000000">()).</span><span style="color: #000000">text</span><span style="color: #000000">(</span><span style="color: #df5000">')'</span><span style="color: #000000">)</span></div>
<div> <span style="color: #000000">}</span></div>
<div> <span style="color: #000000">expect</span><span style="color: #000000">(</span>Math<span style="color: #000000">.</span><span style="color: #000000">abs</span><span style="color: #000000">(</span>subject <span style="color: #a71d5d">-</span> value<span style="color: #000000">),</span> <span style="color: #df5000">'to be less than or equal to'</span><span style="color: #000000">,</span> epsilon<span style="color: #000000">);</span></div>
<div><span style="color: #000000">});</span></div>
<div> </div>
<div><span style="color: #000000">expect</span><span style="color: #000000">(</span><span style="color: #0086b3">4</span><span style="color: #000000">,</span> <span style="color: #df5000">'to be similar to'</span><span style="color: #000000">,</span> <span style="color: #0086b3">4.0001</span><span style="color: #000000">);</span></div>
</div><div class="output">
<div><span style="color: red; font-weight: bold">expected</span> <span style="color: #0086b3">4</span> <span style="color: red; font-weight: bold">to be similar to</span> <span style="color: #0086b3">4.0001</span>, (epsilon: <span style="color: #0086b3">1e-9</span>)</div>
</div><h3 id="controlling-the-output-of-nested-expects">Controlling the output of nested expects</h3>
<p>When a call to <code>expect</code> fails inside your assertion the standard error
message for the custom assertion will be used. In the case of our
<em>sorted</em> assertion fails, the output will be:</p>
<div class="code lang-javascript">
<div><span style="color: #000000">expect</span><span style="color: #000000">([</span> <span style="color: #0086b3">1</span><span style="color: #000000">,</span> <span style="color: #0086b3">3</span><span style="color: #000000">,</span> <span style="color: #0086b3">2</span><span style="color: #000000">,</span> <span style="color: #0086b3">4</span> <span style="color: #000000">],</span> <span style="color: #df5000">'to be sorted'</span><span style="color: #000000">);</span></div>
</div><div class="output">
<div><span style="color: red; font-weight: bold">expected</span> [ <span style="color: #0086b3">1</span>, <span style="color: #0086b3">3</span>, <span style="color: #0086b3">2</span>, <span style="color: #0086b3">4</span> ] <span style="color: red; font-weight: bold">to be sorted</span></div>
<div> </div>
<div>[</div>
<div> <div style="display: inline-block; vertical-align: top">
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">1</span>,</div>
</div></div>
</div></div>
<div> <div style="display: inline-block; vertical-align: top">
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">3</span>, </div>
</div><div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">//</span></div>
</div> <div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">should equal</span> <div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">2</span></div>
</div></div>
</div></div>
</div></div>
<div> <div style="display: inline-block; vertical-align: top">
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">2</span>, </div>
</div><div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">//</span></div>
</div> <div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">should equal</span> <div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">3</span></div>
</div></div>
</div></div>
</div></div>
<div> <div style="display: inline-block; vertical-align: top">
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">4</span></div>
</div></div>
</div></div>
<div>]</div>
</div><p>We can control the output of the nested expects by changing the
<code>this.errorMode</code> property.</p>
<p>The <em>bubble</em> error mode will hoist the next level error message to this level.</p>
<p>If we change the error mode to <em>bubble</em>, we get the following output:</p>
<div class="code lang-javascript">
<div>errorMode <span style="color: #a71d5d">=</span> <span style="color: #df5000">'bubble'</span><span style="color: #000000">;</span></div>
<div><span style="color: #000000">expect</span><span style="color: #000000">([</span> <span style="color: #0086b3">1</span><span style="color: #000000">,</span> <span style="color: #0086b3">3</span><span style="color: #000000">,</span> <span style="color: #0086b3">2</span><span style="color: #000000">,</span> <span style="color: #0086b3">4</span> <span style="color: #000000">],</span> <span style="color: #df5000">'to be sorted'</span><span style="color: #000000">);</span></div>
</div><div class="output">
<div><span style="color: red; font-weight: bold">expected</span> [ <span style="color: #0086b3">1</span>, <span style="color: #0086b3">3</span>, <span style="color: #0086b3">2</span>, <span style="color: #0086b3">4</span> ] <span style="color: red; font-weight: bold">to equal</span> [ <span style="color: #0086b3">1</span>, <span style="color: #0086b3">2</span>, <span style="color: #0086b3">3</span>, <span style="color: #0086b3">4</span> ]</div>
<div> </div>
<div>[</div>
<div> <div style="display: inline-block; vertical-align: top">
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">1</span>,</div>
</div></div>
</div></div>
<div> <div style="display: inline-block; vertical-align: top">
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">3</span>, </div>
</div><div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">//</span></div>
</div> <div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">should equal</span> <div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">2</span></div>
</div></div>
</div></div>
</div></div>
<div> <div style="display: inline-block; vertical-align: top">
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">2</span>, </div>
</div><div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">//</span></div>
</div> <div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">should equal</span> <div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">3</span></div>
</div></div>
</div></div>
</div></div>
<div> <div style="display: inline-block; vertical-align: top">
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">4</span></div>
</div></div>
</div></div>
<div>]</div>
</div><p>In the <em>nested</em> error mode the next level error message is included and
indented underneath the standard error message.</p>
<p>If we change the error mode to <em>nested</em>, we get the following output:</p>
<div class="code lang-javascript">
<div>errorMode <span style="color: #a71d5d">=</span> <span style="color: #df5000">'nested'</span><span style="color: #000000">;</span></div>
<div><span style="color: #000000">expect</span><span style="color: #000000">([</span> <span style="color: #0086b3">1</span><span style="color: #000000">,</span> <span style="color: #0086b3">3</span><span style="color: #000000">,</span> <span style="color: #0086b3">2</span><span style="color: #000000">,</span> <span style="color: #0086b3">4</span> <span style="color: #000000">],</span> <span style="color: #df5000">'to be sorted'</span><span style="color: #000000">);</span></div>
</div><div class="output">
<div><span style="color: red; font-weight: bold">expected</span> [ <span style="color: #0086b3">1</span>, <span style="color: #0086b3">3</span>, <span style="color: #0086b3">2</span>, <span style="color: #0086b3">4</span> ] <span style="color: red; font-weight: bold">to be sorted</span></div>
<div> <div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">expected</span> [ <span style="color: #0086b3">1</span>, <span style="color: #0086b3">3</span>, <span style="color: #0086b3">2</span>, <span style="color: #0086b3">4</span> ] <span style="color: red; font-weight: bold">to equal</span> [ <span style="color: #0086b3">1</span>, <span style="color: #0086b3">2</span>, <span style="color: #0086b3">3</span>, <span style="color: #0086b3">4</span> ]</div>
<div> </div>
<div>[</div>
<div> <div style="display: inline-block; vertical-align: top">
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">1</span>,</div>
</div></div>
</div></div>
<div> <div style="display: inline-block; vertical-align: top">
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">3</span>, </div>
</div><div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">//</span></div>
</div> <div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">should equal</span> <div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">2</span></div>
</div></div>
</div></div>
</div></div>
<div> <div style="display: inline-block; vertical-align: top">
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">2</span>, </div>
</div><div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">//</span></div>
</div> <div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">should equal</span> <div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">3</span></div>
</div></div>
</div></div>
</div></div>
<div> <div style="display: inline-block; vertical-align: top">
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">4</span></div>
</div></div>
</div></div>
<div>]</div>
</div></div>
</div><p>The <em>defaultOrNested</em> error mode uses the default mode if the error chain contains a diff;
otherwise it the <em>nested</em> error mode will be used.</p>
<p>If we change the error mode to <em>defaultOrNested</em>, we get the following output:</p>
<div class="code lang-javascript">
<div>errorMode <span style="color: #a71d5d">=</span> <span style="color: #df5000">'defaultOrNested'</span><span style="color: #000000">;</span></div>
<div><span style="color: #000000">expect</span><span style="color: #000000">([</span> <span style="color: #0086b3">1</span><span style="color: #000000">,</span> <span style="color: #0086b3">3</span><span style="color: #000000">,</span> <span style="color: #0086b3">2</span><span style="color: #000000">,</span> <span style="color: #0086b3">4</span> <span style="color: #000000">],</span> <span style="color: #df5000">'to be sorted'</span><span style="color: #000000">);</span></div>
</div><div class="output">
<div><span style="color: red; font-weight: bold">expected</span> [ <span style="color: #0086b3">1</span>, <span style="color: #0086b3">3</span>, <span style="color: #0086b3">2</span>, <span style="color: #0086b3">4</span> ] <span style="color: red; font-weight: bold">to be sorted</span></div>
<div> </div>
<div>[</div>
<div> <div style="display: inline-block; vertical-align: top">
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">1</span>,</div>
</div></div>
</div></div>
<div> <div style="display: inline-block; vertical-align: top">
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">3</span>, </div>
</div><div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">//</span></div>
</div> <div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">should equal</span> <div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">2</span></div>
</div></div>
</div></div>
</div></div>
<div> <div style="display: inline-block; vertical-align: top">
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">2</span>, </div>
</div><div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">//</span></div>
</div> <div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">should equal</span> <div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">3</span></div>
</div></div>
</div></div>
</div></div>
<div> <div style="display: inline-block; vertical-align: top">
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">4</span></div>
</div></div>
</div></div>
<div>]</div>
</div><p>In the <em>diff</em> error mode will hoist the first found diff as the error message.
If no diff is present, it will fall back to the <em>default</em> error mode.</p>
<p>If we change the error mode to <em>diff</em>, we get the following output:</p>
<div class="code lang-javascript">
<div>errorMode <span style="color: #a71d5d">=</span> <span style="color: #df5000">'diff'</span><span style="color: #000000">;</span></div>
<div><span style="color: #000000">expect</span><span style="color: #000000">([</span> <span style="color: #0086b3">1</span><span style="color: #000000">,</span> <span style="color: #0086b3">3</span><span style="color: #000000">,</span> <span style="color: #0086b3">2</span><span style="color: #000000">,</span> <span style="color: #0086b3">4</span> <span style="color: #000000">],</span> <span style="color: #df5000">'to be sorted'</span><span style="color: #000000">);</span></div>
</div><div class="output">
<div>[</div>
<div> <div style="display: inline-block; vertical-align: top">
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">1</span>,</div>
</div></div>
</div></div>
<div> <div style="display: inline-block; vertical-align: top">
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">3</span>, </div>
</div><div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">//</span></div>
</div> <div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">should equal</span> <div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">2</span></div>
</div></div>
</div></div>
</div></div>
<div> <div style="display: inline-block; vertical-align: top">
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">2</span>, </div>
</div><div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">//</span></div>
</div> <div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">should equal</span> <div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">3</span></div>
</div></div>
</div></div>
</div></div>
<div> <div style="display: inline-block; vertical-align: top">
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: #0086b3">4</span></div>
</div></div>
</div></div>
<div>]</div>
</div><h3 id="asynchronous-assertions">Asynchronous assertions</h3>
<p>Unexpected comes with built-in support for asynchronous
assertions. You basically just return a promise from the assertion.</p>
<p>For the purpose of explaining how we can make an asynchronous
assertion we will define a silly type which contains a
value that can only be retrieved after a delay:</p>
<div class="code lang-javascript">
<div><span style="color: #a71d5d">function</span> <span style="color: #000000">Timelock</span><span style="color: #000000">(</span>value<span style="color: #000000">,</span> delay<span style="color: #000000">)</span> <span style="color: #000000">{</span></div>
<div> <span style="color: #a71d5d">this</span><span style="color: #000000">.</span>value <span style="color: #a71d5d">=</span> value<span style="color: #000000">;</span></div>
<div> <span style="color: #a71d5d">this</span><span style="color: #000000">.</span>delay <span style="color: #a71d5d">=</span> delay<span style="color: #000000">;</span></div>
<div><span style="color: #000000">}</span></div>
<div> </div>
<div>Timelock<span style="color: #000000">.</span>prototype<span style="color: #000000">.</span>getValue <span style="color: #a71d5d">=</span> <span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>cb<span style="color: #000000">)</span> <span style="color: #000000">{</span></div>
<div> <span style="color: #a71d5d">var</span> that <span style="color: #a71d5d">=</span> <span style="color: #a71d5d">this</span><span style="color: #000000">;</span></div>
<div> <span style="color: #000000">setTimeout</span><span style="color: #000000">(</span><span style="color: #a71d5d">function</span> <span style="color: #000000">()</span> <span style="color: #000000">{</span></div>
<div> <span style="color: #000000">cb</span><span style="color: #000000">(</span>that<span style="color: #000000">.</span>value<span style="color: #000000">);</span></div>
<div> <span style="color: #000000">},</span> <span style="color: #a71d5d">this</span><span style="color: #000000">.</span>delay<span style="color: #000000">);</span></div>
<div><span style="color: #000000">};</span></div>
</div><p>It would be pretty nice if we could use
<a href="../../assertions/any/to-satisfy/">to satisfy</a> on the value of a <code>Timelock</code>,
even if the retrieval is delayed. Then we would be able to do stuff
like this:</p>
<div class="code lang-javascript">
<div><span style="color: #a71d5d">return</span> <span style="color: #000000">expect</span><span style="color: #000000">(</span><span style="color: #a71d5d">new</span> Timelock<span style="color: #000000">(</span><span style="color: #df5000">'Hello world'</span><span style="color: #000000">),</span> <span style="color: #df5000">'to satisfy'</span><span style="color: #000000">,</span> expect<span style="color: #000000">.</span><span style="color: #000000">it</span><span style="color: #000000">(</span><span style="color: #df5000">'have length'</span><span style="color: #000000">,</span> <span style="color: #0086b3">11</span><span style="color: #000000">));</span></div>
</div><p>First we need to define a <a href="../addType/">type</a> for handling the <code>Timelock</code>:</p>
<div class="code lang-javascript">
<div>expect<span style="color: #000000">.</span><span style="color: #000000">addType</span><span style="color: #000000">({</span></div>
<div> name<span style="color: #000000">:</span> <span style="color: #df5000">'Timelock'</span><span style="color: #000000">,</span></div>
<div> identify<span style="color: #000000">:</span> <span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>value<span style="color: #000000">)</span> <span style="color: #000000">{</span></div>
<div> <span style="color: #a71d5d">return</span> value && value <span style="color: #a71d5d">instanceof</span> Timelock<span style="color: #000000">;</span></div>
<div> <span style="color: #000000">},</span></div>
<div> inspect<span style="color: #000000">:</span> <span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>value<span style="color: #000000">,</span> depth<span style="color: #000000">,</span> output<span style="color: #000000">)</span> <span style="color: #000000">{</span></div>
<div> output<span style="color: #000000">.</span><span style="color: #000000">jsFunctionName</span><span style="color: #000000">(</span><span style="color: #df5000">'Timelock'</span><span style="color: #000000">);</span></div>
<div> <span style="color: #000000">}</span></div>
<div><span style="color: #000000">});</span></div>
</div><div class="code lang-javascript">
<div>expect<span style="color: #000000">.</span><span style="color: #000000">addAssertion</span><span style="color: #000000">(</span><span style="color: #df5000">'Timelock'</span><span style="color: #000000">,</span> <span style="color: #df5000">'to satisfy'</span><span style="color: #000000">,</span> <span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>expect<span style="color: #000000">,</span> subject<span style="color: #000000">,</span> spec<span style="color: #000000">)</span> <span style="color: #000000">{</span></div>
<div> <span style="color: #a71d5d">return</span> expect<span style="color: #000000">.</span><span style="color: #000000">promise</span><span style="color: #000000">(</span><span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>run<span style="color: #000000">)</span> <span style="color: #000000">{</span></div>
<div> subject<span style="color: #000000">.</span><span style="color: #000000">getValue</span><span style="color: #000000">(</span><span style="color: #000000">run</span><span style="color: #000000">(</span><span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>value<span style="color: #000000">)</span> <span style="color: #000000">{</span></div>
<div> <span style="color: #a71d5d">return</span> <span style="color: #000000">expect</span><span style="color: #000000">(</span>value<span style="color: #000000">,</span> <span style="color: #df5000">'to satisfy'</span><span style="color: #000000">,</span> spec<span style="color: #000000">);</span></div>
<div> <span style="color: #000000">}));</span></div>
<div> <span style="color: #000000">});</span></div>
<div><span style="color: #000000">});</span></div>
</div><p>Let's see how it works:</p>
<div class="code lang-javascript">
<div><span style="color: #a71d5d">return</span> <span style="color: #000000">expect</span><span style="color: #000000">(</span><span style="color: #a71d5d">new</span> Timelock<span style="color: #000000">(</span><span style="color: #df5000">'Hello world!'</span><span style="color: #000000">,</span> <span style="color: #0086b3">5</span><span style="color: #000000">),</span> <span style="color: #df5000">'to satisfy'</span><span style="color: #000000">,</span> expect<span style="color: #000000">.</span><span style="color: #000000">it</span><span style="color: #000000">(</span><span style="color: #df5000">'not to match'</span><span style="color: #000000">,</span> <span style="color: #183691">/!/</span><span style="color: #000000">));</span></div>
</div><div class="output">
<div><span style="color: red; font-weight: bold">expected</span> <span style="color: #795da3">Timelock</span> <span style="color: red; font-weight: bold">to satisfy</span> expect.it(<span style="color: #df5000">'not to match'</span>, <span style="color: #183691">/!/</span>)</div>
<div> </div>
<div><div style="display: inline-block; vertical-align: top">
<div><span style="color: red; font-weight: bold">expected</span> <span style="color: #df5000">'Hello world!'</span> <span style="color: red; font-weight: bold">not to match</span> <span style="color: #183691">/!/</span></div>
<div> </div>
<div>Hello world<span style="background-color: red; color: white">!</span></div>
</div></div>
</div><p>The best resource for learning more about custom assertions is to look
at how the predefined assertions are built:</p>
<p><a href="https://github.com/unexpectedjs/unexpected/blob/master/lib/assertions.js">lib/assertions.js</a></p>
</div>
</div>
</section>
<script type="text/javascript">
baseUrl = '../..';
</script>
<script type="text/javascript" src="../../static/toggleSidebar.js"></script>
<script type="text/javascript" src="../../static/rememberScrollPosition.js"></script>
<script type="text/javascript" src="../../static/focusMain.js"></script>
<script type="text/javascript" src="../../static/search.js"></script>
</body>
</html>