@klondikemarlen/expect-http-response 1.0.0 → 1.0.2

package/README.md

@@ -1,6 +1,81 @@
 # @klondikemarlen/expect-http-response
 
-One `expect` can describe an HTTP response contract: its status and complete body. This dependency-free ESM matcher works with Jest's `expect` and Vitest. Register it explicitly with your existing test runner.
+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
+
+`toHaveHttpResponse` expresses the response status and complete body as one HTTP contract, with focused diagnostics when that contract fails. Separate status and body assertions provide a useful comparison:
+
+```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` combines the status and body checks while keeping their diagnostics focused:
+
+```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.
+
+### Example: Whole-Response Failure
+
+In a real controller test, the expected title of a returned notice was deliberately changed. On Vitest 4.1.11, the whole-response `toEqual(expect.objectContaining(...))` assertion above produced the following selected diff lines. Domain names and fixture values are anonymized; `...` marks omitted output:
+
+```diff
+-   "body": {
+-     "notices": [
+-       ObjectContaining {
+-         "id": 1,
+-         "title": "Scheduled maintenance",
+...
++   "header": {
++     "content-type": "application/json; charset=utf-8",
+...
++   "req": {
++     "method": "GET",
++     "url": "http://127.0.0.1:<port>/notices",
+...
++   "text": "{\"notices\":[...\"title\":\"Active notice\"...]}",
+```
+
+The expected title appears under `body`, but the received title is embedded in escaped response text among unrelated transport details.
+
+Using the same expected body with `toHaveHttpResponse` produced these selected lines instead:
+
+```diff
+Body mismatch:
+- Expected
++ Received
+...
+-       "title": "Scheduled maintenance",
+...
++       "title": "Active notice",
+```
+
+Both titles are now part of the body comparison, without headers, request metadata, or raw response text. Other body fields can still appear according to the runner's native asymmetric-match formatting.
 
 ## Installation
 
@@ -74,6 +149,8 @@ export default defineConfig({
 
 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:
@@ -174,17 +251,17 @@ npm test
 npm pack --dry-run
 git switch main
 git pull --ff-only origin main
-git tag v1.0.0
-git push origin v1.0.0
-gh release create v1.0.0 --title v1.0.0 --generate-notes
+git tag v1.0.2
+git push origin v1.0.2
+gh release create v1.0.2 --title v1.0.2 --generate-notes
 npm publish --access public
-npm view @klondikemarlen/expect-http-response@1.0.0 version
+npm view @klondikemarlen/expect-http-response@1.0.2 version
 ```
 
 In a separate consumer project, install the registry artifact:
 
 ```sh
-npm install --save-dev @klondikemarlen/expect-http-response@1.0.0
+npm install --save-dev @klondikemarlen/expect-http-response@1.0.2
 ```
 
 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.

package/index.d.mts

@@ -12,7 +12,22 @@ interface HttpResponseLike {
   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,

package/index.mjs

@@ -58,10 +58,8 @@ function formatMessage(context, result) {
       hint,
       "",
       "Expected the response not to match this HTTP contract:",
-      `Expected status: ${printValue(context, "printExpected", result.expectedStatus)}`,
-      `Received status: ${printValue(context, "printReceived", result.receivedStatus)}`,
-      `Expected body: ${printValue(context, "printExpected", result.expectedBody)}`,
-      `Received body: ${printValue(context, "printReceived", result.receivedBody)}`,
+      `Matched status: ${printValue(context, "printReceived", result.receivedStatus)}`,
+      "The status and body both matched.",
     ].join("\n")
   }
 
@@ -77,14 +75,36 @@ function formatMessage(context, result) {
     lines.push(
       "",
       "Body mismatch:",
-      `Expected body: ${printValue(context, "printExpected", result.expectedBody)}`,
-      `Received body: ${printValue(context, "printReceived", result.receivedBody)}`
+      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(

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@klondikemarlen/expect-http-response",
-  "version": "1.0.0",
-  "description": "One-expect HTTP response contracts for Jest and Vitest",
+  "version": "1.0.2",
+  "description": "Focused HTTP response failure diagnostics for Jest and Vitest",
   "license": "MIT",
   "type": "module",
   "exports": {