{"id":15982,"library":"chai-http","title":"Chai HTTP","description":"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.","status":"active","version":"5.1.2","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/chaijs/chai-http","tags":["javascript","chai","chai-plugin","browser","http","request","vendor","supertest","superagent","typescript"],"install":[{"cmd":"npm install chai-http","lang":"bash","label":"npm"},{"cmd":"yarn add chai-http","lang":"bash","label":"yarn"},{"cmd":"pnpm add chai-http","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency as `chai-http` is a plugin for the `chai` assertion library.","package":"chai","optional":false},{"reason":"Used internally by `chai-http` to perform HTTP requests.","package":"superagent","optional":false}],"imports":[{"note":"This is the default export used to install the plugin into Chai.","wrong":"import { chaiHttp } from 'chai-http';","symbol":"chaiHttp","correct":"import chaiHttp from 'chai-http';"},{"note":"`request` is a named export from `chai-http`, not from `chai` itself. It is the primary method for initiating HTTP requests.","wrong":"import { request } from 'chai';","symbol":"request","correct":"import { request } from 'chai-http';"},{"note":"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`).","wrong":"const chai = require('chai');","symbol":"chai","correct":"import * as chai from 'chai';"}],"quickstart":{"code":"import * as chai from 'chai';\nimport chaiHttp from 'chai-http';\nimport { request } from 'chai-http';\nimport express from 'express';\n\nchai.use(chaiHttp);\nconst expect = chai.expect;\n\nconst app = express();\napp.get('/', (req, res) => {\n  res.status(200).send('Hello Chai HTTP!');\n});\n\napp.post('/data', (req, res) => {\n  res.status(201).json({ received: req.body });\n});\n\ndescribe('Chai HTTP Basic Test', () => {\n  it('should get a 200 response from the root path', (done) => {\n    request.execute(app)\n      .get('/')\n      .end((err, res) => {\n        expect(err).to.be.null;\n        expect(res).to.have.status(200);\n        expect(res.text).to.equal('Hello Chai HTTP!');\n        done();\n      });\n  });\n\n  it('should post data and get a 201 response', (done) => {\n    request.execute(app)\n      .post('/data')\n      .send({ key: 'value' })\n      .end((err, res) => {\n        expect(err).to.be.null;\n        expect(res).to.have.status(201);\n        expect(res.body).to.deep.equal({ received: {} }); // Express needs body-parser for req.body\n        done();\n      });\n  });\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Migrate your project to use ESM `import` statements. Ensure your `package.json` has `\"type\": \"module\"` or use `.mjs` extensions.","message":"Chai 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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Upgrade your Node.js environment to version 16.20.0 or higher.","message":"Chai HTTP v5.0.0 raised the minimum supported Node.js version to `>=v16.20`. Older Node.js versions are no longer supported.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Review `superagent` v9 changelogs for any breaking changes that might affect your tests. Update your test cases if necessary.","message":"Chai 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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"For multiple requests, use `const requester = request.Request(app).keepOpen();` then call `requester.close()` when all requests are done.","message":"When 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"For 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.","severity":"gotcha","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`).","cause":"Attempting to use CommonJS `require()` syntax with Chai or Chai HTTP v5+ in a Node.js environment.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/chai/chai.js from ... not supported."},{"fix":"Import `request` directly from `chai-http`: `import { request } from 'chai-http';`.","cause":"Incorrectly attempting to import `request` from the `chai` package instead of `chai-http`.","error":"SyntaxError: The requested module 'chai' does not provide an export named 'request'"},{"fix":"Ensure you are using the default import for `chaiHttp` and passing it to `chai.use()`: `import chaiHttp from 'chai-http'; chai.use(chaiHttp);`","cause":"Attempting to use `chaiHttp` as a function directly or incorrectly destructuring the import, typically when trying to install the plugin.","error":"TypeError: chaiHttp is not a function"},{"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.","cause":"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.","error":"AssertionError: expected ... to have status ... but got ..."}],"ecosystem":"npm"}