chai-http

library5.1.2jsnpmunverified

Chai HTTP is an assertion plugin for the Chai Assertion Library, designed specifically for conducting HTTP integration tests. It enables developers to test HTTP APIs by composing requests and asserting on their responses, supporting both web applications (like Express or Connect apps) and external URLs. The library uses Superagent under the hood for making HTTP requests. The current stable version is 5.1.2, which maintains an active release cadence with multiple updates in the past year, indicating sustainable maintenance and a popular standing within the Node.js ecosystem. Key differentiators include its fluent, chainable API for request creation, automatic server management for local applications (starting and stopping it), and comprehensive assertions for common HTTP tasks like status codes, headers, and body content. It ships with TypeScript types, enhancing developer experience in TypeScript projects.

testing http-networking

npm install chai-http

github ↗package ↗

INSTALL

IMPORT

SIG · CHAI-HTTP

chai-http

testingjavascriptv5.1.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

chaiHttp

✓ import chaiHttp from 'chai-http';

✗ import { chaiHttp } from 'chai-http';

This is the default export used to install the plugin into Chai.

request

✓ import { request } from 'chai-http';

✗ import { request } from 'chai';

`request` is a named export from `chai-http`, not from `chai` itself. It is the primary method for initiating HTTP requests.

chai

✓ import * as chai from 'chai';

✗ const chai = require('chai');

Chai v5+ is ESM-only; CommonJS `require` will result in an `ERR_REQUIRE_ESM` error. Import `chai` as a namespace import or specific named imports (e.g., `expect`, `should`).

This quickstart demonstrates setting up Chai HTTP with an Express app, sending a GET request, and asserting the response status and text, and a POST request with data.

import * as chai from 'chai'; import chaiHttp from 'chai-http'; import { request } from 'chai-http'; import express from 'express'; chai.use(chaiHttp); const expect = chai.expect; const app = express(); app.get('/', (req, res) => { res.status(200).send('Hello Chai HTTP!'); }); app.post('/data', (req, res) => { res.status(201).json({ received: req.body }); }); describe('Chai HTTP Basic Test', () => { it('should get a 200 response from the root path', (done) => { request.execute(app) .get('/') .end((err, res) => { expect(err).to.be.null; expect(res).to.have.status(200); expect(res.text).to.equal('Hello Chai HTTP!'); done(); }); }); it('should post data and get a 201 response', (done) => { request.execute(app) .post('/data') .send({ key: 'value' }) .end((err, res) => { expect(err).to.be.null; expect(res).to.have.status(201); expect(res.body).to.deep.equal({ received: {} }); // Express needs body-parser for req.body done(); }); }); });

Debug

Known issues

breakingChai HTTP v5.0.0 (and its underlying Chai v5.x) dropped support for CommonJS modules, requiring all consumers to use EcmaScript Modules (ESM). Using `require('chai-http')` or `require('chai')` will cause an `ERR_REQUIRE_ESM` error.

fix

Migrate your project to use ESM `import` statements. Ensure your `package.json` has `"type": "module"` or use `.mjs` extensions.

affects: >=5.0.0

breakingChai HTTP v5.0.0 raised the minimum supported Node.js version to `>=v16.20`. Older Node.js versions are no longer supported.

fix

Upgrade your Node.js environment to version 16.20.0 or higher.

affects: >=5.0.0

breakingChai HTTP v5.0.0 updated its internal `superagent` dependency to version `^9`. This might introduce subtle behavioral changes if your project relied on specific `superagent` behaviors from older versions.

fix

Review `superagent` v9 changelogs for any breaking changes that might affect your tests. Update your test cases if necessary.

affects: >=5.0.0

gotchaWhen testing a local application (e.g., an Express app) by passing it to `request.execute(app)`, Chai HTTP will automatically open and then close the server after the request. If you intend to make multiple requests and keep the server open between them, you must explicitly call `.keepOpen()` on the request object and then manually `.close()` it.

fix

For multiple requests, use `const requester = request.Request(app).keepOpen();` then call `requester.close()` when all requests are done.

affects: >=3.0.0

gotchaFor browser-based testing, the README explicitly states to use `chai-http` v4.x. Version 5.x and above are primarily focused on Node.js environments for HTTP integration testing.

fix

If targeting web browsers for testing, stick to `chai-http` v4.x. Be aware of browser same-origin policy limitations on reading certain HTTP headers.

affects: >=5.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/chai/chai.js from ... not supported.

Attempting to use CommonJS `require()` syntax with Chai or Chai HTTP v5+ in a Node.js environment.

fix

Convert your test files to use ES Module `import` syntax (e.g., `import * as chai from 'chai';`). Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

SyntaxError: The requested module 'chai' does not provide an export named 'request'

Incorrectly attempting to import `request` from the `chai` package instead of `chai-http`.

fix

Import `request` directly from `chai-http`: `import { request } from 'chai-http';`.

TypeError: chaiHttp is not a function

Attempting to use `chaiHttp` as a function directly or incorrectly destructuring the import, typically when trying to install the plugin.

fix

Ensure you are using the default import for `chaiHttp` and passing it to `chai.use()`: `import chaiHttp from 'chai-http'; chai.use(chaiHttp);`

AssertionError: expected ... to have status ... but got ...

The HTTP response status code did not match the expected value in your assertion, or the server failed to send a response within the test timeout.

fix

Verify that your application/API is sending the correct status code. For asynchronous tests, ensure `done()` is called for Mocha, or return the promise if using promise-based tests. Increase test timeout if necessary.

Upgrade

Version history

5.1.2latest on npm

Audit

Dependencies

chairequiredPeer dependency as `chai-http` is a plugin for the `chai` assertion library.

superagentrequiredUsed internally by `chai-http` to perform HTTP requests.

Agent activity

23 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/chaijs/chai-http ↗

packagehttps://www.npmjs.com/package/chai-http ↗