SuperDeno

HTTP assertions for Deno made easy via superagent.

Table of Contents

• Getting Started
• About
• Installation
• Example
• Documentation
• API
• Notes
• Contributing
• License

Getting Started

import { superdeno } from "https://deno.land/x/superdeno@main/mod.ts";
import { opine } from "https://deno.land/x/opine@0.8.0/mod.ts";

const app = opine();

app.get("/user", (req, res) => {
  res.setStatus(200).json({ name: "Deno" });
});

superdeno(app)
  .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@main/mod.ts";

If you want to use a specific version of SuperDeno, just modify the import url to contain the version:

import { superdeno } from "https://deno.land/x/superdeno@0.3.0/mod.ts";

Or if you want to use a specific commit of SuperDeno, just modify the import url to contain the commit hash:

import { superdeno } from "https://deno.land/x/superdeno@c21f8d6/mod.ts";

Example

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 Opine web framework:

import { opine } from "https://deno.land/x/opine@0.8.0/mod.ts";
import { expect } from "https://deno.land/x/expect@9effa6/mod.ts";

const app = opine();

app.get("/", (req, res) => {
  res.send("Hello Deno!");
});

Deno.test("it should support regular expressions", async () => {
  await superdeno(app)
    .get("/")
    .expect("Content-Type", /^application/)
    .end((err) => {
      expect(err.message).toEqual(
        'expected "Content-Type" matching /^application/, got "text/html; charset=utf-8"'
      );
    });
});

Here’s an example of SuperDeno working with the Oak web framework:

import { Application, Router } from "https://deno.land/x/oak@main/mod.ts";

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", () => {
  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 });
});

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 { Application, Router } from "https://deno.land/x/oak@main/mod.ts";

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

• SuperDeno Deno Docs
• SuperDeno Type Docs - Unavailable while awaiting GitHub’s support of alternatively named default branches.
• License
• Changelog

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.

.expect(body[, fn])

Assert response body text with a string, regular expression, or parsed body object.

.expect(field, value[, fn])

Assert header field value with a string or regular expression.

.expect(function(res) {})

Pass a custom assertion function. It’ll be given the response object to check. If the check fails, throw an error.

function hasPreviousAndNextKeys(res) {
  if (!("next" in res.parsedBody)) throw new Error("missing next key");
  if (!("prev" in res.parsedBody)) throw new Error("missing prev key");
}

await superdeno(app).get("/").expect(hasPreviousAndNextKeys);

.end(fn)

Perform the request and invoke fn(err, res).

Notes

This is a port (not fork) of supertest to TypeScript + Deno, which fulfills this motivation currently for Node. This module also includes a XHR sham so superagent client mode can be used directly.

Contributing

Contributing guide

License

This library is a port of supertest whose license and copyrights are available at SUPERTEST_LICENSE in the root of this repository, and covers all files within the source directory which detail that the file is a port.

SuperDeno is licensed under the MIT License.

Icon designed and created by Hannah Morten.