HTTPtestify

Common errors

• TypeError: HTTPtestify.request is not a function

  cause Attempting to destructure `request` as a named import (e.g., `import { request } from 'http-testify'`) when it's a method on the default export.
  fix Import the default `HTTPtestify` object and then call `HTTPtestify.request(app)`.

• AssertionError: Expected status 200, got 404

  cause The tested API endpoint returned an unexpected HTTP status code, often due to an incorrect route, missing handler, or server-side error.
  fix Verify the endpoint path, HTTP method, and server-side route definitions. Check server logs for internal errors during the request.

• UnhandledPromiseRejectionWarning: This error originated either by throwing an error inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch().

  cause An `http-testify` operation (or subsequent assertion) rejected a Promise, and the rejection was not caught by an `await` within a `try/catch` block or a `.catch()` handler.
  fix Wrap asynchronous test code in `try...catch` blocks, or ensure all Promises are handled with `.catch()` to log or assert on errors explicitly.

Warnings

• gotcha When migrating from older CommonJS (`require`) patterns to modern ESM (`import`) in Node.js, ensure your project's `package.json` and TypeScript configuration are set up for ESM, as `http-testify` ships with types and is designed for modern usage.
  Fix: Use `import HTTPtestify from 'http-testify';` and ensure `type: 'module'` in `package.json` or configure TypeScript to emit ESM.
• gotcha Asynchronous operations with `http-testify` require proper handling of Promises. Forgetting `await` or neglecting `.then().catch()` chains can lead to tests completing prematurely or unhandled promise rejections, making debugging difficult.
  Fix: Always use `await` with `http-testify` methods in `async` functions, or chain `.then()` for successful responses and `.catch()` for error handling.
• gotcha While `http-testify` manages the lifecycle of its internal mock server, it's crucial to ensure proper test isolation and cleanup within your test suite. Shared state or external resources not properly reset between tests can lead to flaky results.
  Fix: Design tests to be stateless where possible. For stateful scenarios, use test runner hooks (e.g., `beforeEach`, `afterEach` in Jest/Mocha) to reset application state or mock external dependencies.

Install

• npm install http-testify npm
• yarn add http-testify yarn
• pnpm add http-testify pnpm

Imports

• HTTPtestify
  wrong:

  const HTTPtestify = require('http-testify');

  correct:

  import HTTPtestify from 'http-testify';

  While the library's `README` uses `require` for CommonJS, modern Node.js applications and TypeScript projects should prefer the ESM `import` syntax. The package is designed with TypeScript in mind, ensuring proper type inference with `import`.
• request
  wrong:

  import { request } from 'http-testify';

  correct:

  const server = HTTPtestify.request(app);

  `request` is a method on the default-imported `HTTPtestify` object, used to initialize a test server instance. It is not a named export that can be destructured directly from the package.
• get
  wrong:

  HTTPtestify.get('/api/data').then(...);

  correct:

  server.get('/api/data').then(...);

  HTTP methods like `get`, `post`, `put`, etc., are invoked on the `server` instance returned by `HTTPtestify.request(app)`, not directly on the main `HTTPtestify` object.

Quickstart

Demonstrates how to set up `http-testify` with a simple Express server, make GET and POST requests, and execute parallel requests, logging their responses.

import HTTPtestify from 'http-testify';
import express from 'express'; // Common framework for HTTP APIs

// 1. Create a minimal Express app instance for testing
const app = express();
app.use(express.json()); // Enable JSON body parsing for POST requests

// Define a simple GET endpoint
app.get('/api/status', (req, res) => {
  res.status(200).json({ status: 'ok', version: '1.0' });
});

// Define a simple POST endpoint
app.post('/api/submit', (req, res) => {
  const data = req.body;
  res.status(201).json({ message: 'Data received', received: data });
});

// 2. Initialize HTTPtestify with the app instance
const server = HTTPtestify.request(app);

// 3. Define an async test function
async function runExampleTests() {
  try {
    // Perform a GET request
    const getResponse = await server.get('/api/status');
    console.log('GET /api/status Status:', getResponse.status); // Expected: 200
    console.log('GET /api/status Data:', getResponse.data);    // Expected: { status: 'ok', version: '1.0' }

    // Perform a POST request with a JSON body
    const postResponse = await server.post('/api/submit', { item: 'widget', quantity: 5 });
    console.log('POST /api/submit Status:', postResponse.status); // Expected: 201
    console.log('POST /api/submit Data:', postResponse.data);    // Expected: { message: 'Data received', received: { item: 'widget', quantity: 5 } }

    // Demonstrate parallel GET requests
    const [res1, res2] = await server.all((instance) => [
      instance.get('/api/status'),
      instance.get('/api/status')
    ]);
    console.log('Parallel Requests Results:', res1.status, res2.status);

    console.log('\nAll example tests completed successfully!');
  } catch (error) {
    console.error('An error occurred during tests:', error);
  }
}

runExampleTests();