SuperOak

HTTP assertions for Deno’s Oak web framework made easy via SuperDeno.

Table of Contents

• Table of Contents
• About
• Installation
• Example
• Documentation
• API
• FAQs
  • Property 'get' does not exist on type 'Promise<SuperDeno>' error
  • Request has been terminated error
• Contributing
• License

About

This module aims to provide a high-level abstraction for testing HTTP in Deno’s Oak web framework. This is a wrapper compatibility layer around SuperDeno to reduce some of the boilerplate needed to setup Oak integration + functional tests.

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 SuperOak straight into your project:

import { superoak } from "https://deno.land/x/superoak/mod.ts";

SuperOak is also available on nest.land, a package registry for Deno on the Blockchain.

Note: Some 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/superoak@4.8.1/mod.ts.

Example

You may pass a url string (for an already running Oak server), or an Oak Application object to superoak() - when passing an Oak Application, SuperOak will automatically handle the creation of a server, binding to a free ephemeral port and closing of the server on a call to .end().

SuperOak works with any Deno test framework. Here’s an example with Deno’s built-in test framework.

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

const router = new Router();
router.get("/", (ctx) => {
  ctx.response.body = "Hello Deno!";
});
router.post("/user", (ctx) => {
  ctx.response.body = "Post!";
});

const app = new Application();
app.use(router.routes());
app.use(router.allowedMethods());

// Send simple GET request
Deno.test("it should support the Oak framework", async () => {
  const request = await superoak(app);
  await request.get("/").expect("Hello Deno!");
});

// Custom requests can be built with the superagent API
// https://visionmedia.github.io/superagent/#post--put-requests.
Deno.test("it should allow post requests", async () => {
  const request = await superoak(app);
  await request
    .post("/user")
    .set("Content-Type", "application/json")
    .send('{"name":"superoak"}')
    .expect(200);
});

Save the above to a file demo.test.ts and test it using deno test --allow-net demo.test.ts.

For further examples, see the SuperOak examples, tests or the SuperDeno examples for inspiration.

Documentation

• SuperOak Type Docs
• SuperOak Deno Docs
• SuperOak Examples
• License
• Changelog

API

Please refer to the SuperDeno API and SuperAgent API.

FAQs

Property 'get' does not exist on type 'Promise<SuperDeno>' error

Unlike SuperDeno, superoak() returns a promise which will need to be awaited before you can call any method such as .get("/").

// ✅ works
Deno.test("it will allow you to make assertions if you await it", async () => {
  const request = await superoak(app);
  await request.get("/").expect(200).expect("Hello Deno!");
});

// ❌ won't work
Deno.test("it will allow you to make assertions if you await it", async () => {
  const request = superoak(app);
  await request.get("/").expect(200).expect("Hello Deno!"); // Boom 💥 `Property 'get' does not exist on type 'Promise<SuperDeno>'`
});

Request has been terminated error

Unlike SuperDeno, you cannot re-use SuperOak instances. If you try you will encounter an error similar to below:

Error: Request has been terminated
Possible causes: the network is offline, Origin is not allowed by Access-Control-Allow-Origin, the page is being unloaded, etc.
    at Test.Request.crossDomainError
    at XMLHttpRequestSham.xhr.onreadystatechange
    ...

This is because SuperOak instances automatically close the underlying Oak server once the assertion chain has completed.

Instead you should make all of your assertions on a single SuperOak instance, or create a new SuperOak instance for subsequent assertions like below:

// ✅ works
Deno.test(
  "it will allow you to make multiple assertions on one SuperOak instance",
  async () => {
    const request = await superoak(app);
    await request.get("/").expect(200).expect("Hello Deno!");
  }
);

// ✅ works
Deno.test(
  "it will allow you to re-use the Application for another SuperOak instance",
  async () => {
    const request1 = await superoak(app);
    await request1.get("/").expect(200);

    const request2 = await superoak(app);
    await request2.get("/").expect("Hello Deno!");
  }
);

// ❌ won't work
Deno.test(
  "it will throw an error if try to re-use a SuperOak instance",
  async () => {
    const request = await superoak(app);
    await request.get("/").expect(200);
    await request.get("/").expect("Hello Deno!"); // Boom 💥 `Error: Request has been terminated`
  }
);

Contributing

Contributing guide

License

SuperOak is licensed under the MIT License.

Icon designed and created by Hannah Morten.