Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cmorten/superoak
HTTP assertions for Oak made easy via SuperDeno. 🐿 🦕
https://github.com/cmorten/superoak
assertions deno deno-doc http-assertions http-testing oak superdeno superoak supertest testing typescript
Last synced: 7 days ago
JSON representation
HTTP assertions for Oak made easy via SuperDeno. 🐿 🦕
- Host: GitHub
- URL: https://github.com/cmorten/superoak
- Owner: cmorten
- License: mit
- Created: 2020-05-31T09:10:20.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-01-28T18:58:09.000Z (9 months ago)
- Last Synced: 2024-10-01T08:33:02.670Z (about 1 month ago)
- Topics: assertions, deno, deno-doc, http-assertions, http-testing, oak, superdeno, superoak, supertest, testing, typescript
- Language: TypeScript
- Homepage: https://cmorten.github.io/superoak/
- Size: 547 KB
- Stars: 121
- Watchers: 4
- Forks: 8
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS.md
Awesome Lists containing this project
README
SuperOak
HTTP assertions for Deno's Oak web framework made easy via SuperDeno.
---
## Table of Contents
- [Table of Contents](#table-of-contents)
- [About](#about)
- [Installation](#installation)
- [Example](#example)
- [Documentation](#documentation)
- [API](#api)
- [FAQs](#faqs)
- [`Property 'get' does not exist on type 'Promise'`
error](#property-get-does-not-exist-on-type-promisesuperdeno-error)
- [`Request has been terminated` error](#request-has-been-terminated-error)
- [Contributing](#contributing)
- [License](#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](https://github.com/cmorten/superdeno) to reduce some of the
boilerplate needed to setup Oak integration + functional tests.
## Installation
This is a [Deno](https://deno.land/) module available to import direct from this
repo and via the [Deno Registry](https://deno.land/x).
Before importing, [download and install Deno](https://deno.land/#installation).
You can then import SuperOak straight into your project:
```ts
import { superoak } from "https://deno.land/x/superoak/mod.ts";
```
SuperOak is also available on [nest.land](https://nest.land/package/superoak), 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/[email protected]/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.
```ts
import { Application, Router } from "https://deno.land/x/[email protected]/mod.ts";
import { superoak } from "https://deno.land/x/[email protected]/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](https://github.com/cmorten/superoak/blob/main/examples/README.md),
[tests](https://github.com/cmorten/superoak/blob/main/test/superoak.test.ts)
or the
[SuperDeno examples](https://github.com/cmorten/superdeno#example) for
inspiration.
## Documentation
- [SuperOak Type Docs](https://cmorten.github.io/superoak/)
- [SuperOak Deno Docs](https://doc.deno.land/https/deno.land/x/superoak/mod.ts)
- [SuperOak Examples](https://github.com/cmorten/superoak/blob/main/examples/README.md)
- [License](https://github.com/cmorten/superoak/blob/main/LICENSE.md)
- [Changelog](https://github.com/cmorten/superoak/blob/main/.github/CHANGELOG.md)
## API
Please refer to the
[SuperDeno API](https://github.com/cmorten/superdeno#api) and
[SuperAgent API](https://visionmedia.github.io/superagent/).
## FAQs
### `Property 'get' does not exist on type 'Promise'` error
Unlike [SuperDeno](https://github.com/cmorten/superdeno), `superoak()`
returns a promise which will need to be awaited before you can call any method
such as `.get("/")`.
```ts
// ✅ 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'`
});
```
### `Request has been terminated` error
Unlike [SuperDeno](https://github.com/cmorten/superdeno), you cannot
re-use SuperOak instances. If you try you will encounter an error similar to
below:
```console
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:
```ts
// ✅ 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](https://github.com/cmorten/superoak/blob/main/.github/CONTRIBUTING.md)
---
## License
SuperOak is licensed under the [MIT License](./LICENSE.md).
Icon designed and created by
[Hannah Morten](https://www.linkedin.com/in/hannah-morten-b1218017a/).