msw 2.10.5 → 2.11.1

package/src/core/handlers/GraphQLHandler.ts

@@ -21,15 +21,15 @@ import { toPublicUrl } from '../utils/request/toPublicUrl'
 import { devUtils } from '../utils/internal/devUtils'
 import { getAllRequestCookies } from '../utils/request/getRequestCookies'
 
-export type ExpectedOperationTypeNode = OperationTypeNode | 'all'
+export type GraphQLOperationType = OperationTypeNode | 'all'
 export type GraphQLHandlerNameSelector = DocumentNode | RegExp | string
 
 export type GraphQLQuery = Record<string, any> | null
 export type GraphQLVariables = Record<string, any>
 
 export interface GraphQLHandlerInfo extends RequestHandlerDefaultInfo {
-  operationType: ExpectedOperationTypeNode
-  operationName: GraphQLHandlerNameSelector
+  operationType: GraphQLOperationType
+  operationName: GraphQLHandlerNameSelector | GraphQLCustomPredicate
 }
 
 export type GraphQLRequestParsedResult = {
@@ -77,6 +77,21 @@ export type GraphQLResponseBody<BodyType extends DefaultBodyType> =
   | null
   | undefined
 
+export type GraphQLCustomPredicate = (args: {
+  request: Request
+  query: string
+  operationType: GraphQLOperationType
+  operationName: string
+  variables: GraphQLVariables
+  cookies: Record<string, string>
+}) => GraphQLCustomPredicateResult | Promise<GraphQLCustomPredicateResult>
+
+export type GraphQLCustomPredicateResult = boolean | { matches: boolean }
+
+export type GraphQLPredicate =
+  | GraphQLHandlerNameSelector
+  | GraphQLCustomPredicate
+
 export function isDocumentNode(
   value: DocumentNode | any,
 ): value is DocumentNode {
@@ -100,16 +115,16 @@ export class GraphQLHandler extends RequestHandler<
   >()
 
   constructor(
-    operationType: ExpectedOperationTypeNode,
-    operationName: GraphQLHandlerNameSelector,
+    operationType: GraphQLOperationType,
+    predicate: GraphQLPredicate,
     endpoint: Path,
     resolver: ResponseResolver<GraphQLResolverExtras<any>, any, any>,
     options?: RequestHandlerOptions,
   ) {
-    let resolvedOperationName = operationName
+    let resolvedOperationName = predicate
 
-    if (isDocumentNode(operationName)) {
-      const parsedNode = parseDocumentNode(operationName)
+    if (isDocumentNode(resolvedOperationName)) {
+      const parsedNode = parseDocumentNode(resolvedOperationName)
 
       if (parsedNode.operationType !== operationType) {
         throw new Error(
@@ -126,10 +141,15 @@ export class GraphQLHandler extends RequestHandler<
       resolvedOperationName = parsedNode.operationName
     }
 
+    const displayOperationName =
+      typeof resolvedOperationName === 'function'
+        ? '[custom predicate]'
+        : resolvedOperationName
+
     const header =
       operationType === 'all'
         ? `${operationType} (origin: ${endpoint.toString()})`
-        : `${operationType} ${resolvedOperationName} (origin: ${endpoint.toString()})`
+        : `${operationType}${displayOperationName ? ` ${displayOperationName}` : ''} (origin: ${endpoint.toString()})`
 
     super({
       info: {
@@ -175,7 +195,10 @@ export class GraphQLHandler extends RequestHandler<
     const cookies = getAllRequestCookies(args.request)
 
     if (!match.matches) {
-      return { match, cookies }
+      return {
+        match,
+        cookies,
+      }
     }
 
     const parsedResult = await this.parseGraphQLRequestOrGetFromCache(
@@ -183,7 +206,10 @@ export class GraphQLHandler extends RequestHandler<
     )
 
     if (typeof parsedResult === 'undefined') {
-      return { match, cookies }
+      return {
+        match,
+        cookies,
+      }
     }
 
     return {
@@ -196,10 +222,10 @@ export class GraphQLHandler extends RequestHandler<
     }
   }
 
-  predicate(args: {
+  async predicate(args: {
     request: Request
     parsedResult: GraphQLRequestParsedResult
-  }) {
+  }): Promise<boolean> {
     if (args.parsedResult.operationType === undefined) {
       return false
     }
@@ -218,10 +244,16 @@ Consider naming this operation or using "graphql.operation()" request handler to
       this.info.operationType === 'all' ||
       args.parsedResult.operationType === this.info.operationType
 
-    const hasMatchingOperationName =
-      this.info.operationName instanceof RegExp
-        ? this.info.operationName.test(args.parsedResult.operationName || '')
-        : args.parsedResult.operationName === this.info.operationName
+    /**
+     * Check if the operation name matches the outgoing GraphQL request.
+     * @note Unlike the HTTP handler, the custom predicate functions are invoked
+     * during predicate, not parsing, because GraphQL request parsing happens first,
+     * and non-GraphQL requests are filtered out automatically.
+     */
+    const hasMatchingOperationName = await this.matchOperationName({
+      request: args.request,
+      parsedResult: args.parsedResult,
+    })
 
     return (
       args.parsedResult.match.matches &&
@@ -230,12 +262,44 @@ Consider naming this operation or using "graphql.operation()" request handler to
     )
   }
 
+  private async matchOperationName(args: {
+    request: Request
+    parsedResult: GraphQLRequestParsedResult
+  }): Promise<boolean> {
+    if (typeof this.info.operationName === 'function') {
+      const customPredicateResult = await this.info.operationName({
+        request: args.request,
+        ...this.extendResolverArgs({
+          request: args.request,
+          parsedResult: args.parsedResult,
+        }),
+      })
+
+      /**
+       * @note Keep the { matches } signature in case we decide to support path parameters
+       * in GraphQL handlers. If that happens, the custom predicate would have to be moved
+       * to the parsing phase, the same as we have for the HttpHandler, and the user will
+       * have a possibility to return parsed path parameters from the custom predicate.
+       */
+      return typeof customPredicateResult === 'boolean'
+        ? customPredicateResult
+        : customPredicateResult.matches
+    }
+
+    if (this.info.operationName instanceof RegExp) {
+      return this.info.operationName.test(args.parsedResult.operationName || '')
+    }
+
+    return args.parsedResult.operationName === this.info.operationName
+  }
+
   protected extendResolverArgs(args: {
     request: Request
     parsedResult: GraphQLRequestParsedResult
   }) {
     return {
       query: args.parsedResult.query || '',
+      operationType: args.parsedResult.operationType!,
       operationName: args.parsedResult.operationName || '',
       variables: args.parsedResult.variables || {},
       cookies: args.parsedResult.cookies,

package/src/core/handlers/HttpHandler.test.ts

@@ -1,6 +1,4 @@
-/**
- * @vitest-environment jsdom
- */
+// @vitest-environment jsdom
 import { createRequestId } from '@mswjs/interceptors'
 import { HttpHandler, HttpRequestResolverExtras } from './HttpHandler'
 import { HttpResponse } from '..'
@@ -13,7 +11,7 @@ const resolver: ResponseResolver<
 }
 
 describe('info', () => {
-  test('exposes request handler information', () => {
+  it('exposes request handler information', () => {
     const handler = new HttpHandler('GET', '/user/:userId', resolver)
 
     expect(handler.info.header).toEqual('GET /user/:userId')
@@ -24,7 +22,7 @@ describe('info', () => {
 })
 
 describe('parse', () => {
-  test('parses a URL given a matching request', async () => {
+  it('parses a URL given a matching request', async () => {
     const handler = new HttpHandler('GET', '/user/:userId', resolver)
     const request = new Request(new URL('/user/abc-123', location.href))
 
@@ -39,7 +37,7 @@ describe('parse', () => {
     })
   })
 
-  test('parses a URL and ignores the request method', async () => {
+  it('parses a URL and ignores the request method', async () => {
     const handler = new HttpHandler('GET', '/user/:userId', resolver)
     const request = new Request(new URL('/user/def-456', location.href), {
       method: 'POST',
@@ -56,7 +54,7 @@ describe('parse', () => {
     })
   })
 
-  test('returns negative match result given a non-matching request', async () => {
+  it('returns negative match result given a non-matching request', async () => {
     const handler = new HttpHandler('GET', '/user/:userId', resolver)
     const request = new Request(new URL('/login', location.href))
 
@@ -71,21 +69,21 @@ describe('parse', () => {
 })
 
 describe('predicate', () => {
-  test('returns true given a matching request', async () => {
+  it('returns true given a matching request', async () => {
     const handler = new HttpHandler('POST', '/login', resolver)
     const request = new Request(new URL('/login', location.href), {
       method: 'POST',
     })
 
-    expect(
+    await expect(
       handler.predicate({
         request,
         parsedResult: await handler.parse({ request }),
       }),
-    ).toBe(true)
+    ).resolves.toBe(true)
   })
 
-  test('respects RegExp as the request method', async () => {
+  it('supports RegExp as the request method', async () => {
     const handler = new HttpHandler(/.+/, '/login', resolver)
     const requests = [
       new Request(new URL('/login', location.href)),
@@ -94,30 +92,60 @@ describe('predicate', () => {
     ]
 
     for (const request of requests) {
-      expect(
+      await expect(
         handler.predicate({
           request,
           parsedResult: await handler.parse({ request }),
         }),
-      ).toBe(true)
+      ).resolves.toBe(true)
     }
   })
 
-  test('returns false given a non-matching request', async () => {
+  it('returns false given a non-matching request', async () => {
     const handler = new HttpHandler('POST', '/login', resolver)
     const request = new Request(new URL('/user/abc-123', location.href))
 
-    expect(
+    await expect(
       handler.predicate({
         request,
         parsedResult: await handler.parse({ request }),
       }),
-    ).toBe(false)
+    ).resolves.toBe(false)
+  })
+
+  it('supports custom predicate function', async () => {
+    const handler = new HttpHandler(
+      'GET',
+      ({ request }) => {
+        return new URL(request.url).searchParams.get('a') === '1'
+      },
+      resolver,
+    )
+
+    {
+      const request = new Request(new URL('/login?a=1', location.href))
+      await expect(
+        handler.predicate({
+          request,
+          parsedResult: await handler.parse({ request }),
+        }),
+      ).resolves.toBe(true)
+    }
+
+    {
+      const request = new Request(new URL('/login', location.href))
+      await expect(
+        handler.predicate({
+          request,
+          parsedResult: await handler.parse({ request }),
+        }),
+      ).resolves.toBe(false)
+    }
   })
 })
 
 describe('test', () => {
-  test('returns true given a matching request', async () => {
+  it('returns true given a matching request', async () => {
     const handler = new HttpHandler('GET', '/user/:userId', resolver)
     const firstTest = await handler.test({
       request: new Request(new URL('/user/abc-123', location.href)),
@@ -130,7 +158,7 @@ describe('test', () => {
     expect(secondTest).toBe(true)
   })
 
-  test('returns false given a non-matching request', async () => {
+  it('returns false given a non-matching request', async () => {
     const handler = new HttpHandler('GET', '/user/:userId', resolver)
     const firstTest = await handler.test({
       request: new Request(new URL('/login', location.href)),
@@ -149,7 +177,7 @@ describe('test', () => {
 })
 
 describe('run', () => {
-  test('returns a mocked response given a matching request', async () => {
+  it('returns a mocked response given a matching request', async () => {
     const handler = new HttpHandler('GET', '/user/:userId', resolver)
     const request = new Request(new URL('/user/abc-123', location.href))
     const requestId = createRequestId()
@@ -169,10 +197,12 @@ describe('run', () => {
     expect(result!.request.url).toBe('http://localhost/user/abc-123')
     expect(result!.response?.status).toBe(200)
     expect(result!.response?.statusText).toBe('OK')
-    expect(await result?.response?.json()).toEqual({ userId: 'abc-123' })
+    await expect(result?.response?.json()).resolves.toEqual({
+      userId: 'abc-123',
+    })
   })
 
-  test('returns null given a non-matching request', async () => {
+  it('returns null given a non-matching request', async () => {
     const handler = new HttpHandler('POST', '/login', resolver)
     const result = await handler.run({
       request: new Request(new URL('/users', location.href)),
@@ -182,7 +212,7 @@ describe('run', () => {
     expect(result).toBeNull()
   })
 
-  test('returns an empty "params" object given request with no URL parameters', async () => {
+  it('returns an empty "params" object given request with no URL parameters', async () => {
     const handler = new HttpHandler('GET', '/users', resolver)
     const result = await handler.run({
       request: new Request(new URL('/users', location.href)),
@@ -192,7 +222,7 @@ describe('run', () => {
     expect(result?.parsedResult?.match?.params).toEqual({})
   })
 
-  test('exhausts resolver until its generator completes', async () => {
+  it('exhausts resolver until its generator completes', async () => {
     const handler = new HttpHandler('GET', '/users', function* () {
       let count = 0
 
@@ -212,12 +242,12 @@ describe('run', () => {
       return result?.response?.text()
     }
 
-    expect(await run()).toBe('pending')
-    expect(await run()).toBe('pending')
-    expect(await run()).toBe('pending')
-    expect(await run()).toBe('pending')
-    expect(await run()).toBe('pending')
-    expect(await run()).toBe('complete')
-    expect(await run()).toBe('complete')
+    await expect(run()).resolves.toBe('pending')
+    await expect(run()).resolves.toBe('pending')
+    await expect(run()).resolves.toBe('pending')
+    await expect(run()).resolves.toBe('pending')
+    await expect(run()).resolves.toBe('pending')
+    await expect(run()).resolves.toBe('complete')
+    await expect(run()).resolves.toBe('complete')
   })
 })

package/src/core/handlers/HttpHandler.ts

@@ -25,7 +25,7 @@ type HttpHandlerMethod = string | RegExp
 
 export interface HttpHandlerInfo extends RequestHandlerDefaultInfo {
   method: HttpHandlerMethod
-  path: Path
+  path: HttpRequestPredicate<PathParams>
 }
 
 export enum HttpMethods {
@@ -52,6 +52,24 @@ export type HttpRequestResolverExtras<Params extends PathParams> = {
   cookies: Record<string, string>
 }
 
+export type HttpCustomPredicate<Params extends PathParams> = (args: {
+  request: Request
+  cookies: Record<string, string>
+}) =>
+  | HttpCustomPredicateResult<Params>
+  | Promise<HttpCustomPredicateResult<Params>>
+
+export type HttpCustomPredicateResult<Params extends PathParams> =
+  | boolean
+  | {
+      matches: boolean
+      params: Params
+    }
+
+export type HttpRequestPredicate<Params extends PathParams> =
+  | Path
+  | HttpCustomPredicate<Params>
+
 /**
  * Request handler for HTTP requests.
  * Provides request matching based on method and URL.
@@ -63,14 +81,17 @@ export class HttpHandler extends RequestHandler<
 > {
   constructor(
     method: HttpHandlerMethod,
-    path: Path,
+    predicate: HttpRequestPredicate<PathParams>,
     resolver: ResponseResolver<HttpRequestResolverExtras<any>, any, any>,
     options?: RequestHandlerOptions,
   ) {
+    const displayPath =
+      typeof predicate === 'function' ? '[custom predicate]' : predicate
+
     super({
       info: {
-        header: `${method} ${path}`,
-        path,
+        header: `${method}${displayPath ? ` ${displayPath}` : ''}`,
+        path: predicate,
         method,
       },
       resolver,
@@ -83,7 +104,7 @@ export class HttpHandler extends RequestHandler<
   private checkRedundantQueryParameters() {
     const { method, path } = this.info
 
-    if (path instanceof RegExp) {
+    if (!path || path instanceof RegExp || typeof path === 'function') {
       return
     }
 
@@ -95,7 +116,7 @@ export class HttpHandler extends RequestHandler<
     }
 
     const searchParams = getSearchParams(path)
-    const queryParams: string[] = []
+    const queryParams: Array<string> = []
 
     searchParams.forEach((_, paramName) => {
       queryParams.push(paramName)
@@ -111,20 +132,48 @@ export class HttpHandler extends RequestHandler<
     resolutionContext?: ResponseResolutionContext
   }) {
     const url = new URL(args.request.url)
-    const match = matchRequestUrl(
-      url,
-      this.info.path,
-      args.resolutionContext?.baseUrl,
-    )
     const cookies = getAllRequestCookies(args.request)
 
+    /**
+     * Handle custom predicate functions.
+     * @note Invoke this during parsing so the user can parse the path parameters
+     * manually. Otherwise, `params` is always an empty object, which isn't nice.
+     */
+    if (typeof this.info.path === 'function') {
+      const customPredicateResult = await this.info.path({
+        request: args.request,
+        cookies,
+      })
+
+      const match =
+        typeof customPredicateResult === 'boolean'
+          ? {
+              matches: customPredicateResult,
+              params: {},
+            }
+          : customPredicateResult
+
+      return {
+        match,
+        cookies,
+      }
+    }
+
+    const match = this.info.path
+      ? matchRequestUrl(url, this.info.path, args.resolutionContext?.baseUrl)
+      : { matches: false, params: {} }
+
     return {
       match,
       cookies,
     }
   }
 
-  predicate(args: { request: Request; parsedResult: HttpRequestParsedResult }) {
+  async predicate(args: {
+    request: Request
+    parsedResult: HttpRequestParsedResult
+    resolutionContext?: ResponseResolutionContext
+  }) {
     const hasMatchingMethod = this.matchMethod(args.request.method)
     const hasMatchingUrl = args.parsedResult.match.matches
     return hasMatchingMethod && hasMatchingUrl

package/src/core/handlers/RequestHandler.ts

@@ -179,7 +179,7 @@ export abstract class RequestHandler<
     request: Request
     parsedResult: ParsedResult
     resolutionContext?: ResponseResolutionContext
-  }): boolean
+  }): boolean | Promise<boolean>
 
   /**
    * Print out the successfully handled request.
@@ -273,7 +273,7 @@ export abstract class RequestHandler<
       request: args.request,
       resolutionContext: args.resolutionContext,
     })
-    const shouldInterceptRequest = this.predicate({
+    const shouldInterceptRequest = await this.predicate({
       request: args.request,
       parsedResult,
       resolutionContext: args.resolutionContext,

package/src/core/http.ts

@@ -7,8 +7,9 @@ import {
   HttpMethods,
   HttpHandler,
   HttpRequestResolverExtras,
+  HttpRequestPredicate,
 } from './handlers/HttpHandler'
-import type { Path, PathParams } from './utils/matching/matchRequestUrl'
+import type { PathParams } from './utils/matching/matchRequestUrl'
 
 export type HttpRequestHandler = <
   Params extends PathParams<keyof Params> = PathParams,
@@ -18,9 +19,8 @@ export type HttpRequestHandler = <
   // returns plain "Response" and the one returning "HttpResponse"
   // to enforce a stricter response body type.
   ResponseBodyType extends DefaultBodyType = undefined,
-  RequestPath extends Path = Path,
 >(
-  path: RequestPath,
+  predicate: HttpRequestPredicate<Params>,
   resolver: HttpResponseResolver<Params, RequestBodyType, ResponseBodyType>,
   options?: RequestHandlerOptions,
 ) => HttpHandler
@@ -38,8 +38,8 @@ export type HttpResponseResolver<
 function createHttpHandler<Method extends HttpMethods | RegExp>(
   method: Method,
 ): HttpRequestHandler {
-  return (path, resolver, options = {}) => {
-    return new HttpHandler(method, path, resolver, options)
+  return (predicate, resolver, options = {}) => {
+    return new HttpHandler(method, predicate, resolver, options)
   }
 }
 

package/src/core/index.ts

@@ -42,6 +42,7 @@ export type {
 export type {
   RequestQuery,
   HttpRequestParsedResult,
+  HttpCustomPredicate,
 } from './handlers/HttpHandler'
 export type { HttpRequestHandler, HttpResponseResolver } from './http'
 
@@ -51,6 +52,8 @@ export type {
   GraphQLRequestBody,
   GraphQLResponseBody,
   GraphQLJsonRequestBody,
+  GraphQLOperationType,
+  GraphQLCustomPredicate,
 } from './handlers/GraphQLHandler'
 export type { GraphQLRequestHandler, GraphQLResponseResolver } from './graphql'