unexpected

<!DOCTYPE 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>UnexpectedError</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="../addAssertion">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=""> <a href="../addAssertion">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="active"> <a href="">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="unexpectederror">UnexpectedError</h1> <p>When assertions fail in Unexpected they yield an <code>UnexpectedError</code>. This instance has several convenience methods for retrieving information about the error.</p> <h2 id="unexpectederror-geterrormessage-options-">UnexpectedError.getErrorMessage(options)</h2> <p>Returns the error message as a <a href="https://github.com/sunesimonsen/magicpen">magicpen</a> instance. The method uses the assertion error modes to produce the correct error message.</p> <p>Notice that you must either provide an output or a format in the given options. The format can be on of <code>text</code>, <code>ansi</code> or <code>html</code>. As a shortcut you can also just pass the output or format directly.</p> <p>An alternative to calling <code>getErrorMessage(output)</code> with an output, you can append the error message to an output the following way:</p> <div class="code lang-javascript"> <div>output<span style="color: #000000">.</span><span style="color: #000000">appendErrorMessage</span><span style="color: #000000">(</span>error<span style="color: #000000">);</span></div> </div><p>This is useful if you want to combine multiple errors in one assertion:</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">"to have item satisfying"</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> <span style="color: #000000">{</span></div> <div>  <span style="color: #a71d5d">var</span> args <span style="color: #a71d5d">=</span> Array<span style="color: #000000">.</span>prototype<span style="color: #000000">.</span>slice<span style="color: #000000">.</span><span style="color: #000000">call</span><span style="color: #000000">(</span>arguments<span style="color: #000000">,</span> <span style="color: #0086b3">2</span><span style="color: #000000">);</span></div> <div>  <span style="color: #a71d5d">var</span> promises <span style="color: #a71d5d">=</span> subject<span style="color: #000000">.</span><span style="color: #000000">map</span><span style="color: #000000">(</span><span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>item<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> <span style="color: #000000">{</span></div> <div>      <span style="color: #a71d5d">return</span> expect<span style="color: #000000">.</span><span style="color: #000000">apply</span><span style="color: #000000">(</span>expect<span style="color: #000000">,</span> <span style="color: #000000">[</span>item<span style="color: #000000">].</span><span style="color: #000000">concat</span><span style="color: #000000">(</span>args<span style="color: #000000">));</span></div> <div>    <span style="color: #000000">});</span></div> <div>  <span style="color: #000000">});</span></div> <div> </div> <div>  <span style="color: #a71d5d">return</span> expect<span style="color: #000000">.</span>promise<span style="color: #000000">.</span><span style="color: #000000">settle</span><span style="color: #000000">(</span>promises<span style="color: #000000">).</span><span style="color: #000000">then</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: #a71d5d">var</span> failed <span style="color: #a71d5d">=</span> promises<span style="color: #000000">.</span><span style="color: #000000">every</span><span style="color: #000000">(</span><span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>promise<span style="color: #000000">)</span> <span style="color: #000000">{</span></div> <div>      <span style="color: #a71d5d">return</span> promise<span style="color: #000000">.</span><span style="color: #000000">isRejected</span><span style="color: #000000">();</span></div> <div>    <span style="color: #000000">});</span></div> <div> </div> <div>    <span style="color: #a71d5d">if</span> <span style="color: #000000">(</span>failed<span style="color: #000000">)</span> <span style="color: #000000">{</span></div> <div>      expect<span style="color: #000000">.</span><span style="color: #000000">fail</span><span style="color: #000000">({</span></div> <div>        diff<span style="color: #000000">:</span> <span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>output<span style="color: #000000">,</span> diff<span style="color: #000000">,</span> inspect<span style="color: #000000">,</span> equal<span style="color: #000000">)</span> <span style="color: #000000">{</span></div> <div>          <span style="color: #a71d5d">var</span> result <span style="color: #a71d5d">=</span> <span style="color: #000000">{</span></div> <div>            inline<span style="color: #000000">:</span> <span style="color: #0086b3">true</span><span style="color: #000000">,</span></div> <div>            diff<span style="color: #000000">:</span> output</div> <div>          <span style="color: #000000">};</span></div> <div>          promises<span style="color: #000000">.</span><span style="color: #000000">forEach</span><span style="color: #000000">(</span><span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>promise<span style="color: #000000">,</span> index<span style="color: #000000">)</span> <span style="color: #000000">{</span></div> <div>            <span style="color: #a71d5d">if</span> <span style="color: #000000">(</span>index <span style="color: #a71d5d">></span> <span style="color: #0086b3">0</span><span style="color: #000000">)</span> <span style="color: #000000">{</span> result<span style="color: #000000">.</span>diff<span style="color: #000000">.</span><span style="color: #000000">nl</span><span style="color: #000000">(</span><span style="color: #0086b3">2</span><span style="color: #000000">);</span> <span style="color: #000000">}</span></div> <div>            <span style="color: #a71d5d">var</span> error <span style="color: #a71d5d">=</span> promise<span style="color: #000000">.</span><span style="color: #000000">reason</span><span style="color: #000000">();</span></div> <div>           <span style="color: #969896"> // the error is connected to the current scope</span></div> <div>           <span style="color: #969896"> // but we are just interested in the nested error</span></div> <div>            error<span style="color: #000000">.</span>errorMode <span style="color: #a71d5d">=</span> <span style="color: #df5000">'bubble'</span><span style="color: #000000">;</span></div> <div>            result<span style="color: #000000">.</span>diff<span style="color: #000000">.</span><span style="color: #000000">append</span><span style="color: #000000">(</span>error<span style="color: #000000">.</span><span style="color: #000000">getErrorMessage</span><span style="color: #000000">(</span>output<span style="color: #000000">));</span></div> <div>          <span style="color: #000000">});</span></div> <div>          <span style="color: #a71d5d">return</span> result<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>  <span style="color: #000000">});</span></div> <div><span style="color: #000000">});</span></div> </div><p>When the assertion fails we get the following output:</p> <div class="code lang-javascript"> <div><span style="color: #000000">expect</span><span style="color: #000000">([</span><span style="color: #df5000">'foo'</span><span style="color: #000000">,</span> <span style="color: #df5000">'bar'</span><span style="color: #000000">],</span> <span style="color: #df5000">'to have item satisfying'</span><span style="color: #000000">,</span> <span style="color: #df5000">'to equal'</span><span style="color: #000000">,</span> <span style="color: #df5000">'bar'</span><span style="color: #000000">);</span></div> <div><span style="color: #000000">expect</span><span style="color: #000000">([</span><span style="color: #df5000">'foo'</span><span style="color: #000000">,</span> <span style="color: #df5000">'bar'</span><span style="color: #000000">],</span> <span style="color: #df5000">'to have item satisfying'</span><span style="color: #000000">,</span> <span style="color: #df5000">'to equal'</span><span style="color: #000000">,</span> <span style="color: #df5000">'bAr'</span><span style="color: #000000">);</span></div> </div><div class="output"> <div><span style="color: red; font-weight: bold">expected</span> [ <span style="color: #df5000">'foo'</span>, <span style="color: #df5000">'bar'</span> ] <span style="color: red; font-weight: bold">to have item satisfying</span> <span style="color: #df5000">'to equal'</span>, <span style="color: #df5000">'bAr'</span></div> <div> </div> <div><span style="color: red; font-weight: bold">expected</span> <span style="color: #df5000">'foo'</span> <span style="color: red; font-weight: bold">to equal</span> <span style="color: #df5000">'bAr'</span></div> <div> </div> <div><div style="display: inline-block; vertical-align: top"> <div><span style="color: red">-</span></div> </div><div style="display: inline-block; vertical-align: top"> <div><span style="background-color: red; color: white">foo</span></div> </div></div> <div><div style="display: inline-block; vertical-align: top"> <div><span style="color: green">+</span></div> </div><div style="display: inline-block; vertical-align: top"> <div><span style="background-color: green; color: white">bAr</span></div> </div></div> <div> </div> <div><span style="color: red; font-weight: bold">expected</span> <span style="color: #df5000">'bar'</span> <span style="color: red; font-weight: bold">to equal</span> <span style="color: #df5000">'bAr'</span></div> <div> </div> <div><div style="display: inline-block; vertical-align: top"> <div><span style="color: red">-</span></div> </div><div style="display: inline-block; vertical-align: top"> <div><span style="background-color: red; color: white">bar</span></div> </div></div> <div><div style="display: inline-block; vertical-align: top"> <div><span style="color: green">+</span></div> </div><div style="display: inline-block; vertical-align: top"> <div><span style="background-color: green; color: white">bAr</span></div> </div></div> </div><h2 id="unexpectederror-parent">UnexpectedError.parent</h2> <p>When assertions delegate to nested <code>expect</code> calls the errors that are thrown at each level are chained together through the <code>parent</code> property. The error message is serialized lazily, so it is possible to change the error hierarchy before the error is serialized, or extract information from the hierarchy and use <a href="../fail/">expect.fail</a> to throw a new error.</p> <p>We could for example change the error mode for all the errors in the chain to <code>nested</code>:</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">'detailed to be'</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> <span style="color: #000000">{</span></div> <div>  expect<span style="color: #000000">.</span>errorMode <span style="color: #a71d5d">=</span> <span style="color: #df5000">'bubble'</span><span style="color: #000000">;</span></div> <div>  expect<span style="color: #000000">.</span><span style="color: #000000">withError</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">expect</span><span style="color: #000000">(</span>subject<span style="color: #000000">,</span> <span style="color: #df5000">'to be'</span><span style="color: #000000">,</span> value<span style="color: #000000">);</span></div> <div>  <span style="color: #000000">},</span> <span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>err<span style="color: #000000">)</span> <span style="color: #000000">{</span></div> <div>    err<span style="color: #000000">.</span><span style="color: #000000">getParents</span><span style="color: #000000">().</span><span style="color: #000000">forEach</span><span style="color: #000000">(</span><span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>e<span style="color: #000000">)</span> <span style="color: #000000">{</span></div> <div>      e<span style="color: #000000">.</span>errorMode <span style="color: #a71d5d">=</span> <span style="color: #df5000">'nested'</span><span style="color: #000000">;</span></div> <div>    <span style="color: #000000">});</span></div> <div>    expect<span style="color: #000000">.</span><span style="color: #000000">fail</span><span style="color: #000000">(</span>err<span style="color: #000000">);</span></div> <div>  <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: #df5000">'f00!'</span><span style="color: #000000">,</span> <span style="color: #df5000">'detailed to be'</span><span style="color: #000000">,</span> <span style="color: #df5000">'foo!'</span><span style="color: #000000">);</span></div> </div><div class="output"> <div><span style="color: red; font-weight: bold">expected</span> <span style="color: #df5000">'f00!'</span> <span style="color: red; font-weight: bold">to be</span> <span style="color: #df5000">'foo!'</span></div> <div>  <div style="display: inline-block; vertical-align: top"> <div><span style="color: red; font-weight: bold">expected</span> <span style="color: #df5000">'f00!'</span> <span style="color: red; font-weight: bold">to equal</span> <span style="color: #df5000">'foo!'</span></div> <div>  <div style="display: inline-block; vertical-align: top"> <div><span style="color: red; font-weight: bold">Explicit failure</span></div> <div> </div> <div><div style="display: inline-block; vertical-align: top"> <div><span style="color: red">-</span></div> </div><div style="display: inline-block; vertical-align: top"> <div><span style="background-color: red; color: white">f00</span><span style="color: red">!</span></div> </div></div> <div><div style="display: inline-block; vertical-align: top"> <div><span style="color: green">+</span></div> </div><div style="display: inline-block; vertical-align: top"> <div><span style="background-color: green; color: white">foo</span><span style="color: green">!</span></div> </div></div> </div></div> </div></div> </div><h2 id="unexpectederror-getparents-">UnexpectedError.getParents()</h2> <p>Return an array with all the ancestor errors to this error. See <a href="#unexpectederror-parent">parent</a> for more information.</p> <h2 id="unexpectederror-getallerrors-">UnexpectedError.getAllErrors()</h2> <p>Return an array with this error and all its ancestors. See <a href="#unexpectederror-parent">parent</a> for more information.</p> <h2 id="unexpectederror-getdiff-">UnexpectedError.getDiff()</h2> <p>Find the first error in the hierarchy that contains a diff and return it. This method if useful if you want to hoist a diff from an ancestor error and combine it with a new message.</p> <p>Notice that you must either provide an output or a format in the given options. The format can be on of <code>text</code>, <code>ansi</code> or <code>html</code>. As a shortcut you can also just pass the output or format directly.</p> <h2 id="unexpectederror-getdiffmethod-">UnexpectedError.getDiffMethod()</h2> <p>In case you need to wrap diff with additional information you can retrieve a method that will build a diff for you. It will find the first ancestor error that contains a diff and return the method to create the diff. Now you can delegate to that method from <code>expect.fail</code>:</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">'to be completely custom'</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> <span style="color: #000000">{</span></div> <div>  <span style="color: #a71d5d">return</span> expect<span style="color: #000000">.</span><span style="color: #000000">withError</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">expect</span><span style="color: #000000">(</span>subject<span style="color: #000000">,</span> <span style="color: #df5000">'to satisfy'</span><span style="color: #000000">,</span> <span style="color: #000000">{</span> custom<span style="color: #000000">:</span> <span style="color: #0086b3">true</span> <span style="color: #000000">});</span></div> <div>  <span style="color: #000000">},</span> <span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>err<span style="color: #000000">)</span> <span style="color: #000000">{</span></div> <div>    <span style="color: #a71d5d">var</span> createDiff <span style="color: #a71d5d">=</span> err<span style="color: #000000">.</span><span style="color: #000000">getDiffMethod</span><span style="color: #000000">();</span></div> <div>    expect<span style="color: #000000">.</span><span style="color: #000000">fail</span><span style="color: #000000">({</span></div> <div>      diff<span style="color: #000000">:</span> <span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>output<span style="color: #000000">,</span> diff<span style="color: #000000">,</span> inspect<span style="color: #000000">,</span> equal<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">'~~~~~~~~~~~~~~'</span><span style="color: #000000">).</span><span style="color: #000000">sp</span><span style="color: #000000">().</span><span style="color: #000000">success</span><span style="color: #000000">(</span><span style="color: #df5000">'custom'</span><span style="color: #000000">).</span><span style="color: #000000">sp</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">nl</span><span style="color: #000000">();</span></div> <div>        <span style="color: #a71d5d">var</span> result <span style="color: #a71d5d">=</span> <span style="color: #000000">createDiff</span><span style="color: #000000">(</span>output<span style="color: #000000">,</span> diff<span style="color: #000000">,</span> inspect<span style="color: #000000">,</span> equal<span style="color: #000000">);</span></div> <div>        <span style="color: #a71d5d">return</span> result<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><span style="color: #000000">});</span></div> <div> </div> <div><span style="color: #000000">expect</span><span style="color: #000000">({</span> custom<span style="color: #000000">:</span> <span style="color: #0086b3">false</span> <span style="color: #000000">},</span> <span style="color: #df5000">'to be completely custom'</span><span style="color: #000000">);</span></div> </div><div class="output"> <div><span style="color: red; font-weight: bold">expected</span> { <span style="color: #555">custom</span>: <span style="color: #0086b3">false</span> } <span style="color: red; font-weight: bold">to be completely custom</span></div> <div> </div> <div>~~~~~~~~~~~~~~ <span style="color: green; font-weight: bold">custom</span> ~~~~~~~~~~~~~~</div> <div>{</div> <div>  <div style="display: inline-block; vertical-align: top"> <div><span style="color: #555">custom</span>: <span style="color: #0086b3">false</span> <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">true</span></div> </div></div> </div></div> </div></div> <div>}</div> </div><h2 id="unexpectederror-getlabel-">UnexpectedError.getLabel()</h2> <p>Get a shortened representation of the error message that doesn't repeat the subject, for example <code>should equal 'bar'</code> rather than <code>expected 'foo' to equal 'bar'</code>. This makes it suitable for display next to an existing rendering of the subject, such as inside a diff.</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>