@klondikemarlen/expect-http-response 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marlen Brunner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,234 @@
-# Temporary Holding Version
+# @klondikemarlen/expect-http-response
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Readable HTTP response failures for Jest and Vitest: focused status errors and contextual body diffs, without unrelated transport internals. One `expect` describes the status and complete body. This dependency-free ESM matcher is registered explicitly with your existing test runner.
+
+## Why This Matcher Exists
+
+The goal is readable failures, not satisfying an assertion-count quota. Separate status and body assertions are a useful baseline:
+
+```js
+expect(response.status).toEqual(200)
+expect(response.body).toEqual(expectedBody)
+```
+
+Those assertions keep an incorrect status obvious and give the body its own native diff. A stock matcher can express the combined contract too:
+
+```js
+expect(response).toEqual(expect.objectContaining({ status: 200, body: expectedBody }))
+```
+
+However, a failure against the whole Supertest response can include unrelated headers, request metadata, and raw response text. `toMatchObject` is not an equivalent complete-body replacement: its partial matching can accept unexpected body fields.
+
+`toHaveHttpResponse` keeps the focused diagnostics of the two-expect approach while naming one HTTP response contract:
+
+```js
+expect(response).toHaveHttpResponse(200, expectedBody)
+```
+
+- A status-only failure reports the differing statuses without printing the matching body.
+- A body failure uses the active runner's contextual diff, exposing changed nested values rather than dumping both collections or hiding them as `[Object]`.
+- If both differ, both failures are reported; separate assertions normally stop at the first failed status assertion.
+- Failed negation explains that status and body both matched without printing the matching payload twice.
+
+For example, a changed field among 100 response records remains visible in the diff (excerpt):
+
+```diff
+         "id": 50,
+-        "name": "Expected record 50",
++        "name": "Record 50",
+```
+
+This changes the diagnostic boundary, not the equality policy. Complete-body comparison, deliberate asymmetric matches, and the runner's custom equality testers retain their existing meaning.
+
+## Installation
+
+Install a published release as a development dependency:
+
+```sh
+npm install --save-dev @klondikemarlen/expect-http-response
+```
+
+Alternatively, install directly from this focused repository:
+
+```sh
+npm install --save-dev github:klondikemarlen/expect-http-response
+```
+
+Use an ESM project (`"type": "module"`) or `.mjs` setup/config files. The package has no runtime dependencies and exports `toHaveHttpResponse` from its root only. Consumers supply their own test runner and explicitly register the matcher; registration is not automatic.
+
+## Registering the Matcher
+
+Register once in the setup module for the runner you use. The examples use the runner's own `expect` instance.
+
+### Jest
+
+Jest setup files run after Jest initializes its assertion environment:
+
+```js
+// test/setup-http-response-matcher.mjs
+import { expect } from "@jest/globals"
+import { toHaveHttpResponse } from "@klondikemarlen/expect-http-response"
+
+expect.extend({ toHaveHttpResponse })
+```
+
+```js
+// jest.config.mjs
+export default {
+  setupFilesAfterEnv: ["<rootDir>/test/setup-http-response-matcher.mjs"],
+}
+```
+
+For Jest's native ESM mode, invoke the existing Jest command with Node's VM-module support, for example:
+
+```sh
+node --experimental-vm-modules node_modules/jest/bin/jest.js
+```
+
+Preserve the project's existing transforms and test command when integrating the setup.
+
+### Vitest
+
+```js
+// test/setup-http-response-matcher.mjs
+import { expect } from "vitest"
+import { toHaveHttpResponse } from "@klondikemarlen/expect-http-response"
+
+expect.extend({ toHaveHttpResponse })
+```
+
+```js
+// vitest.config.mjs
+import { defineConfig } from "vitest/config"
+
+export default defineConfig({
+  test: {
+    setupFiles: ["./test/setup-http-response-matcher.mjs"],
+  },
+})
+```
+
+### Other Compatible Runners
+
+Import the matcher from the package root and extend the active runner's `expect` instance explicitly. The matcher relies on the runner's equality function and custom matcher context; it does not bundle or select a runner.
+
+Focused failures use the runner's `utils.printDiffOrStringify`, which Jest and Vitest supply through `expect.extend`. Other compatible runners need a Jest- or Vitest-compatible version of that utility for contextual diffs; without it, only basic expected/received rendering is available.
+
+## TypeScript
+
+The package root resolves to `index.d.mts`. Add a declaration augmentation for each runner you actually install. For Jest's `expect` package:
+
+```ts
+// test/http-response-matchers.d.ts
+import "expect"
+
+declare module "expect" {
+  interface Matchers<R extends void | Promise<void>, T = unknown> {
+    toHaveHttpResponse(expectedStatus: number, expectedBody: unknown): R
+  }
+}
+```
+
+For Vitest:
+
+```ts
+// test/http-response-matchers.d.ts
+import "vitest"
+
+declare module "vitest" {
+  interface Matchers<R, T> {
+    toHaveHttpResponse(expectedStatus: number, expectedBody: unknown): R
+  }
+}
+```
+
+Ensure TypeScript includes the augmentation as well as the tests (merge these entries into the existing `include` paths rather than replacing source entries):
+
+```json
+{
+  "include": ["src/**/*.ts", "test/**/*.ts", "test/http-response-matchers.d.ts"]
+}
+```
+
+The TypeScript setup module must also be included if it is written in TypeScript. Explicitly importing `expect` from `vitest` or `@jest/globals` does not require runner globals in `compilerOptions.types`. Do not add an augmentation for a runner that is not installed.
+
+For a Node.js project, keep `@types/node` installed and include `"node"` in `compilerOptions.types` if the project's configuration does not already load it. Node types are separate from Jest/Vitest globals.
+
+## Example: Express and Supertest
+
+This makes a real request to an Express route. The single assertion is the response contract; it makes no separate claim about persistence or other effects.
+
+```ts
+import express from "express"
+import { expect, test } from "vitest"
+import request from "supertest"
+import { toHaveHttpResponse } from "@klondikemarlen/expect-http-response"
+
+expect.extend({ toHaveHttpResponse })
+
+const app = express()
+app.get("/users/:id", (req, res) => {
+  res.status(200).json({
+    user: { id: Number(req.params.id), name: "Ada" },
+  })
+})
+
+test("when the user exists, returns the complete user response", async () => {
+  const response = await request(app).get("/users/7")
+
+  expect(response).toHaveHttpResponse(200, {
+    user: { id: 7, name: "Ada" },
+  })
+})
+```
+
+## Body Equality, Negation, and Invalid Arguments
+
+`toHaveHttpResponse(status, body)` passes only when the numeric response `status` and complete `body` both match. Body comparison uses the active runner's equality function and custom equality testers, plus iterable equality when the runner exposes it, consistent with `toEqual`. Transport fields such as request, socket, or response internals are not inspected.
+
+- Body equality is complete: unexpected body keys fail, just as they do with `toEqual`.
+- Asymmetric values such as `expect.objectContaining(...)` deliberately request a partial body match.
+- `.not` negates the combined status-and-body contract. It passes if either status or body differs and fails only when both match.
+- The expected status and received `response.status` must be finite numbers. An Express `res.status()` method is not a sent response status.
+- Invalid inputs throw even through `.not`; they are not treated as a successful negative assertion.
+- Supply the body argument explicitly. Pass `undefined` when the expected response body is undefined.
+
+## Package Development
+
+The package's focused test suite includes matcher unit tests using Jest's `expect`, a real Express/Supertest integration test using Vitest, and strict TypeScript registration checks for both runners.
+
+```sh
+npm ci
+npm test
+npm run test:unit
+npm run test:integration
+npm run typecheck
+```
+
+## Release
+
+From the repository's merged `main` branch, verify the package before tagging and publishing. Release publication is not complete until the registry artifact is installed and exercised:
+
+```sh
+npm test
+npm pack --dry-run
+git switch main
+git pull --ff-only origin main
+git tag v1.0.1
+git push origin v1.0.1
+gh release create v1.0.1 --title v1.0.1 --generate-notes
+npm publish --access public
+npm view @klondikemarlen/expect-http-response@1.0.1 version
+```
+
+In a separate consumer project, install the registry artifact:
+
+```sh
+npm install --save-dev @klondikemarlen/expect-http-response@1.0.1
+```
+
+After publishing, use the actual registry installation in a fresh consumer project and run its matcher and TypeScript registration checks. Do not claim npm availability until the publish and registry install have been observed.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/index.d.mts

@@ -0,0 +1,59 @@
+type EqualityTester = (this: any, ...values: any[]) => boolean | undefined
+
+type EqualityFunction = (
+  received: unknown,
+  expected: unknown,
+  customTesters?: EqualityTester[],
+  strictCheck?: boolean
+) => boolean
+
+interface HttpResponseLike {
+  readonly status: number
+  readonly body?: unknown
+}
+
+type JestBodyFormatter = (
+  expected: unknown,
+  received: unknown,
+  expectedLabel: string,
+  receivedLabel: string,
+  expand: boolean
+) => string
+
+type VitestBodyFormatter = (
+  received: unknown,
+  expected: unknown,
+  options?: { expand?: boolean }
+) => string | undefined
+
+interface MatcherUtils {
+  printDiffOrStringify?: JestBodyFormatter | VitestBodyFormatter
+  matcherHint?: (
+    matcherName: string,
+    received?: string,
+    expected?: string,
+    options?: { isNot?: boolean }
+  ) => string
+  printExpected?: (value: unknown) => string
+  printReceived?: (value: unknown) => string
+  iterableEquality?: EqualityTester
+}
+
+interface MatcherContext {
+  readonly isNot?: boolean
+  readonly customTesters?: EqualityTester[]
+  readonly equals: EqualityFunction
+  readonly utils?: MatcherUtils
+}
+
+interface MatcherResult {
+  readonly pass: boolean
+  readonly message: () => string
+}
+
+export declare function toHaveHttpResponse(
+  this: MatcherContext,
+  received: HttpResponseLike,
+  expectedStatus: number,
+  expectedBody: unknown
+): MatcherResult

package/index.mjs

@@ -0,0 +1,129 @@
+const MATCHER_NAME = "toHaveHttpResponse"
+
+export function toHaveHttpResponse(response, expectedStatus, expectedBody) {
+  if (arguments.length < 3) {
+    throw new TypeError(
+      `${MATCHER_NAME} requires an expected status and body. Pass undefined explicitly for an undefined body.`
+    )
+  }
+
+  if (typeof expectedStatus !== "number" || !Number.isFinite(expectedStatus)) {
+    throw new TypeError("expectedStatus must be a finite number.")
+  }
+
+  if (typeof response !== "object" || response === null) {
+    throw new TypeError("received value must be a non-null HTTP response object.")
+  }
+
+  const receivedStatus = response.status
+  if (typeof receivedStatus !== "number" || !Number.isFinite(receivedStatus)) {
+    throw new TypeError(
+      "received response.status must be a finite number; an Express status() method is not a response status value."
+    )
+  }
+
+  if (typeof this?.equals !== "function") {
+    throw new TypeError("the test runner must provide an equality function for custom matchers.")
+  }
+
+  const equalityTesters = [...(this.customTesters ?? [])]
+  const iterableEquality = this.utils?.iterableEquality
+  if (typeof iterableEquality === "function" && !equalityTesters.includes(iterableEquality)) {
+    equalityTesters.push(iterableEquality)
+  }
+
+  const receivedBody = response.body
+  const statusMatches = receivedStatus === expectedStatus
+  const bodyMatches = this.equals(receivedBody, expectedBody, equalityTesters)
+  const pass = statusMatches && bodyMatches
+
+  return {
+    pass,
+    message: () =>
+      formatMessage(this, {
+        expectedBody,
+        expectedStatus,
+        receivedBody,
+        receivedStatus,
+        statusMatches,
+        bodyMatches,
+      }),
+  }
+}
+
+function formatMessage(context, result) {
+  const hint = matcherHint(context)
+  if (context.isNot) {
+    return [
+      hint,
+      "",
+      "Expected the response not to match this HTTP contract:",
+      `Matched status: ${printValue(context, "printReceived", result.receivedStatus)}`,
+      "The status and body both matched.",
+    ].join("\n")
+  }
+
+  const lines = [hint]
+  if (!result.statusMatches) {
+    lines.push(
+      "",
+      `Status mismatch: expected ${printValue(context, "printExpected", result.expectedStatus)}, received ${printValue(context, "printReceived", result.receivedStatus)}.`
+    )
+  }
+
+  if (!result.bodyMatches) {
+    lines.push(
+      "",
+      "Body mismatch:",
+      formatBodyDifference(context, result.expectedBody, result.receivedBody)
+    )
+  }
+
+  return lines.join("\n")
+}
+
+function formatBodyDifference(context, expectedBody, receivedBody) {
+  const formatter = context.utils?.printDiffOrStringify
+  let difference
+
+  if (typeof formatter === "function") {
+    // Jest uses five positional arguments; Vitest uses three or four, with reversed values.
+    if (formatter.length >= 5) {
+      difference = formatter(expectedBody, receivedBody, "Expected body", "Received body", false)
+    } else {
+      difference = formatter(receivedBody, expectedBody, { expand: false })
+    }
+  }
+
+  if (typeof difference === "string") {
+    return difference
+  }
+
+  return [
+    `Expected body: ${printValue(context, "printExpected", expectedBody)}`,
+    `Received body: ${printValue(context, "printReceived", receivedBody)}`,
+  ].join("\n")
+}
+
+function matcherHint(context) {
+  if (typeof context.utils?.matcherHint === "function") {
+    return context.utils.matcherHint(
+      `.${MATCHER_NAME}`,
+      undefined,
+      "expectedStatus, expectedBody",
+      { isNot: context.isNot }
+    )
+  }
+
+  const negation = context.isNot ? ".not" : ""
+  return `expect(received)${negation}.${MATCHER_NAME}(expectedStatus, expectedBody)`
+}
+
+function printValue(context, formatterName, value) {
+  const formatter = context.utils?.[formatterName]
+  if (typeof formatter === "function") {
+    return formatter(value)
+  }
+
+  return String(value)
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@klondikemarlen/expect-http-response",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Focused HTTP response failure diagnostics for Jest and Vitest",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.mts",
+      "import": "./index.mjs"
+    }
+  },
+  "files": [
+    "index.mjs",
+    "index.d.mts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "node --test tests/to-have-http-response.test.mjs && vitest run && tsc --noEmit -p tsconfig.json",
+    "test:unit": "node --test tests/to-have-http-response.test.mjs",
+    "test:integration": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/klondikemarlen/expect-http-response.git"
+  },
+  "homepage": "https://github.com/klondikemarlen/expect-http-response#readme",
+  "bugs": {
+    "url": "https://github.com/klondikemarlen/expect-http-response/issues"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^26.6.5",
+    "@types/supertest": "^7.2.1",
+    "expect": "^30.5.2",
+    "express": "^5.3.0",
+    "supertest": "^7.3.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.4"
+  }
+}