{"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,"search_vec":"'10':57 '13':59 '9.0.0':52 'across':122 'align':87 'allow':31 'api':130 'applic':69 'assert':15,36,71,120,143,147 'backend':128 'bodi':77 'cadenc':85 'capabl':140 'client':24,149 'code':74 'compat':98 'consist':119 'content':78 'core':90 'declar':29 'deep':111 'depend':92 'design':18 'develop':32 'dif':137 'differenti':108 'ecosystem':116 'enabl':62 'experi':121 'express':35,48 'extend':26 'fail':142 'featur':101 'fluent':63 'frontend':127 'header':75 'http':2,8,21,38,80,104,145 'includ':126 'integr':112 'interact':81 'introduc':100 'introspect':139 'javascript':144 'leverag':133 'librari':16,61 'maintain':97 'mimick':42 'often':86 'plugin':5,11 'power':136 'primari':107 'provid':117 'receiv':94 'releas':84 'relev':102 'request':39 'respons':41 'scenario':125 'server':3,22,67,148 'server-sid':66 'side':68 'specif':17 'status':73 'style':44 'support':54 'syntax':30 'test':4,20,64,105,124,131,146 'unexpect':1,7,14,27,47,55,91,115,134 'unexpected-express':46 'unexpected-http':6 'updat':95 'various':123 'version':51,56 'write':34","created_at":"2026-04-22T16:31:10.596734+00:00","updated_at":"2026-04-22T16:31:10.596734+00:00","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,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/unexpectedjs/unexpected-http","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/unexpected-http","openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-21","install_tag":null}}