{"id":17390,"library":"unexpected-http","title":"Unexpected HTTP Server Testing Plugin","description":"unexpected-http is a plugin for the `unexpected` assertion library, specifically designed for testing HTTP servers and clients. It extends `unexpected`'s declarative syntax, allowing developers to write expressive assertions against HTTP requests and responses, mimicking the style of `unexpected-express`. As of version 9.0.0, it supports `unexpected` versions 10 through 13. The library enables fluent testing of server-side applications by asserting on status codes, headers, and body content of HTTP interactions. While its release cadence often aligns with its core `unexpected` dependency, it receives updates to maintain compatibility and introduce features relevant to HTTP testing. Its primary differentiator is its deep integration into the `unexpected` ecosystem, providing a consistent assertion experience across various testing scenarios, including frontend, backend, and API testing, by leveraging `unexpected`'s powerful diffing and introspection capabilities for failed assertions.","status":"active","version":"9.0.0","language":"javascript","source_language":"en","source_url":"git://github.com/unexpectedjs/unexpected-http","tags":["javascript","http","test","assertion","server","client"],"install":[{"cmd":"npm install unexpected-http","lang":"bash","label":"npm"},{"cmd":"yarn add unexpected-http","lang":"bash","label":"yarn"},{"cmd":"pnpm add unexpected-http","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core assertion library; `unexpected-http` is a plugin that extends its assertion capabilities.","package":"unexpected","optional":false}],"imports":[{"note":"The plugin is typically imported as a default export and passed to `expect.use()`.","wrong":"import { unexpectedHttp } from 'unexpected-http';","symbol":"unexpectedHttp","correct":"import unexpectedHttp from 'unexpected-http';"},{"note":"The `expect` object itself comes from the `unexpected` core library. Ensure it's correctly imported/required before using the plugin.","wrong":"const expect = require('unexpected');","symbol":"expect","correct":"import { expect } from 'unexpected';"},{"note":"For CommonJS environments, the plugin is a default export.","wrong":"const { unexpectedHttp } = require('unexpected-http');","symbol":"unexpectedHttp (CommonJS)","correct":"const unexpectedHttp = require('unexpected-http');"}],"quickstart":{"code":"import { expect } from 'unexpected';\nimport unexpectedHttp from 'unexpected-http';\nimport express from 'express';\nimport supertest from 'supertest';\n\n// Activate the unexpected-http plugin\nexpect.use(unexpectedHttp);\n\nconst app = express();\napp.use(express.json()); // For parsing application/json\n\napp.get('/hello', (req, res) => {\n  res.status(200).json({ message: 'Hello, World!' });\n});\n\napp.post('/echo', (req, res) => {\n  if (!req.body || Object.keys(req.body).length === 0) {\n    return res.status(400).json({ error: 'Request body is empty' });\n  }\n  res.status(200).json({ received: req.body });\n});\n\ndescribe('HTTP Server Tests with unexpected-http', () => {\n  let requestAgent: supertest.SuperTest<supertest.Test>;\n\n  beforeAll(() => {\n    // Use supertest to create a test agent for the Express app\n    requestAgent = supertest(app);\n  });\n\n  it('should respond with a greeting on GET /hello', async () => {\n    await expect(\n      requestAgent.get('/hello'),\n      'to yield response',\n      {\n        status: 200,\n        headers: { 'content-type': 'application/json; charset=utf-8' },\n        body: { message: 'Hello, World!' }\n      }\n    );\n  });\n\n  it('should echo the JSON body on POST /echo', async () => {\n    const payload = { data: 'test data', value: 123 };\n    await expect(\n      requestAgent.post('/echo').send(payload),\n      'to yield response',\n      {\n        status: 200,\n        headers: { 'content-type': 'application/json; charset=utf-8' },\n        body: { received: payload }\n      }\n    );\n  });\n\n  it('should return 400 for an empty body on POST /echo', async () => {\n    await expect(\n      requestAgent.post('/echo').send({}),\n      'to yield response',\n      400\n    );\n  });\n});","lang":"typescript","description":"This quickstart demonstrates how to set up `unexpected-http` with an Express application and `supertest` to perform declarative HTTP assertions on status, headers, and JSON body content for various endpoints."},"warnings":[{"fix":"Review the changelogs for both `unexpected-http` and `unexpected` (especially for major versions) and update your test code and Node.js environment accordingly. Ensure your `unexpected` peer dependency matches the specified range for `unexpected-http`.","message":"Version 9.0.0 includes breaking changes, primarily due to updates in its peer dependency `unexpected` and potential shifts in supported Node.js versions. Always consult the `unexpected` changelog for major version updates to understand core assertion library changes.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Upgrade or downgrade your `unexpected` package to a version that satisfies the `unexpected-http` peer dependency range (e.g., `^10.27.0 || ^11.12.1 || ^12.0.0 || ^13.0.0` for v9.0.0). Use `npm install unexpected@<version>` or `yarn add unexpected@<version>`.","message":"Peer dependency conflicts with `unexpected` are common. If `npm install` or `yarn install` report warnings or errors about `unexpected`, it means your project's version of `unexpected` does not satisfy the range required by `unexpected-http`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Place `expect.use(unexpectedHttp);` at the top of your test suite or in a dedicated test setup file that runs before your tests. If using TypeScript, ensure `expect` is imported from 'unexpected' and the plugin is imported correctly.","message":"When writing tests, ensure `expect.use(unexpectedHttp);` is called at a global level (e.g., in a setup file or before all tests) so that the HTTP assertions are available to your `expect` instance.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install `unexpected` in your project: `npm install unexpected` or `yarn add unexpected`.","cause":"The core `unexpected` assertion library, which is a peer dependency, is not installed or not resolvable by your package manager.","error":"Error: Cannot find module 'unexpected'"},{"fix":"Ensure `import { expect } from 'unexpected';` (or `const expect = require('unexpected').expect;`) is at the top of your test file, and `expect.use(unexpectedHttp);` is called to register the plugin.","cause":"The `unexpected-http` plugin has not been correctly applied to the `expect` instance, or `expect` itself is not correctly imported.","error":"TypeError: expect(...).to yield response is not a function"},{"fix":"Examine the `peerDependencies` field in `unexpected-http`'s `package.json` (or the error message) and adjust your `unexpected` version to fit the range. For example, `npm install unexpected@^13.0.0` or `npm install --legacy-peer-deps` (use `legacy-peer-deps` with caution as a temporary workaround).","cause":"Your project's version of `unexpected` conflicts with the peer dependency requirements of `unexpected-http`.","error":"npm ERR! ERESOLVE unable to resolve dependency tree"}],"ecosystem":"npm","meta_description":null}