Popular
Latest
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416<!doctype html><html class="default no-js"><head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <title>superdeno</title> <meta name="description" content="Documentation for superdeno"> <meta name="viewport" content="width=device-width, initial-scale=1"> <link rel="stylesheet" href="assets/css/main.css"></head><body><header> <div class="tsd-page-toolbar"> <div class="container"> <div class="table-wrap"> <div class="table-cell" id="tsd-search" data-index="assets/js/search.json" data-base="."> <div class="field"> <label for="tsd-search-field" class="tsd-widget search no-caption">Search</label> <input id="tsd-search-field" type="text" /> </div> <ul class="results"> <li class="state loading">Preparing search index...</li> <li class="state failure">The search index is not available</li> </ul> <a href="index.html" class="title">superdeno</a> </div> <div class="table-cell" id="tsd-widgets"> <div id="tsd-filter"> <a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a> <div class="tsd-filter-group"> <div class="tsd-select" id="tsd-filter-visibility"> <span class="tsd-select-label">All</span> <ul class="tsd-select-list"> <li data-value="public">Public</li> <li data-value="protected">Public/Protected</li> <li data-value="private" class="selected">All</li> </ul> </div> <input type="checkbox" id="tsd-filter-inherited" checked /> <label class="tsd-widget" for="tsd-filter-inherited">Inherited</label> <input type="checkbox" id="tsd-filter-only-exported" /> <label class="tsd-widget" for="tsd-filter-only-exported">Only exported</label> </div> </div> <a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a> </div> </div> </div> </div> <div class="tsd-page-title"> <div class="container"> <ul class="tsd-breadcrumb"> <li> <a href="globals.html">Globals</a> </li> </ul> <h1>superdeno</h1> </div> </div></header><div class="container container-main"> <div class="row"> <div class="col-8 col-content"> <div class="tsd-panel tsd-typography"> <p align="center"> <a href="https://www.linkedin.com/in/hannah-morten-b1218017a/"><img height="200" style="height: 200px;" src="https://github.com/cmorten/superdeno/raw/main/.github/superdeno.png" alt="Super Deno standing in the rain at night – stoically facing the dark battle that is software engineering"></a> <h1 align="center">SuperDeno</h1> </p> <p align="center"> HTTP assertions for Deno made easy via <a href="https://github.com/visionmedia/superagent">superagent</a>. </p> <p align="center"> <a href="https://github.com/cmorten/superdeno/tags/"><img src="https://img.shields.io/github/tag/cmorten/superdeno" alt="Current version" /></a> <img src="https://github.com/cmorten/superdeno/workflows/Test/badge.svg" alt="Current test status" /> <a href="https://doc.deno.land/https/deno.land/x/superdeno/mod.ts"><img src="https://doc.deno.land/badge.svg" alt="SuperDeno docs" /></a> <a href="http://makeapullrequest.com"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs are welcome" /></a> <a href="https://github.com/cmorten/superdeno/issues/"><img src="https://img.shields.io/github/issues/cmorten/superdeno" alt="SuperDeno issues" /></a> <img src="https://img.shields.io/github/stars/cmorten/superdeno" alt="SuperDeno stars" /> <img src="https://img.shields.io/github/forks/cmorten/superdeno" alt="SuperDeno forks" /> <img src="https://img.shields.io/github/license/cmorten/superdeno" alt="SuperDeno license" /> <a href="https://GitHub.com/cmorten/superdeno/graphs/commit-activity"><img src="https://img.shields.io/badge/Maintained%3F-yes-green.svg" alt="SuperDeno is maintained" /></a> </p> <p align="center"> <a href="https://deno.land/x/superdeno"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fdeno-visualizer.danopia.net%2Fshields%2Flatest-version%2Fx%2Fsuperdeno%2Fmod.ts" alt="SuperDeno latest /x/ version" /></a> <a href="https://github.com/denoland/deno/blob/main/Releases.md"><img src="https://img.shields.io/badge/deno-^1.40.2-brightgreen?logo=deno" alt="Minimum supported Deno version" /></a> <a href="https://deno-visualizer.danopia.net/dependencies-of/https/deno.land/x/superdeno/mod.ts"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fdeno-visualizer.danopia.net%2Fshields%2Fdep-count%2Fx%2Fsuperdeno%2Fmod.ts" alt="SuperDeno dependency count" /></a> <a href="https://deno-visualizer.danopia.net/dependencies-of/https/deno.land/x/superdeno/mod.ts"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fdeno-visualizer.danopia.net%2Fshields%2Fupdates%2Fx%2Fsuperdeno%2Fmod.ts" alt="SuperDeno dependency outdatedness" /></a> <a href="https://deno-visualizer.danopia.net/dependencies-of/https/deno.land/x/superdeno/mod.ts"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fdeno-visualizer.danopia.net%2Fshields%2Fcache-size%2Fx%2Fsuperdeno%2Fmod.ts" alt="SuperDeno cached size" /></a> </p> <hr> <a href="#table-of-contents" id="table-of-contents" style="color: inherit; text-decoration: none;"> <h2>Table of Contents</h2> </a> <ul> <li><a href="#getting-started">Getting Started</a></li> <li><a href="#about">About</a></li> <li><a href="#installation">Installation</a></li> <li><a href="#examples">Examples</a></li> <li><a href="#documentation">Documentation</a></li> <li><a href="#api">API</a></li> <li><a href="#notes">Notes</a></li> <li><a href="#contributing">Contributing</a></li> <li><a href="#license">License</a></li> </ul> <a href="#getting-started" id="getting-started" style="color: inherit; text-decoration: none;"> <h2>Getting Started</h2> </a> <pre><code class="language-ts"><span class="hljs-keyword">import</span> { superdeno } <span class="hljs-keyword">from</span> <span class="hljs-string">"https://deno.land/x/superdeno/mod.ts"</span>;<span class="hljs-keyword">import</span> { opine } <span class="hljs-keyword">from</span> <span class="hljs-string">"https://deno.land/x/opine@2.3.4/mod.ts"</span>;
<span class="hljs-keyword">const</span> app = opine();
app.get(<span class="hljs-string">"/user"</span>, <span class="hljs-function">(<span class="hljs-params">req, res</span>) =></span> { res.setStatus(<span class="hljs-number">200</span>).json({ <span class="hljs-attr">name</span>: <span class="hljs-string">"Deno"</span> });});
superdeno(app) .get(<span class="hljs-string">"/user"</span>) .expect(<span class="hljs-string">"Content-Type"</span>, <span class="hljs-regexp">/json/</span>) .expect(<span class="hljs-string">"Content-Length"</span>, <span class="hljs-string">"15"</span>) .expect(<span class="hljs-number">200</span>) .end(<span class="hljs-function">(<span class="hljs-params">err, res</span>) =></span> { <span class="hljs-keyword">if</span> (err) <span class="hljs-keyword">throw</span> err; });</code></pre> <p>Looking to test an Oak web server? Check out <a href="https://github.com/cmorten/superoak">SuperOak</a>!</p> <a href="#about" id="about" style="color: inherit; text-decoration: none;"> <h2>About</h2> </a> <p>The motivation of this module is to provide a high-level abstraction for testing HTTP in Deno, while still allowing you to drop down to the lower-level API provided by <a href="https://visionmedia.github.io/superagent/">superagent</a>.</p> <a href="#installation" id="installation" style="color: inherit; text-decoration: none;"> <h2>Installation</h2> </a> <p>This is a <a href="https://deno.land/">Deno</a> module available to import direct from this repo and via the <a href="https://deno.land/x">Deno Registry</a>.</p> <p>Before importing, <a href="https://deno.land/#installation">download and install Deno</a>.</p> <p>You can then import SuperDeno straight into your project:</p> <pre><code class="language-ts"><span class="hljs-keyword">import</span> { superdeno } <span class="hljs-keyword">from</span> <span class="hljs-string">"https://deno.land/x/superdeno/mod.ts"</span>;</code></pre> <p>SuperDeno is also available on <a href="https://nest.land/package/superdeno">nest.land</a>, a package registry for Deno on the Blockchain.</p> <blockquote> <p>Note: All examples in this README are using the unversioned form of the import URL. In production you should always use the versioned import form such as <code>https://deno.land/x/superdeno@4.9.0/mod.ts</code>.</p> </blockquote> <a href="#examples" id="examples" style="color: inherit; text-decoration: none;"> <h2>Examples</h2> </a> <p>You may pass a url string, <a href="https://doc.deno.land/https/deno.land/std/http/mod.ts#Server"><code>http.Server</code></a>, a request handling function, or an object that implements an <code>app.listen()</code> method (which mirrors the <a href="https://doc.deno.land/https/deno.land/std/http/mod.ts#serve"><code>http.serve</code></a> interface) to <code>superdeno()</code> - if SuperDeno identifies that a server is not already listening for connections, then one is bound to an ephemeral port for you so there is no need to keep track of ports.</p> <p>SuperDeno works with any Deno test framework. Here's an example with Deno's built-in test framework, note how you can pass <code>done</code> straight to any of the <code>.expect()</code> calls:</p> <pre><code class="language-ts">Deno.test(<span class="hljs-string">"GET /user responds with json"</span>, <span class="hljs-keyword">async</span> () => { <span class="hljs-keyword">await</span> superdeno(app) .get(<span class="hljs-string">"/user"</span>) .set(<span class="hljs-string">"Accept"</span>, <span class="hljs-string">"application/json"</span>) .expect(<span class="hljs-string">"Content-Type"</span>, <span class="hljs-regexp">/json/</span>) .expect(<span class="hljs-number">200</span>);});</code></pre> <p>Here's an example of SuperDeno working with the Opine web framework:</p> <pre><code class="language-ts"><span class="hljs-keyword">import</span> { superdeno } <span class="hljs-keyword">from</span> <span class="hljs-string">"https://deno.land/x/superdeno/mod.ts"</span>;<span class="hljs-keyword">import</span> { opine } <span class="hljs-keyword">from</span> <span class="hljs-string">"https://deno.land/x/opine@2.3.4/mod.ts"</span>;<span class="hljs-keyword">import</span> { expect } <span class="hljs-keyword">from</span> <span class="hljs-string">"https://deno.land/x/expect@v0.4.0/mod.ts"</span>;
<span class="hljs-keyword">const</span> app = opine();
app.get(<span class="hljs-string">"/"</span>, <span class="hljs-function">(<span class="hljs-params">req, res</span>) =></span> { res.send(<span class="hljs-string">"Hello Deno!"</span>);});
Deno.test(<span class="hljs-string">"it should support regular expressions"</span>, <span class="hljs-keyword">async</span> () => { <span class="hljs-keyword">await</span> superdeno(app) .get(<span class="hljs-string">"/"</span>) .expect(<span class="hljs-string">"Content-Type"</span>, <span class="hljs-regexp">/^application/</span>) .catch(<span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { expect(err.message).toEqual( <span class="hljs-string">'expected "Content-Type" matching /^application/, got "text/html; charset=utf-8"'</span> ); });});</code></pre> <p>See more examples in the <a href="./test/superdeno.opine.test.ts">Opine test suite</a>.</p> <p>Here's an example of SuperDeno working with the Express web framework:</p> <pre><code class="language-ts"><span class="hljs-keyword">import</span> { superdeno } <span class="hljs-keyword">from</span> <span class="hljs-string">"https://deno.land/x/superdeno/mod.ts"</span>;<span class="hljs-comment">// @deno-types="npm:@types/express@^4.17"</span><span class="hljs-keyword">import</span> express <span class="hljs-keyword">from</span> <span class="hljs-string">"npm:express@4.18.2"</span>;<span class="hljs-keyword">import</span> { expect } <span class="hljs-keyword">from</span> <span class="hljs-string">"https://deno.land/x/expect@v0.4.0/mod.ts"</span>;
Deno.test(<span class="hljs-string">"it should support regular expressions"</span>, <span class="hljs-keyword">async</span> () => { <span class="hljs-keyword">const</span> app = express();
app.get(<span class="hljs-string">"/"</span>, <span class="hljs-function">(<span class="hljs-params">_req, res</span>) =></span> { res.send(<span class="hljs-string">"Hello Deno!"</span>); });
<span class="hljs-keyword">await</span> superdeno(app) .get(<span class="hljs-string">"/"</span>) .expect(<span class="hljs-string">"Content-Type"</span>, <span class="hljs-regexp">/^application/</span>) .catch(<span class="hljs-function">(<span class="hljs-params">err</span>) =></span> { expect(err.message).toEqual( <span class="hljs-string">'expected "Content-Type" matching /^application/, got "text/html; charset=utf-8"'</span> ); });});</code></pre> <p>See more examples in the <a href="./test/superdeno.express.test.ts">Express test suite</a>.</p> <p>Here's an example of SuperDeno working with the Oak web framework:</p> <pre><code class="language-ts"><span class="hljs-keyword">import</span> { superdeno } <span class="hljs-keyword">from</span> <span class="hljs-string">"https://deno.land/x/superdeno/mod.ts"</span>;<span class="hljs-keyword">import</span> { Application, Router } <span class="hljs-keyword">from</span> <span class="hljs-string">"https://deno.land/x/oak@v12.6.2/mod.ts"</span>;
<span class="hljs-keyword">const</span> router = <span class="hljs-keyword">new</span> Router();router.get(<span class="hljs-string">"/"</span>, <span class="hljs-function">(<span class="hljs-params">ctx</span>) =></span> { ctx.response.body = <span class="hljs-string">"Hello Deno!"</span>;});
<span class="hljs-keyword">const</span> app = <span class="hljs-keyword">new</span> Application();app.use(router.routes());app.use(router.allowedMethods());
Deno.test(<span class="hljs-string">"it should support the Oak framework"</span>, <span class="hljs-function">() =></span> { <span class="hljs-keyword">const</span> controller = <span class="hljs-keyword">new</span> AbortController(); <span class="hljs-keyword">const</span> { signal } = controller;
app.addEventListener(<span class="hljs-string">"listen"</span>, <span class="hljs-keyword">async</span> ({ hostname, port, secure }) => { <span class="hljs-keyword">const</span> protocol = secure ? <span class="hljs-string">"https"</span> : <span class="hljs-string">"http"</span>; <span class="hljs-keyword">const</span> url = <span class="hljs-string">`<span class="hljs-subst">${protocol}</span>://<span class="hljs-subst">${hostname}</span>:<span class="hljs-subst">${port}</span>`</span>;
<span class="hljs-keyword">await</span> superdeno(url) .get(<span class="hljs-string">"/"</span>) .expect(<span class="hljs-string">"Hello Deno!"</span>, <span class="hljs-function">() =></span> { controller.abort(); }); });
<span class="hljs-keyword">await</span> app.listen({ <span class="hljs-attr">port</span>: <span class="hljs-number">0</span>, signal });});</code></pre> <p>See more examples in the <a href="./test/superdeno.oak.test.ts">Oak test suite</a>.</p> <p>If you are using the <a href="https://github.com/oakserver/oak/">Oak</a> web framework then it is recommended that you use the specialized <a href="https://github.com/cmorten/superoak">SuperOak</a> assertions library for reduced bootstrapping.</p> <p>If you don't need to test the server setup side of your Oak application, or you are making use of the <code>app.handle()</code> method (for example for serverless apps) then you can write slightly less verbose tests for Oak:</p> <pre><code class="language-ts"><span class="hljs-keyword">import</span> { Application, Router } <span class="hljs-keyword">from</span> <span class="hljs-string">"https://deno.land/x/oak@v12.6.2/mod.ts"</span>;<span class="hljs-keyword">import</span> { superdeno } <span class="hljs-keyword">from</span> <span class="hljs-string">"https://deno.land/x/superdeno/mod.ts"</span>;
<span class="hljs-keyword">const</span> router = <span class="hljs-keyword">new</span> Router();
router.get(<span class="hljs-string">"/"</span>, <span class="hljs-function">(<span class="hljs-params">ctx</span>) =></span> { ctx.response.body = <span class="hljs-string">"Hello Deno!"</span>;});
<span class="hljs-keyword">const</span> app = <span class="hljs-keyword">new</span> Application();app.use(router.routes());app.use(router.allowedMethods());
Deno.test( <span class="hljs-string">"it should support the Oak framework `app.handle` method"</span>, <span class="hljs-keyword">async</span> () => { <span class="hljs-comment">/** * Note that we have to bind `app` to the function otherwise `app.handle` * doesn't preserve the `this` context from `app`. */</span> <span class="hljs-keyword">await</span> superdeno(app.handle.bind(app)).get(<span class="hljs-string">"/"</span>).expect(<span class="hljs-string">"Hello Deno!"</span>); });</code></pre> <p>In this case, SuperDeno handles the setup and closing of the server for you, so you can focus on just testing your middleware.</p> <p>For further examples, see the <a href="./test">tests</a> or the <a href="https://github.com/visionmedia/supertest#example">supertest examples</a> for inspiration.</p> <a href="#documentation" id="documentation" style="color: inherit; text-decoration: none;"> <h2>Documentation</h2> </a> <ul> <li><a href="https://doc.deno.land/https/deno.land/x/superdeno/mod.ts">SuperDeno Deno Docs</a></li> <li><a href="https://cmorten.github.io/superdeno/">SuperDeno Type Docs</a></li> <li><a href="https://github.com/cmorten/superdeno/blob/main/LICENSE.md">License</a></li> <li><a href="https://github.com/cmorten/superdeno/blob/main/.github/CHANGELOG.md">Changelog</a></li> </ul> <a href="#api" id="api" style="color: inherit; text-decoration: none;"> <h2>API</h2> </a> <p>You may use any <a href="http://github.com/visionmedia/superagent">superagent</a> client (browser) methods and perform assertions in the <code>.end()</code> callback for lower-level needs.</p> <a href="#expectstatus-fn" id="expectstatus-fn" style="color: inherit; text-decoration: none;"> <h3>.expect(status[, fn])</h3> </a> <p>Assert response <code>status</code> code.</p> <a href="#expectstatus-body-fn" id="expectstatus-body-fn" style="color: inherit; text-decoration: none;"> <h3>.expect(status, body[, fn])</h3> </a> <p>Assert response <code>status</code> code and <code>body</code>.</p> <a href="#expectbody-fn" id="expectbody-fn" style="color: inherit; text-decoration: none;"> <h3>.expect(body[, fn])</h3> </a> <p>Assert response <code>body</code> text with a string, regular expression, or parsed body object.</p> <a href="#expectfield-value-fn" id="expectfield-value-fn" style="color: inherit; text-decoration: none;"> <h3>.expect(field, value[, fn])</h3> </a> <p>Assert header <code>field</code> <code>value</code> with a string or regular expression.</p> <a href="#expectfunctionres-" id="expectfunctionres-" style="color: inherit; text-decoration: none;"> <h3>.expect(function(res) {})</h3> </a> <p>Pass a custom assertion function. It'll be given the response object to check. If the check fails, throw an error.</p> <pre><code class="language-ts"><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">hasPreviousAndNextKeys</span>(<span class="hljs-params">res</span>) </span>{ <span class="hljs-keyword">if</span> (!(<span class="hljs-string">"next"</span> <span class="hljs-keyword">in</span> res.parsedBody)) <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Error</span>(<span class="hljs-string">"missing next key"</span>); <span class="hljs-keyword">if</span> (!(<span class="hljs-string">"prev"</span> <span class="hljs-keyword">in</span> res.parsedBody)) <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Error</span>(<span class="hljs-string">"missing prev key"</span>);}
<span class="hljs-keyword">await</span> superdeno(app).get(<span class="hljs-string">"/"</span>).expect(hasPreviousAndNextKeys);</code></pre> <a href="#endfn" id="endfn" style="color: inherit; text-decoration: none;"> <h3>.end(fn)</h3> </a> <p>Perform the request and invoke <code>fn(err, res)</code>.</p> <a href="#notes" id="notes" style="color: inherit; text-decoration: none;"> <h2>Notes</h2> </a> <p>This is a port of <a href="https://github.com/visionmedia/supertest">supertest</a> to TypeScript + Deno, which fulfills this motivation currently for Node. This module also includes a XHR sham so <a href="https://visionmedia.github.io/superagent/">superagent</a> client mode can be used directly.</p> <a href="#contributing" id="contributing" style="color: inherit; text-decoration: none;"> <h2>Contributing</h2> </a> <p><a href="https://github.com/cmorten/superdeno/blob/main/.github/CONTRIBUTING.md">Contributing guide</a></p> <hr> <a href="#license" id="license" style="color: inherit; text-decoration: none;"> <h2>License</h2> </a> <p>This library is a port of <a href="https://github.com/visionmedia/supertest">supertest</a> whose license and copyrights are available at <a href="./SUPERTEST_LICENSE.md">SUPERTEST_LICENSE</a> in the root of this repository, and covers all files within the <a href="./src">source</a> directory which detail that the file is a port.</p> <p>SuperDeno is licensed under the <a href="./LICENSE.md">MIT License</a>.</p> <p>Icon designed and created by <a href="https://www.linkedin.com/in/hannah-morten-b1218017a/">Hannah Morten</a>.</p> </div> </div> <div class="col-4 col-menu menu-sticky-wrap menu-highlight"> <nav class="tsd-navigation primary"> <ul> <li class="globals "> <a href="globals.html"><em>Globals</em></a> </li> <li class=" tsd-kind-module"> <a href="modules/_close_.html">"close"</a> </li> <li class=" tsd-kind-module"> <a href="modules/_superagent_.html">"superagent"</a> </li> <li class=" tsd-kind-module"> <a href="modules/_superdeno_.html">"superdeno"</a> </li> <li class=" tsd-kind-module"> <a href="modules/_test_.html">"test"</a> </li> <li class=" tsd-kind-module"> <a href="modules/_types_.html">"types"</a> </li> <li class=" tsd-kind-module"> <a href="modules/_utils_.html">"utils"</a> </li> </ul> </nav> <nav class="tsd-navigation secondary menu-sticky"> <ul class="before-current"> </ul> </nav> </div> </div></div><footer class="with-border-bottom"> <div class="container"> <h2>Legend</h2> <div class="tsd-legend-group"> <ul class="tsd-legend"> <li class="tsd-kind-variable"><span class="tsd-kind-icon">Variable</span></li> <li class="tsd-kind-function"><span class="tsd-kind-icon">Function</span></li> <li class="tsd-kind-type-alias"><span class="tsd-kind-icon">Type alias</span></li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-interface"><span class="tsd-kind-icon">Interface</span></li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-class"><span class="tsd-kind-icon">Class</span></li> </ul> </div> </div></footer><div class="container tsd-generator"> <p>Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></div><div class="overlay"></div><script src="assets/js/main.js"></script></body></html>