eddienubes / sagetest

🧪 Neat and streamlined library for testing node.js HTTP servers.

---

Neat and streamlined testing library for node.js HTTP servers powered by undici.

Documentation | Getting Started

🌟 Features

• Yes! This is a reference to my favourite Valorant character, Sage.
• TypeScript friendly, exposes both ESM and CJS modules.
• Built on top of undici for maximum performance.
• Provides easy-to-use, supertest-like API.
• Supports a dedicated test server to reduce the number of instances spawned during testing.
• Supports Node.js v18.0 and above.
• No unnecessary third-party dependencies.
• Automatically handles cookie parsing.

🚀 Getting Started

npm install -D sagetest
yarn add -D sagetest
pnpm add -D sagetest

Sagetest supports Node.js v18.0 and above out of the box. Even though undici's support starts from Node.js v18. This is possible due to one-liner polyfills for WebAPI Readable/WritableStreams and Blob, which were not available at that time globally (globalThis).

🎬 Sagetest in action

There are several other methods which you can find in the API documentation. In general, the usage experience should resemble that of supertest.

Express Endpoint Testing

Example usage of auth method to set Basic Auth header based on username and password.

import { request } from '../src/index.js';

// Just a plain express app
const response = await request(app).get('/').auth('user', 'pass');

expect(response).toEqual({
  body: {
    message: 'I love my mom!',
    requestHeaders: {
      authorization: 'Basic dXNlcjpwYXNz',
      connection: 'close',
      host: expect.stringContaining('localhost')
    }
  },
  cookies: {
    'sweet-cookie': {
      httpOnly: true,
      path: '/',
      value: 'choco'
    }
  },
  error: false,
  headers: {
    connection: 'close',
    'content-length': '130',
    'content-type': 'application/json; charset=utf-8',
    date: expect.any(String),
    etag: expect.any(String),
    'set-cookie': 'sweet-cookie=choco; Path=/; HttpOnly',
    'x-powered-by': 'Express'
  },
  location: undefined,
  ok: true,
  redirect: false,
  status: 200,
  statusCode: 200,
  statusText: 'OK',
  text: expect.any(String) // Stringified body
});

Fastify Endpoint Testing

Example usage of auth method to set the Authorization header based on the provided token. Also, in response, you're able to validate cookies sent by the server.

import { request } from '../src/index.js';

// Don't forget to wait until all plugins are registered.
await fastifyApp.ready();

// Don't forget to use .server instead of plain fastify instance.
const response = await request(fastifyApp.server).get('/').auth('jwtToken');

expect(response).toEqual({
  body: {
    message: 'I love my mom!',
    requestHeaders: {
      authorization: 'Bearer jwtToken',
      connection: 'close',
      host: expect.any(String)
    }
  },
  cookies: {
    'sweet-cookie': {
      httpOnly: true,
      path: '/',
      value: 'choco'
    }
  },
  error: false,
  headers: {
    connection: 'close',
    'content-length': '127',
    'content-type': 'application/json; charset=utf-8',
    date: expect.any(String),
    'set-cookie': 'sweet-cookie=choco; HttpOnly'
  },
  location: undefined,
  ok: true,
  redirect: false,
  status: 200,
  statusCode: 200,
  statusText: 'OK',
  text: expect.any(String) // Stringified body
});

📚 API Documentation

The API documentation is available here. If you need more examples or have some questions, just open an issue or submit a pull request. I'll be happy to help you out.

❤️ Contributing

If you wish to contribute to the evolution of this package, please feel free to submit your issues or open pull requests. You are always welcome. 🥰

License

MIT (c) Eddie Nubes

sagetest's Issues

Known issues and feature requests

To streamline prerelease development, I'll keep the list of known issues here.
If you have anything to add, please open a separate issue.

---

• query method doesn't accept number arguments.
• send method should have its parameters optional.
• BREAKING: polyfill.ts doesn't check whether properties already exist on globalThis
• Sometimes file upload hangs (needs triage)
• remove undefined from header Record type. It'll make it more convenient to use in testing
• verify that file downloading works as expected in testing
• add an option to buffer a file into memory before sending it over to the server (.attach method), when file is supplied as a stream or path.
• Import still breaks in CJS projects because parent package.json contains type: module. Solution: add child package.json files with respective types for each bundle. (refined with rollup)