nock 15.0.0-beta.5 → 15.0.0

package/README.md

@@ -461,13 +461,14 @@ nock('http://www.google.com')
   .replyWithError('something awful happened')
 ```
 
-JSON error responses are allowed too:
+Error objects are allowed too:
 
 ```js
-nock('http://www.google.com').get('/cat-poems').replyWithError({
-  message: 'something awful happened',
-  code: 'AWFUL_ERROR',
-})
+nock('http://www.google.com')
+  .get('/cat-poems')
+  .replyWithError(
+    Object.assign(new Error('Connection refused'), { code: 'ECONNREFUSED' }),
+  )
 ```
 
 > Note: This will emit an `error` event on the `request` object, not the reply.
@@ -1352,9 +1353,39 @@ A scope emits the following events:
 You can also listen for no match events like this:
 
 ```js
-nock.emitter.on('no match', req => {})
+nock.emitter.on('no match', (req, interceptorResults) => {
+  console.log('Request did not match any interceptors:', req.url)
+
+  if (interceptorResults && interceptorResults.length > 0) {
+    interceptorResults.forEach(({ interceptor, reasons }) => {
+      console.log(
+        'Interceptor:',
+        interceptor.method,
+        interceptor.basePath + interceptor.path,
+      )
+      console.log('Reasons:', reasons)
+    })
+  }
+})
 ```
 
+The callback receives two parameters:
+
+- `req` - The request object that didn't match
+- `interceptorResults` - An array of objects containing detailed information about each interceptor that was tested.
+  Each object contains:
+  - `interceptor` - The interceptor that was tested against the request
+  - `reasons` - An array of strings describing why the request didn't match this interceptor
+    > ⚠️ **Experimental**: The structure and format of the detailed mismatch information may change in future versions as we gather user feedback and refine the API. The feature itself is stable and ready for use and we're seeking community input on the API design before marking it stable.
+
+Common mismatch reasons include:
+
+- **Method mismatch**: `"Method mismatch: expected GET, got POST"`
+- **Path mismatch**: `"Path mismatch: expected /api/users, got /api/posts"`
+- **Header mismatch**: `"Header mismatch: expected authorization to match Bearer token, got null"`
+- **Body mismatch**: `"Body mismatch: expected "expected body", got actual body"`
+- **Query mismatch**: `"query matching failed"`
+
 ## Nock Back
 
 Fixture recording support and playback.

package/lib/handle-request.js

@@ -34,9 +34,16 @@ async function handleRequest(request) {
         requestBodyIsUtf8Representable ? 'utf8' : 'hex',
       )
 
-      const matchedInterceptor = interceptors.find(i =>
-        i.match(request, requestBodyString),
-      )
+      const matchResults = []
+      const matchedInterceptor = interceptors.find(i => {
+        const reasons = i.match(request, requestBodyString)
+        if (reasons.length > 0) {
+          matchResults.push({ interceptor: i, reasons })
+          return false
+        } else {
+          return true
+        }
+      })
 
       if (matchedInterceptor) {
         matchedInterceptor.scope.logger(
@@ -54,7 +61,11 @@ async function handleRequest(request) {
 
         return response
       } else {
-        globalEmitter.emit('no match', request)
+        globalEmitter.emit(
+          'no match',
+          request,
+          matchResults.sort((a, b) => a.reasons.length - b.reasons.length),
+        )
 
         // Try to find a hostname match that allows unmocked.
         const allowUnmocked = interceptors.some(

package/lib/interceptor.js

@@ -224,21 +224,21 @@ module.exports = class Interceptor {
   /**
    * @param {Request} request
    * @param {string} body - string or hex
+   * @returns {string[]}
    */
   match(request, body) {
     const url = new URL(request.url)
     // TODO: fix request log to string
     this.scope.logger('attempting match %j, body = %j', request, body)
 
+    const mismatches = []
     let path = url.pathname + url.search
-    let matches
     let matchKey
 
     if (this.method !== request.method) {
-      this.scope.logger(
-        `Method did not match. Request ${request.method} Interceptor ${this.method}`,
-      )
-      return false
+      const msg = `Method mismatch: expected ${this.method}, got ${request.method}`
+      this.scope.logger(msg)
+      mismatches.push(msg)
     }
 
     if (this.scope.transformPathFunction) {
@@ -254,12 +254,15 @@ module.exports = class Interceptor {
       }
     }
 
-    if (
-      !this.scope.matchHeaders.every(requestMatchesFilter) ||
-      !this.interceptorMatchHeaders.every(requestMatchesFilter)
-    ) {
-      this.scope.logger("headers don't match")
-      return false
+    for (const header of [
+      ...this.scope.matchHeaders,
+      ...this.interceptorMatchHeaders,
+    ]) {
+      if (!requestMatchesFilter(header)) {
+        const msg = `Header mismatch: expected ${header.name} to match ${header.value}, got ${request.headers.get(header.name)}`
+        this.scope.logger(msg)
+        mismatches.push(msg)
+      }
     }
 
     const reqHeadersMatch = Object.keys(this.reqheaders).every(key =>
@@ -271,18 +274,18 @@ module.exports = class Interceptor {
     )
 
     if (!reqHeadersMatch) {
-      this.scope.logger("headers don't match")
-      return false
+      const msg = "Request headers don't match"
+      this.scope.logger(msg)
+      mismatches.push(msg)
     }
 
     if (
       this.scope.scopeOptions.conditionally &&
       !this.scope.scopeOptions.conditionally()
     ) {
-      this.scope.logger(
-        'matching failed because Scope.conditionally() did not validate',
-      )
-      return false
+      const msg = 'conditionally() did not validate'
+      this.scope.logger(msg)
+      mismatches.push(msg)
     }
 
     const badHeaders = this.badheaders.filter(header =>
@@ -290,8 +293,9 @@ module.exports = class Interceptor {
     )
 
     if (badHeaders.length) {
-      this.scope.logger('request contains bad headers', ...badHeaders)
-      return false
+      const msg = `Request contains bad headers: ${badHeaders.join(', ')}`
+      this.scope.logger(msg)
+      mismatches.push(msg)
     }
 
     // Match query strings when using query()
@@ -302,12 +306,10 @@ module.exports = class Interceptor {
       const [pathname, search] = path.split('?')
       const matchQueries = this.matchQuery({ search })
 
-      this.scope.logger(
-        matchQueries ? 'query matching succeeded' : 'query matching failed',
-      )
-
       if (!matchQueries) {
-        return false
+        const msg = 'query matching failed'
+        this.scope.logger(msg)
+        mismatches.push(msg)
       }
 
       // If the query string was explicitly checked then subsequent checks against
@@ -325,37 +327,37 @@ module.exports = class Interceptor {
       matchKey = common.normalizeOrigin(url)
     }
 
-    if (typeof this.uri === 'function') {
-      matches =
-        common.matchStringOrRegexp(matchKey, this.basePath) &&
-        // This is a false positive, as `uri` is not bound to `this`.
-
-        this.uri.call(this, path)
-    } else {
-      matches =
-        common.matchStringOrRegexp(matchKey, this.basePath) &&
-        common.matchStringOrRegexp(path, this.path)
+    if (!common.matchStringOrRegexp(matchKey, this.basePath)) {
+      const msg = `Base path mismatch: expected ${this.basePath}, got ${matchKey}`
+      this.scope.logger(msg)
+      mismatches.push(msg)
     }
 
-    this.scope.logger(`matching ${matchKey}${path} to ${this._key}: ${matches}`)
+    if (typeof this.uri === 'function') {
+      if (!this.uri.call(this, path)) {
+        const msg = `Path function mismatch: expected function to return true for ${path}`
+        this.scope.logger(msg)
+        mismatches.push(msg)
+      }
+    } else if (!common.matchStringOrRegexp(path, this.path)) {
+      const msg = `Path mismatch: expected ${this.path}, got ${path}`
+      this.scope.logger(msg)
+      mismatches.push(msg)
+    }
 
-    if (matches && this._requestBody !== undefined) {
+    if (this._requestBody !== undefined) {
       if (this.scope.transformRequestBodyFunction) {
         body = this.scope.transformRequestBodyFunction(body, this._requestBody)
       }
 
-      matches = matchBody(request, this._requestBody, body)
-      if (!matches) {
-        this.scope.logger(
-          "bodies don't match: \n",
-          this._requestBody,
-          '\n',
-          body,
-        )
+      if (!matchBody(request, this._requestBody, body)) {
+        const msg = `Body mismatch: expected ${stringify(this._requestBody)}, got ${body}`
+        this.scope.logger(msg)
+        mismatches.push(msg)
       }
     }
 
-    return matches
+    return mismatches
   }
 
   /**

package/package.json

@@ -7,7 +7,7 @@
     "testing",
     "isolation"
   ],
-  "version": "15.0.0-beta.5",
+  "version": "15.0.0",
   "author": "Pedro Teixeira <pedro.teixeira@gmail.com>",
   "repository": {
     "type": "git",
@@ -22,7 +22,7 @@
   "main": "./index.js",
   "types": "types",
   "dependencies": {
-    "@mswjs/interceptors": "^0.39.3",
+    "@mswjs/interceptors": "^0.39.5",
     "json-stringify-safe": "^5.0.1"
   },
   "devDependencies": {
@@ -42,10 +42,11 @@
     "globals": "^16.1.0",
     "got": "^11.8.6",
     "jest": "^29.7.0",
-    "mocha": "^9.1.3",
+    "mocha": "^11.7.2",
     "npm-run-all": "^4.1.5",
     "nyc": "^15.0.0",
     "prettier": "3.2.5",
+    "proxyquire": "^2.1.0",
     "rimraf": "^3.0.0",
     "semantic-release": "^24.1.0",
     "sinon": "^17.0.1",

package/types/index.d.ts

@@ -32,7 +32,7 @@ declare namespace nock {
   function abortPendingRequests(): void
 
   let back: Back
-  let emitter: NodeJS.EventEmitter
+  let emitter: NockEmitter
   let recorder: Recorder
 
   type InterceptFunction = (
@@ -87,6 +87,42 @@ declare namespace nock {
     | readonly [StatusCode, ReplyBody]
     | readonly [StatusCode, ReplyBody, ReplyHeaders]
 
+  /**
+   * Detailed mismatch information for the 'no match' event
+   * @experimental This interface may change in future versions based on community feedback.
+   */
+  interface InterceptorMatchResult {
+    interceptor: Interceptor
+    reasons: string[]
+  }
+
+  /**
+   * Enhanced global emitter with typed 'no match' event
+   */
+  interface NockEmitter extends NodeJS.EventEmitter {
+    on(event: 'no match', listener: (req: Request) => void): this
+    on(
+      event: 'no match',
+      listener: (
+        req: Request,
+        interceptorResults?: InterceptorMatchResult[],
+      ) => void,
+    ): this
+    once(event: 'no match', listener: (req: Request) => void): this
+    once(
+      event: 'no match',
+      listener: (
+        req: Request,
+        interceptorResults?: InterceptorMatchResult[],
+      ) => void,
+    ): this
+    emit(
+      event: 'no match',
+      req: Request,
+      interceptorResults?: InterceptorMatchResult[],
+    ): boolean
+  }
+
   interface Scope extends NodeJS.EventEmitter {
     get: InterceptFunction
     post: InterceptFunction