Registry / testing / unexpected-http

unexpected-http

JSON →
library9.0.0jsnpmunverified

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.

npm install unexpected-http
INSTALL
IMPORT
SIG · UNEXPECTED-HTTP
U
unexpected-http
testingjavascriptv9.0.0
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.

unexpectedHttp
✓ import unexpectedHttp from 'unexpected-http';
✗ import { unexpectedHttp } from 'unexpected-http';
The plugin is typically imported as a default export and passed to `expect.use()`.
expect
✓ import { expect } from 'unexpected';
✗ const expect = require('unexpected');
The `expect` object itself comes from the `unexpected` core library. Ensure it's correctly imported/required before using the plugin.
unexpectedHttp (CommonJS)
✓ const unexpectedHttp = require('unexpected-http');
✗ const { unexpectedHttp } = require('unexpected-http');
For CommonJS environments, the plugin is a default export.

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.

import { expect } from 'unexpected'; import unexpectedHttp from 'unexpected-http'; import express from 'express'; import supertest from 'supertest'; // Activate the unexpected-http plugin expect.use(unexpectedHttp); const app = express(); app.use(express.json()); // For parsing application/json app.get('/hello', (req, res) => { res.status(200).json({ message: 'Hello, World!' }); }); app.post('/echo', (req, res) => { if (!req.body || Object.keys(req.body).length === 0) { return res.status(400).json({ error: 'Request body is empty' }); } res.status(200).json({ received: req.body }); }); describe('HTTP Server Tests with unexpected-http', () => { let requestAgent: supertest.SuperTest<supertest.Test>; beforeAll(() => { // Use supertest to create a test agent for the Express app requestAgent = supertest(app); }); it('should respond with a greeting on GET /hello', async () => { await expect( requestAgent.get('/hello'), 'to yield response', { status: 200, headers: { 'content-type': 'application/json; charset=utf-8' }, body: { message: 'Hello, World!' } } ); }); it('should echo the JSON body on POST /echo', async () => { const payload = { data: 'test data', value: 123 }; await expect( requestAgent.post('/echo').send(payload), 'to yield response', { status: 200, headers: { 'content-type': 'application/json; charset=utf-8' }, body: { received: payload } } ); }); it('should return 400 for an empty body on POST /echo', async () => { await expect( requestAgent.post('/echo').send({}), 'to yield response', 400 ); }); });
Debug
Known issues
breakingVersion 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.
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`.
affects: >=9.0.0
gotchaPeer 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`.
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>`.
affects: >=1.0.0
gotchaWhen 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.
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.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Cannot find module 'unexpected'
The core `unexpected` assertion library, which is a peer dependency, is not installed or not resolvable by your package manager.
fix
Install `unexpected` in your project: `npm install unexpected` or `yarn add unexpected`.
TypeError: expect(...).to yield response is not a function
The `unexpected-http` plugin has not been correctly applied to the `expect` instance, or `expect` itself is not correctly imported.
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.
npm ERR! ERESOLVE unable to resolve dependency tree
Your project's version of `unexpected` conflicts with the peer dependency requirements of `unexpected-http`.
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).
Upgrade
Version history
9.0.0latest on npm
Audit
Dependencies
unexpectedrequiredCore assertion library; `unexpected-http` is a plugin that extends its assertion capabilities.
Agent activity
19 hits · last 30 days
node
18
OpenAI (training)
1
Resources
unexpected-http — npm install unexpected-http · libregistry