unexpected
Version:
Extensible BDD assertion toolkit
180 lines (169 loc) • 19.3 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>Plugins</title>
</head>
<body class="sidebar-hidden">
<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=""><a href="../api/addAssertion">API</a></li>
<li class="active"><a href="">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>
<div class="main theme-light" tabindex="-1">
<div class="content">
<h1 id="plugins">Plugins</h1>
<p>Unexpected is designed to be highly extensible with new data types, assertions,
output styles and themes.</p>
<p>Here's a partial list of plugins for Unexpected:</p>
<ul>
<li><a href="http://unexpected.js.org/unexpected-color/">unexpected-color</a>: Assertions for
strings representing colors.</li>
<li><a href="https://github.com/alexjeffburke/unexpected-couchdb/">unexpected-couchdb</a>:
Run your tests against a mock CouchDB server initialized to a given state.</li>
<li><a href="https://github.com/munter/unexpected-dom/">unexpected-dom</a>: Assertions for
XML/HTML DOM and HTML/XML strings. Works in the browser and in node.js via</li>
<li><a href="http://unexpected.js.org/unexpected-exif/">unexpected-exif</a>: Assertions for
EXIF data of images (node.js only).</li>
<li><a href="https://github.com/unexpectedjs/unexpected-express/">unexpected-express</a>: Express
app/middleware assertions with a declarative syntax.</li>
<li><a href="https://github.com/unexpectedjs/unexpected-fs/">unexpected-fs</a>: Assertions for
files and directories on disc, including mock file system support via
<a href="https://github.com/tschaub/mock-fs">mock-js</a>.</li>
<li><a href="https://github.com/unexpectedjs/unexpected-http/">unexpected-http</a>: Assertions for
testing local or remote HTTP servers.
Browser-compatible via browserify (experimental).</li>
<li><a href="http://unexpected.js.org/unexpected-image/">unexpected-image</a>: Assertions for
image metadata (node.js only).</li>
<li><a href="http://unexpected.js.org/unexpected-knockout/">unexpected-knockout</a>: Add support
for <a href="http://knockoutjs.com/">Knockout.js</a> observables.</li>
<li><a href="http://unexpected.js.org/unexpected-messy/">unexpected-messy</a>: Assertions for
HTTP messages (requests and responses) and mails (rfc2822). Browser-compatible.</li>
<li><a href="https://github.com/unexpectedjs/unexpected-mitm/">unexpected-mitm</a>: Mock out HTTP
and make assertions about the HTTP traffic that goes on while executing other
assertions. Based on the <a href="https://github.com/moll/node-mitm/">mitm</a> module.
Only works with node.js and io.js.</li>
<li><a href="http://github.com/bruderstein/unexpected-react-shallow/">unexpected-react-shallow</a>: Assertions for the <a href="http://facebook.github.io/react/docs/test-utils.html#shallow-rendering">React.js shallow renderer</a>. Assert using JSX.</li>
<li><a href="http://unexpected.js.org/unexpected-resemble/">unexpected-resemble</a>: Image resemblance
assertions based on <a href="http://huddle.github.io/Resemble.js/">resemble.js</a>. Works in
both node.js and the browser.</li>
<li><a href="http://unexpected.js.org/unexpected-sinon/">unexpected-sinon</a>: Add support for
<a href="http://sinonjs.org/">sinon</a> spies.
<a href="https://github.com/tmpvar/jsdom/">jsdom</a>.</li>
<li><a href="http://unexpected.js.org/unexpected-stream/">unexpected-stream</a>: Assertions for
node.js streams.</li>
</ul>
<h2 id="installation">Installation</h2>
<p>The recommended way to get plugins is installing them via npm:</p>
<div class="code lang-">
<div>$ npm install unexpected-fs</div>
</div><p>And then in your test suite:</p>
<div class="code lang-javascript">
<div><span style="color: #a71d5d">var</span> expect <span style="color: #a71d5d">=</span> <span style="color: #000000">require</span><span style="color: #000000">(</span><span style="color: #df5000">'unexpected'</span><span style="color: #000000">).</span><span style="color: #000000">clone</span><span style="color: #000000">()</span></div>
<div> <span style="color: #000000">.</span><span style="color: #000000">use</span><span style="color: #000000">(</span><span style="color: #000000">require</span><span style="color: #000000">(</span><span style="color: #df5000">'unexpected-fs'</span><span style="color: #000000">));</span></div>
</div><p>For plugins that work in the browser, you'll either need to add an extra <code><script></code>, or
use browserify or a script loader instead of the Common.js <code>require</code> in the above example.
Please consult the documentation for each individual plugin.</p>
<h2 id="caveats-with-plugins-that-depend-on-other-plugins">Caveats with plugins that depend on other plugins</h2>
<p>The unexpected-express, unexpected-mitm, and unexpected-http plugins all depend
on unexpected-messy being available. If you use more than one of these in the same
test suite, it's important that only one version of unexpected-messy is installed.</p>
<p>All three plugins list <code>unexpected-messy</code> under both <code>peerDependencies</code> and <code>dependencies</code>
in their package.json. This strategy is carefully thought out to be forward compatible
with how <code>peerDependencies</code> work with npm 3. Unfortunately, users of npm 1 and 2 will
sometimes be in for a bit of a rough ride.</p>
<p>Unexpected's <a href="/api/use/">use method</a> will throw an error if you install two different
versions of unexpected-messy, so there's a stop gap that prevents <code>expect</code> from
ending up in a broken state. Still, recovering from that error condition or an
<code>EPEERINVALID</code> error can be tricky. We recommend trying the following:</p>
<ol>
<li>Upgrade to <code>npm 3</code>, then remove the <code>node_modules</code> folder and run a fresh <code>npm install</code>.</li>
<li>If you're stuck on a previous npm version, you should still try to remove <code>node_modules</code>
and run a fresh <code>npm install</code>.</li>
<li>If that doesn't work, upgrade unexpected and the plugins you're using to the newest
versions at once. The newest versions should be using the same version of
unexpected-messy, which will resolve the problem in most cases.</li>
</ol>
<h2 id="mixing-plugins">Mixing plugins</h2>
<p>All of these plugins should be able coexist in the same Unexpected instance and
compose well together. For instance, you can grab a few and assert that an express
app serves an HTML response body that contains a yellow <code><div></code>:</p>
<div class="code lang-javascript">
<div><span style="color: #a71d5d">var</span> expect <span style="color: #a71d5d">=</span> <span style="color: #000000">require</span><span style="color: #000000">(</span><span style="color: #df5000">'unexpected'</span><span style="color: #000000">).</span><span style="color: #000000">clone</span><span style="color: #000000">()</span></div>
<div> <span style="color: #000000">.</span><span style="color: #000000">use</span><span style="color: #000000">(</span><span style="color: #000000">require</span><span style="color: #000000">(</span><span style="color: #df5000">'unexpected-express'</span><span style="color: #000000">))</span></div>
<div> <span style="color: #000000">.</span><span style="color: #000000">use</span><span style="color: #000000">(</span><span style="color: #000000">require</span><span style="color: #000000">(</span><span style="color: #df5000">'unexpected-dom'</span><span style="color: #000000">))</span></div>
<div> <span style="color: #000000">.</span><span style="color: #000000">use</span><span style="color: #000000">(</span><span style="color: #000000">require</span><span style="color: #000000">(</span><span style="color: #df5000">'unexpected-color'</span><span style="color: #000000">));</span></div>
<div> </div>
<div><span style="color: #a71d5d">var</span> app <span style="color: #a71d5d">=</span> <span style="color: #000000">require</span><span style="color: #000000">(</span><span style="color: #df5000">'express'</span><span style="color: #000000">)()</span></div>
<div> <span style="color: #000000">.</span><span style="color: #a71d5d">get</span><span style="color: #000000">(</span><span style="color: #df5000">'/myPage'</span><span style="color: #000000">,</span> <span style="color: #a71d5d">function</span> <span style="color: #000000">(</span>req<span style="color: #000000">,</span> res<span style="color: #000000">,</span> next<span style="color: #000000">)</span> <span style="color: #000000">{</span></div>
<div> res<span style="color: #000000">.</span><span style="color: #000000">send</span><span style="color: #000000">(</span><span style="color: #df5000">'<html><body><div style="color: #ff0">Hey!</div></body></html>'</span><span style="color: #000000">);</span></div>
<div> <span style="color: #000000">});</span></div>
<div> </div>
<div><span style="color: #000000">it</span><span style="color: #000000">(</span><span style="color: #df5000">'should deliver something pretty'</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> <span style="color: #000000">expect</span><span style="color: #000000">(</span>app<span style="color: #000000">,</span> <span style="color: #df5000">'to yield exchange'</span><span style="color: #000000">,</span> <span style="color: #000000">{</span></div>
<div> request<span style="color: #000000">:</span> <span style="color: #df5000">'GET /myPage'</span><span style="color: #000000">,</span></div>
<div> response<span style="color: #000000">:</span> <span style="color: #000000">{</span></div>
<div> headers<span style="color: #000000">:</span> <span style="color: #000000">{</span> <span style="color: #df5000">'Content-Type'</span><span style="color: #000000">:</span> <span style="color: #df5000">'text/html; charset=utf-8'</span> <span style="color: #000000">},</span></div>
<div> body<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">'when parsed as HTML'</span><span style="color: #000000">,</span> <span style="color: #df5000">'queried for first'</span><span style="color: #000000">,</span> <span style="color: #df5000">'div'</span><span style="color: #000000">,</span> <span style="color: #df5000">'to satisfy'</span><span style="color: #000000">,</span> <span style="color: #000000">{</span></div>
<div> attributes<span style="color: #000000">:</span> <span style="color: #000000">{</span></div>
<div> style<span style="color: #000000">:</span> <span style="color: #000000">{</span></div>
<div> color<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">'to be colored'</span><span style="color: #000000">,</span> <span style="color: #df5000">'yellow'</span><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><span style="color: #000000">});</span></div>
</div><p>Or you could assert that a node.js readable stream outputs an image that's at most
10% different from a reference image:</p>
<div class="code lang-javascript">
<div><span style="color: #a71d5d">var</span> expect <span style="color: #a71d5d">=</span> <span style="color: #000000">require</span><span style="color: #000000">(</span><span style="color: #df5000">'unexpected'</span><span style="color: #000000">).</span><span style="color: #000000">clone</span><span style="color: #000000">()</span></div>
<div> <span style="color: #000000">.</span><span style="color: #000000">use</span><span style="color: #000000">(</span><span style="color: #000000">require</span><span style="color: #000000">(</span><span style="color: #df5000">'unexpected-stream'</span><span style="color: #000000">))</span></div>
<div> <span style="color: #000000">.</span><span style="color: #000000">use</span><span style="color: #000000">(</span><span style="color: #000000">require</span><span style="color: #000000">(</span><span style="color: #df5000">'unexpected-image'</span><span style="color: #000000">))</span></div>
<div> <span style="color: #000000">.</span><span style="color: #000000">use</span><span style="color: #000000">(</span><span style="color: #000000">require</span><span style="color: #000000">(</span><span style="color: #df5000">'unexpected-resemble'</span><span style="color: #000000">));</span></div>
<div> </div>
<div><span style="color: #000000">it</span><span style="color: #000000">(</span><span style="color: #df5000">'should spew out the expected image'</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> myStream <span style="color: #a71d5d">=</span> <span style="color: #000000">require</span><span style="color: #000000">(</span><span style="color: #df5000">'fs'</span><span style="color: #000000">).</span><span style="color: #000000">createReadStream</span><span style="color: #000000">(</span><span style="color: #df5000">'foo.png'</span><span style="color: #000000">);</span></div>
<div> </div>
<div> <span style="color: #a71d5d">return</span> <span style="color: #000000">expect</span><span style="color: #000000">(</span></div>
<div> myStream<span style="color: #000000">,</span></div>
<div> <span style="color: #df5000">'to yield output satisfying'</span><span style="color: #000000">,</span></div>
<div> expect<span style="color: #000000">.</span><span style="color: #000000">it</span><span style="color: #000000">(</span><span style="color: #df5000">'to resemble'</span><span style="color: #000000">,</span> <span style="color: #df5000">'bar.png'</span><span style="color: #000000">,</span> <span style="color: #000000">{</span></div>
<div> mismatchPercentage<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">'to be less than'</span><span style="color: #000000">,</span> <span style="color: #0086b3">10</span><span style="color: #000000">)</span></div>
<div> <span style="color: #000000">}).</span><span style="color: #000000">and</span><span style="color: #000000">(</span><span style="color: #df5000">'to have metadata satisfying'</span><span style="color: #000000">,</span> <span style="color: #000000">{</span></div>
<div> format<span style="color: #000000">:</span> <span style="color: #df5000">'PNG'</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>
<a class="github-ribbon" href="https://github.com/unexpectedjs/unexpected"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://camo.githubusercontent.com/a6677b08c955af8400f44c6298f40e7d19cc5b2d/68747470733a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f677261795f3664366436642e706e67" alt="Fork me on GitHub" data-canonical-src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png"></a>
</div>
<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>