Unexpected HTTP Server Testing Plugin

Common errors

• Error: Cannot find module 'unexpected'

  cause 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

  cause 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

  cause 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).

Warnings

• breaking 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.
  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`.
• gotcha 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`.
  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>`.
• gotcha 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.
  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.

Install

• npm install unexpected-http npm
• yarn add unexpected-http yarn
• pnpm add unexpected-http pnpm

Imports

• unexpectedHttp
  wrong:

  import { unexpectedHttp } from 'unexpected-http';

  correct:

  import unexpectedHttp from 'unexpected-http';

  The plugin is typically imported as a default export and passed to `expect.use()`.
• expect
  wrong:

  const expect = require('unexpected');

  correct:

  import { expect } from 'unexpected';

  The `expect` object itself comes from the `unexpected` core library. Ensure it's correctly imported/required before using the plugin.
• unexpectedHttp (CommonJS)
  wrong:

  const { unexpectedHttp } = require('unexpected-http');

  correct:

  const unexpectedHttp = require('unexpected-http');

  For CommonJS environments, the plugin is a default export.

Quickstart

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
    );
  });
});