should-http: HTTP Assertions for should.js

0.1.1 · abandoned · verified Tue Apr 21

should-http extends the `should.js` assertion library with specific methods for validating Node.js HTTP `IncomingMessage` objects. Primarily used for testing HTTP requests and responses, it enables fluent assertions on status codes, headers (e.g., `Content-Length`), and content types (e.g., `application/json`, `text/html`). Currently at version 0.1.1, this package appears to be abandoned, with no active development or maintenance. Its approach of patching the global `should` instance, rather than exporting specific utilities, ties it closely to older `should.js` usage patterns and makes it less suitable for modern module development (ESM) where global side-effects are generally avoided. It focuses specifically on the standard Node.js `http` module's request and response objects, distinguishing it from broader HTTP client assertion libraries.

Common errors

```
Error: should.js: assertion for 'status' was not added
```
cause The `should-http` module was required before `should.js` was initialized, or `should.js` itself was not required/available in the environment.

fix Ensure `require('should');` is called *before* `require('should-http');` to guarantee the `should` instance is available for patching.
```
TypeError: Cannot read properties of undefined (reading 'should')
```
cause The `should` library was not correctly loaded or applied, meaning `Object.prototype.should` (or `should(obj)`) is not available, and thus `res.should` fails.

fix Verify that `should` is properly installed (`npm install should`) and required at the top of your test file, as per `should.js`'s standard usage. If using a test runner, ensure `should` is loaded correctly (e.g., via Mocha's `-r` flag).
```
TypeError: 'res.should.be.json' is not a function
```
cause The assertion `json` is a method and requires parentheses `()` to be called, even though it takes no arguments.

fix Change `res.should.be.json` to `res.should.be.json()` to correctly invoke the assertion method. The same applies to `.html()`.

Warnings

breaking This package is largely unmaintained and may not be compatible with newer versions of Node.js or `should.js` beyond the specified peer dependency (>= 4.x). Using older, unmaintained packages can introduce security vulnerabilities or unexpected behavior in modern environments.
Fix: Consider migrating to a more actively maintained assertion library for HTTP testing, such as `chai-http` with `chai` or `supertest`.
gotcha should-http works by patching the global `should` instance (and by extension, potentially `Object.prototype` depending on `should.js` configuration). This can lead to global namespace pollution and conflicts with other libraries or unexpected side effects, which is a deprecated pattern in modern JavaScript development.
Fix: Be aware that including `should-http` modifies global objects. If you encounter unexpected properties or assertion failures in unrelated tests, this global patching is a likely cause. Encapsulate test environments or use `should.js`'s non-prototypal usage if possible.
gotcha This package is designed for CommonJS (`require`). While Node.js has robust interoperability, using a CJS module that relies on global side-effects within an ESM project might introduce subtle issues or require specific configuration (e.g., `--experimental-json-modules` or using bundlers).
Fix: For ESM projects, consider assertion libraries that are natively designed for ESM or offer explicit ESM support. If you must use `should-http`, ensure your build process or Node.js runtime environment handles CJS interoperability correctly.

Install

npm install should-http npm
yarn add should-http yarn
pnpm add should-http pnpm

Imports

* (side-effect import)
wrong:
```
import shouldHttp from 'should-http';
```
correct:
```
require('should-http');
```
This package is a CommonJS module designed to be `require`d for its side effects, patching the global `should` instance. It does not export specific symbols for named or default imports. While technically `import 'should-http';` might work in ESM, the package is likely not tested or intended for modern ESM environments and could have compatibility issues with newer Node.js versions.

Quickstart

Demonstrates how to initialize `should-http` and use its core assertions (status, header, json, html) on a mock HTTP response object.

const should = require('should');
require('should-http');

// Simulate an HTTP response object
const mockResponse = {
  statusCode: 200,
  headers: {
    'content-type': 'application/json; charset=utf-8',
    'content-length': '123'
  },
  body: '{ "key": "value" }'
};

// Assertions using should-http
try {
  mockResponse.should.have.status(200);
  console.log('✔ Status code is 200');

  mockResponse.should.have.header('content-length');
  console.log('✔ Has content-length header');

  mockResponse.should.have.header('Content-Length', '123');
  console.log('✔ Content-Length header matches value');

  mockResponse.should.be.json();
  console.log('✔ Content-Type is application/json');

  // Example of a failing assertion (uncomment to see it fail)
  // mockResponse.should.have.status(404);

} catch (e) {
  console.error('Assertion failed:', e.message);
}

// Example for .html (if content-type were different)
const htmlResponse = {
    statusCode: 200,
    headers: {
        'content-type': 'text/html; charset=utf-8'
    }
};

try {
    htmlResponse.should.be.html();
    console.log('✔ Content-Type is text/html');
} catch (e) {
    console.error('HTML assertion failed:', e.message);
}

view raw JSON →