Superdeno
Super-agent driven library for testing Deno HTTP servers.
Install / Use
/learn @cmorten/SuperdenoREADME
Now in maintenance mode: Deno has introduced Node and NPM compatability, consider using SuperTest itself in Deno!
import supertest from "npm:supertest";
SuperTest not working for you? Raise an issue on Deno and keep reading for SuperDeno usage :tada:
Table of Contents
Getting Started
import { superdeno } from "https://deno.land/x/superdeno/mod.ts";
const USER_ROUTE = new URLPattern({ pathname: "/user" });
function handler(req: Request): Response {
const match = USER_ROUTE.exec(req.url);
if (match) {
const body = JSON.stringify({ name: "Deno" });
return new Response(body, {
status: 200,
headers: {
"content-type": "application/json; charset=utf-8",
},
});
}
return new Response("Not found", {
status: 404,
});
}
const server = Deno.serve(handler);
superdeno(server)
.get("/user")
.expect("Content-Type", /json/)
.expect("Content-Length", "15")
.expect(200)
.end((err, res) => {
if (err) throw err;
});
Looking to test an Oak web server? Check out SuperOak!
About
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 superagent.
Installation
This is a Deno module available to import direct from this repo and via the Deno Registry.
Before importing, download and install Deno.
You can then import SuperDeno straight into your project:
import { superdeno } from "https://deno.land/x/superdeno/mod.ts";
SuperDeno is also available on nest.land, a package registry for Deno on the Blockchain.
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
https://deno.land/x/superdeno@5.0.1/mod.ts.
Examples
You may pass a url string,
http.Server, a
request handling function, or an object that implements an app.listen() method
(which mirrors the
http.serve
interface) to superdeno() - 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.
SuperDeno works with any Deno test framework. Here's an example with Deno's
built-in test framework, note how you can pass done straight to any of the
.expect() calls:
Deno.test("GET /user responds with json", async () => {
await superdeno(app)
.get("/user")
.set("Accept", "application/json")
.expect("Content-Type", /json/)
.expect(200);
});
Here's an example of SuperDeno working with the Express web framework:
import { superdeno } from "https://deno.land/x/superdeno/mod.ts";
// @deno-types="npm:@types/express@^4.17.22"
export { default as express } from "npm:express@4.21.2";
export { expect } from "https://deno.land/x/expect@v0.4.2/mod.ts";
Deno.test("it should support regular expressions", async () => {
const app = express();
app.get("/", (_req, res) => {
res.send("Hello Deno!");
});
await superdeno(app)
.get("/")
.expect("Content-Type", /^application/)
.catch((err) => {
expect(err.message).toEqual(
'expected "Content-Type" matching /^application/, got "text/html; charset=utf-8"'
);
});
});
See more examples in the Express test suite.
Here's an example of SuperDeno working with the Oak web framework:
import { superdeno } from "https://deno.land/x/superdeno/mod.ts";
import { Application, Router } from "jsr:@oak/oak@^17.1.4";
const router = new Router();
router.get("/", (ctx) => {
ctx.response.body = "Hello Deno!";
});
const app = new Application();
app.use(router.routes());
app.use(router.allowedMethods());
Deno.test("it should support the Oak framework", async () => {
const controller = new AbortController();
const { signal } = controller;
app.addEventListener("listen", async ({ hostname, port, secure }) => {
const protocol = secure ? "https" : "http";
const url = `${protocol}://${hostname}:${port}`;
await superdeno(url)
.get("/")
.expect("Hello Deno!", () => {
controller.abort();
});
});
await app.listen({ port: 0, signal });
});
See more examples in the Oak test suite.
If you are using the Oak web framework then it is recommended that you use the specialized SuperOak assertions library for reduced bootstrapping.
If you don't need to test the server setup side of your Oak application, or you
are making use of the app.handle() method (for example for serverless apps)
then you can write slightly less verbose tests for Oak:
import { superdeno } from "https://deno.land/x/superdeno/mod.ts";
import { Application, Router } from "jsr:@oak/oak@^17.1.4";
const router = new Router();
router.get("/", (ctx) => {
ctx.response.body = "Hello Deno!";
});
const app = new Application();
app.use(router.routes());
app.use(router.allowedMethods());
Deno.test(
"it should support the Oak framework `app.handle` method",
async () => {
/**
* Note that we have to bind `app` to the function otherwise `app.handle`
* doesn't preserve the `this` context from `app`.
*/
await superdeno(app.handle.bind(app)).get("/").expect("Hello Deno!");
}
);
In this case, SuperDeno handles the setup and closing of the server for you, so you can focus on just testing your middleware.
For further examples, see the tests or the supertest examples for inspiration.
Documentation
API
You may use any superagent client
(browser) methods and perform assertions in the .end() callback for
lower-level needs.
.expect(status[, fn])
Assert response status code.
.expect(status, body[, fn])
Assert response status code and body.
