msw 2.0.12 → 2.0.13

package/src/core/utils/handleRequest.test.ts

@@ -0,0 +1,554 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { Emitter } from 'strict-event-emitter'
+import { LifeCycleEventsMap, SharedOptions } from '../sharedOptions'
+import { RequestHandler } from '../handlers/RequestHandler'
+import { http } from '../http'
+import { handleRequest, HandleRequestOptions } from './handleRequest'
+import { RequiredDeep } from '../typeUtils'
+import { uuidv4 } from './internal/uuidv4'
+import { HttpResponse } from '../HttpResponse'
+import { passthrough } from '../passthrough'
+
+const options: RequiredDeep<SharedOptions> = {
+  onUnhandledRequest: vi.fn(),
+}
+const handleRequestOptions: Partial<Record<keyof HandleRequestOptions, any>> = {
+  onPassthroughResponse: vi.fn(),
+  onMockedResponse: vi.fn(),
+}
+
+function setup() {
+  const emitter = new Emitter<LifeCycleEventsMap>()
+  const listener = vi.fn()
+
+  const createMockListener = (name: string) => {
+    return (...args: any) => {
+      listener(name, ...args)
+    }
+  }
+
+  emitter.on('request:start', createMockListener('request:start'))
+  emitter.on('request:match', createMockListener('request:match'))
+  emitter.on('request:unhandled', createMockListener('request:unhandled'))
+  emitter.on('request:end', createMockListener('request:end'))
+  emitter.on('response:mocked', createMockListener('response:mocked'))
+  emitter.on('response:bypass', createMockListener('response:bypass'))
+
+  const events = listener.mock.calls
+  return { emitter, events }
+}
+
+beforeEach(() => {
+  vi.spyOn(global.console, 'warn').mockImplementation(() => void 0)
+})
+
+afterEach(() => {
+  vi.resetAllMocks()
+})
+
+test('returns undefined for a request with the "x-msw-intention" header equal to "bypass"', async () => {
+  const { emitter, events } = setup()
+
+  const requestId = uuidv4()
+  const request = new Request(new URL('http://localhost/user'), {
+    headers: new Headers({
+      'x-msw-intention': 'bypass',
+    }),
+  })
+  const handlers: Array<RequestHandler> = []
+
+  const result = await handleRequest(
+    request,
+    requestId,
+    handlers,
+    options,
+    emitter,
+    handleRequestOptions,
+  )
+
+  expect(result).toBeUndefined()
+  expect(events).toEqual([
+    ['request:start', { request, requestId }],
+    ['request:end', { request, requestId }],
+  ])
+  expect(options.onUnhandledRequest).not.toHaveBeenCalled()
+  expect(handleRequestOptions.onPassthroughResponse).toHaveBeenNthCalledWith(
+    1,
+    request,
+  )
+  expect(handleRequestOptions.onMockedResponse).not.toHaveBeenCalled()
+})
+
+test('does not bypass a request with "x-msw-intention" header set to arbitrary value', async () => {
+  const { emitter } = setup()
+
+  const request = new Request(new URL('http://localhost/user'), {
+    headers: new Headers({
+      'x-msw-intention': 'invalid',
+    }),
+  })
+  const handlers: Array<RequestHandler> = [
+    http.get('/user', () => {
+      return HttpResponse.text('hello world')
+    }),
+  ]
+
+  const result = await handleRequest(
+    request,
+    uuidv4(),
+    handlers,
+    options,
+    emitter,
+    handleRequestOptions,
+  )
+
+  expect(result).not.toBeUndefined()
+  expect(options.onUnhandledRequest).not.toHaveBeenCalled()
+  expect(handleRequestOptions.onMockedResponse).toHaveBeenCalledTimes(1)
+})
+
+test('reports request as unhandled when it has no matching request handlers', async () => {
+  const { emitter, events } = setup()
+
+  const requestId = uuidv4()
+  const request = new Request(new URL('http://localhost/user'))
+  const handlers: Array<RequestHandler> = []
+
+  const result = await handleRequest(
+    request,
+    requestId,
+    handlers,
+    options,
+    emitter,
+    handleRequestOptions,
+  )
+
+  expect(result).toBeUndefined()
+  expect(events).toEqual([
+    ['request:start', { request, requestId }],
+    ['request:unhandled', { request, requestId }],
+    ['request:end', { request, requestId }],
+  ])
+  expect(options.onUnhandledRequest).toHaveBeenNthCalledWith(1, request, {
+    warning: expect.any(Function),
+    error: expect.any(Function),
+  })
+  expect(handleRequestOptions.onPassthroughResponse).toHaveBeenNthCalledWith(
+    1,
+    request,
+  )
+  expect(handleRequestOptions.onMockedResponse).not.toHaveBeenCalled()
+})
+
+test('returns undefined on a request handler that returns no response', async () => {
+  const { emitter, events } = setup()
+
+  const requestId = uuidv4()
+  const request = new Request(new URL('http://localhost/user'))
+  const handlers: Array<RequestHandler> = [
+    http.get('/user', () => {
+      // Intentionally blank response resolver.
+      return
+    }),
+  ]
+
+  const result = await handleRequest(
+    request,
+    requestId,
+    handlers,
+    options,
+    emitter,
+    handleRequestOptions,
+  )
+
+  expect(result).toBeUndefined()
+  expect(events).toEqual([
+    ['request:start', { request, requestId }],
+    ['request:end', { request, requestId }],
+  ])
+  expect(options.onUnhandledRequest).not.toHaveBeenCalled()
+  expect(handleRequestOptions.onPassthroughResponse).toHaveBeenNthCalledWith(
+    1,
+    request,
+  )
+  expect(handleRequestOptions.onMockedResponse).not.toHaveBeenCalled()
+
+  /**
+   * @note Returning undefined from a resolver no longer prints a warning.
+   */
+  expect(console.warn).toHaveBeenCalledTimes(0)
+})
+
+test('returns the mocked response for a request with a matching request handler', async () => {
+  const { emitter, events } = setup()
+
+  const requestId = uuidv4()
+  const request = new Request(new URL('http://localhost/user'))
+  const mockedResponse = HttpResponse.json({ firstName: 'John' })
+  const handlers: Array<RequestHandler> = [
+    http.get('/user', () => {
+      return mockedResponse
+    }),
+  ]
+  const lookupResult = {
+    handler: handlers[0],
+    response: mockedResponse,
+    request,
+    parsedResult: {
+      match: { matches: true, params: {} },
+      cookies: {},
+    },
+  }
+
+  const result = await handleRequest(
+    request,
+    requestId,
+    handlers,
+    options,
+    emitter,
+    handleRequestOptions,
+  )
+
+  expect(result).toEqual(mockedResponse)
+  expect(events).toEqual([
+    ['request:start', { request, requestId }],
+    ['request:match', { request, requestId }],
+    ['request:end', { request, requestId }],
+  ])
+  expect(handleRequestOptions.onPassthroughResponse).not.toHaveBeenCalled()
+
+  expect(handleRequestOptions.onMockedResponse).toHaveBeenCalledTimes(1)
+  const [mockedResponseParam, lookupResultParam] =
+    handleRequestOptions.onMockedResponse.mock.calls[0]
+
+  expect(mockedResponseParam.status).toBe(mockedResponse.status)
+  expect(mockedResponseParam.statusText).toBe(mockedResponse.statusText)
+  expect(Object.fromEntries(mockedResponseParam.headers.entries())).toEqual(
+    Object.fromEntries(mockedResponse.headers.entries()),
+  )
+
+  expect(lookupResultParam).toEqual({
+    handler: lookupResult.handler,
+    parsedResult: lookupResult.parsedResult,
+    response: expect.objectContaining({
+      status: lookupResult.response.status,
+      statusText: lookupResult.response.statusText,
+    }),
+  })
+})
+
+test('returns a transformed response if the "transformResponse" option is provided', async () => {
+  const { emitter, events } = setup()
+
+  const requestId = uuidv4()
+  const request = new Request(new URL('http://localhost/user'))
+  const mockedResponse = HttpResponse.json({ firstName: 'John' })
+  const handlers: Array<RequestHandler> = [
+    http.get('/user', () => {
+      return mockedResponse
+    }),
+  ]
+  const transformResponseImpelemntation = (response: Response): Response => {
+    return new Response('transformed', response)
+  }
+  const transformResponse = vi
+    .fn<[Response], Response>()
+    .mockImplementation(transformResponseImpelemntation)
+  const finalResponse = transformResponseImpelemntation(mockedResponse)
+  const lookupResult = {
+    handler: handlers[0],
+    response: mockedResponse,
+    request,
+    parsedResult: {
+      match: { matches: true, params: {} },
+      cookies: {},
+    },
+  }
+
+  const result = await handleRequest(
+    request,
+    requestId,
+    handlers,
+    options,
+    emitter,
+    {
+      ...handleRequestOptions,
+      transformResponse,
+    },
+  )
+
+  expect(result?.status).toEqual(finalResponse.status)
+  expect(result?.statusText).toEqual(finalResponse.statusText)
+  expect(Object.fromEntries(result!.headers.entries())).toEqual(
+    Object.fromEntries(mockedResponse.headers.entries()),
+  )
+
+  expect(events).toEqual([
+    ['request:start', { request, requestId }],
+    ['request:match', { request, requestId }],
+    ['request:end', { request, requestId }],
+  ])
+  expect(handleRequestOptions.onPassthroughResponse).not.toHaveBeenCalled()
+
+  expect(transformResponse).toHaveBeenCalledTimes(1)
+  const [responseParam] = transformResponse.mock.calls[0]
+
+  expect(responseParam.status).toBe(mockedResponse.status)
+  expect(responseParam.statusText).toBe(mockedResponse.statusText)
+  expect(Object.fromEntries(responseParam.headers.entries())).toEqual(
+    Object.fromEntries(mockedResponse.headers.entries()),
+  )
+
+  expect(handleRequestOptions.onMockedResponse).toHaveBeenCalledTimes(1)
+  const [mockedResponseParam, lookupResultParam] =
+    handleRequestOptions.onMockedResponse.mock.calls[0]
+
+  expect(mockedResponseParam.status).toBe(finalResponse.status)
+  expect(mockedResponseParam.statusText).toBe(finalResponse.statusText)
+  expect(Object.fromEntries(mockedResponseParam.headers.entries())).toEqual(
+    Object.fromEntries(mockedResponse.headers.entries()),
+  )
+  expect(await mockedResponseParam.text()).toBe('transformed')
+
+  expect(lookupResultParam).toEqual({
+    handler: lookupResult.handler,
+    parsedResult: lookupResult.parsedResult,
+    response: expect.objectContaining({
+      status: lookupResult.response.status,
+      statusText: lookupResult.response.statusText,
+    }),
+  })
+})
+
+it('returns undefined without warning on a passthrough request', async () => {
+  const { emitter, events } = setup()
+
+  const requestId = uuidv4()
+  const request = new Request(new URL('http://localhost/user'))
+  const handlers: Array<RequestHandler> = [
+    http.get('/user', () => {
+      return passthrough()
+    }),
+  ]
+
+  const result = await handleRequest(
+    request,
+    requestId,
+    handlers,
+    options,
+    emitter,
+    handleRequestOptions,
+  )
+
+  expect(result).toBeUndefined()
+  expect(events).toEqual([
+    ['request:start', { request, requestId }],
+    ['request:end', { request, requestId }],
+  ])
+  expect(options.onUnhandledRequest).not.toHaveBeenCalled()
+  expect(handleRequestOptions.onPassthroughResponse).toHaveBeenNthCalledWith(
+    1,
+    request,
+  )
+  expect(handleRequestOptions.onMockedResponse).not.toHaveBeenCalled()
+})
+
+it('marks the first matching one-time handler as used', async () => {
+  const { emitter } = setup()
+
+  const oneTimeHandler = http.get(
+    '/resource',
+    () => {
+      return HttpResponse.text('One-time')
+    },
+    { once: true },
+  )
+  const anotherHandler = http.get('/resource', () => {
+    return HttpResponse.text('Another')
+  })
+  const handlers: Array<RequestHandler> = [oneTimeHandler, anotherHandler]
+
+  const requestId = uuidv4()
+  const request = new Request('http://localhost/resource')
+  const firstResult = await handleRequest(
+    request,
+    requestId,
+    handlers,
+    options,
+    emitter,
+    handleRequestOptions,
+  )
+
+  expect(await firstResult?.text()).toBe('One-time')
+  expect(oneTimeHandler.isUsed).toBe(true)
+  expect(anotherHandler.isUsed).toBe(false)
+
+  const secondResult = await handleRequest(
+    request,
+    requestId,
+    handlers,
+    options,
+    emitter,
+    handleRequestOptions,
+  )
+
+  expect(await secondResult?.text()).toBe('Another')
+  expect(anotherHandler.isUsed).toBe(true)
+  expect(oneTimeHandler.isUsed).toBe(true)
+})
+
+it('does not mark non-matching one-time handlers as used', async () => {
+  const { emitter } = setup()
+
+  const oneTimeHandler = http.get(
+    '/resource',
+    () => {
+      return HttpResponse.text('One-time')
+    },
+    { once: true },
+  )
+  const anotherHandler = http.get(
+    '/another',
+    () => {
+      return HttpResponse.text('Another')
+    },
+    { once: true },
+  )
+  const handlers: Array<RequestHandler> = [oneTimeHandler, anotherHandler]
+
+  const requestId = uuidv4()
+  const firstResult = await handleRequest(
+    new Request('http://localhost/another'),
+    requestId,
+    handlers,
+    options,
+    emitter,
+    handleRequestOptions,
+  )
+
+  expect(await firstResult?.text()).toBe('Another')
+  expect(oneTimeHandler.isUsed).toBe(false)
+  expect(anotherHandler.isUsed).toBe(true)
+
+  const secondResult = await handleRequest(
+    new Request('http://localhost/resource'),
+    requestId,
+    handlers,
+    options,
+    emitter,
+    handleRequestOptions,
+  )
+
+  expect(await secondResult?.text()).toBe('One-time')
+  expect(anotherHandler.isUsed).toBe(true)
+  expect(oneTimeHandler.isUsed).toBe(true)
+})
+
+it('handles parallel requests with one-time handlers', async () => {
+  const { emitter } = setup()
+
+  const oneTimeHandler = http.get(
+    '/resource',
+    () => {
+      return HttpResponse.text('One-time')
+    },
+    { once: true },
+  )
+  const anotherHandler = http.get('/resource', () => {
+    return HttpResponse.text('Another')
+  })
+  const handlers: Array<RequestHandler> = [oneTimeHandler, anotherHandler]
+
+  const requestId = uuidv4()
+  const request = new Request('http://localhost/resource')
+  const firstResultPromise = handleRequest(
+    request,
+    requestId,
+    handlers,
+    options,
+    emitter,
+    handleRequestOptions,
+  )
+  const secondResultPromise = handleRequest(
+    request,
+    requestId,
+    handlers,
+    options,
+    emitter,
+    handleRequestOptions,
+  )
+
+  const firstResult = await firstResultPromise
+  const secondResult = await secondResultPromise
+
+  expect(await firstResult?.text()).toBe('One-time')
+  expect(await secondResult?.text()).toBe('Another')
+  expect(oneTimeHandler.isUsed).toBe(true)
+  expect(anotherHandler.isUsed).toBe(true)
+})
+
+describe('[Private] - resolutionContext - used for extensions', () => {
+  describe('#baseUrl', () => {
+    test('when defined, handle requests to that base url only defining pathnames in the handler', async () => {
+      const { emitter } = setup()
+
+      const baseUrl = 'http://this-base-url-works.com'
+      const handleRequestOptionsWithBaseUrl: HandleRequestOptions = {
+        ...handleRequestOptions,
+        resolutionContext: { baseUrl },
+      }
+
+      const handler = http.get('/resource', () => {
+        return HttpResponse.text('Mocked response')
+      })
+
+      const handlers: Array<RequestHandler> = [handler]
+
+      const requestId = uuidv4()
+      const request = new Request(new URL('/resource', baseUrl))
+      const response = await handleRequest(
+        request,
+        requestId,
+        handlers,
+        options,
+        emitter,
+        handleRequestOptionsWithBaseUrl,
+      )
+
+      expect(await response?.text()).toBe('Mocked response')
+    })
+
+    test('when defined, do not handle requests to different base urls when defining pathnames in the handler', async () => {
+      const { emitter } = setup()
+
+      const baseUrl = 'http://this-base-url-works.com'
+      const handleRequestOptionsWithBaseUrl: HandleRequestOptions = {
+        ...handleRequestOptions,
+        resolutionContext: { baseUrl },
+      }
+
+      const handler = http.get('/resource', () => {
+        return HttpResponse.text('Mocked response')
+      })
+
+      const handlers: Array<RequestHandler> = [handler]
+
+      const requestId = uuidv4()
+      const request = new Request(
+        new URL('/resource', `http://not-the-base-url.com`),
+      )
+      const response = await handleRequest(
+        request,
+        requestId,
+        handlers,
+        options,
+        emitter,
+        handleRequestOptionsWithBaseUrl,
+      )
+
+      expect(response).toBeUndefined()
+    })
+  })
+})

package/src/core/utils/handleRequest.ts

@@ -0,0 +1,132 @@
+import { until } from '@open-draft/until'
+import { Emitter } from 'strict-event-emitter'
+import { RequestHandler } from '../handlers/RequestHandler'
+import { LifeCycleEventsMap, SharedOptions } from '../sharedOptions'
+import { RequiredDeep } from '../typeUtils'
+import { ResponseLookupResult, getResponse } from './getResponse'
+import { onUnhandledRequest } from './request/onUnhandledRequest'
+import { readResponseCookies } from './request/readResponseCookies'
+
+export interface HandleRequestOptions {
+  /**
+   * `resolutionContext` is not part of the general public api
+   * but is exposed to aid in creating extensions like
+   * `@mswjs/http-middleware`.
+   */
+  resolutionContext?: {
+    /**
+     * A base url to use when resolving relative urls.
+     * @note This is primarily used by the `@mswjs/http-middleware`
+     * to resolve relative urls in the context of the running server
+     */
+    baseUrl?: string
+  }
+
+  /**
+   * Transforms a `MockedResponse` instance returned from a handler
+   * to a response instance supported by the lower tooling (i.e. interceptors).
+   */
+  transformResponse?(response: Response): Response
+
+  /**
+   * Invoked whenever a request is performed as-is.
+   */
+  onPassthroughResponse?(request: Request): void
+
+  /**
+   * Invoked when the mocked response is ready to be sent.
+   */
+  onMockedResponse?(
+    response: Response,
+    handler: RequiredDeep<ResponseLookupResult>,
+  ): void
+}
+
+export async function handleRequest(
+  request: Request,
+  requestId: string,
+  handlers: Array<RequestHandler>,
+  options: RequiredDeep<SharedOptions>,
+  emitter: Emitter<LifeCycleEventsMap>,
+  handleRequestOptions?: HandleRequestOptions,
+): Promise<Response | undefined> {
+  emitter.emit('request:start', { request, requestId })
+
+  // Perform bypassed requests (i.e. issued via "ctx.fetch") as-is.
+  if (request.headers.get('x-msw-intention') === 'bypass') {
+    emitter.emit('request:end', { request, requestId })
+    handleRequestOptions?.onPassthroughResponse?.(request)
+    return
+  }
+
+  // Resolve a mocked response from the list of request handlers.
+  const lookupResult = await until(() => {
+    return getResponse(
+      request,
+      handlers,
+      handleRequestOptions?.resolutionContext,
+    )
+  })
+
+  if (lookupResult.error) {
+    // Allow developers to react to unhandled exceptions in request handlers.
+    emitter.emit('unhandledException', {
+      error: lookupResult.error,
+      request,
+      requestId,
+    })
+    throw lookupResult.error
+  }
+
+  // If the handler lookup returned nothing, no request handler was found
+  // matching this request. Report the request as unhandled.
+  if (!lookupResult.data) {
+    await onUnhandledRequest(request, handlers, options.onUnhandledRequest)
+    emitter.emit('request:unhandled', { request, requestId })
+    emitter.emit('request:end', { request, requestId })
+    handleRequestOptions?.onPassthroughResponse?.(request)
+    return
+  }
+
+  const { response } = lookupResult.data
+
+  // When the handled request returned no mocked response, warn the developer,
+  // as it may be an oversight on their part. Perform the request as-is.
+  if (!response) {
+    emitter.emit('request:end', { request, requestId })
+    handleRequestOptions?.onPassthroughResponse?.(request)
+    return
+  }
+
+  // Perform the request as-is when the developer explicitly returned "req.passthrough()".
+  // This produces no warning as the request was handled.
+  if (
+    response.status === 302 &&
+    response.headers.get('x-msw-intention') === 'passthrough'
+  ) {
+    emitter.emit('request:end', { request, requestId })
+    handleRequestOptions?.onPassthroughResponse?.(request)
+    return
+  }
+
+  // Store all the received response cookies in the virtual cookie store.
+  readResponseCookies(request, response)
+
+  emitter.emit('request:match', { request, requestId })
+
+  const requiredLookupResult =
+    lookupResult.data as RequiredDeep<ResponseLookupResult>
+
+  const transformedResponse =
+    handleRequestOptions?.transformResponse?.(response) ||
+    (response as any as Response)
+
+  handleRequestOptions?.onMockedResponse?.(
+    transformedResponse,
+    requiredLookupResult,
+  )
+
+  emitter.emit('request:end', { request, requestId })
+
+  return transformedResponse
+}

package/src/core/utils/internal/Disposable.ts

@@ -0,0 +1,9 @@
+export type DisposableSubscription = () => Promise<void> | void
+
+export class Disposable {
+  protected subscriptions: Array<DisposableSubscription> = []
+
+  public async dispose() {
+    await Promise.all(this.subscriptions.map((subscription) => subscription()))
+  }
+}

package/src/core/utils/internal/checkGlobals.ts

@@ -0,0 +1,17 @@
+import { invariant } from 'outvariant'
+import { devUtils } from './devUtils'
+
+export function checkGlobals() {
+  /**
+   * MSW expects the "URL" constructor to be defined.
+   * It's not present in React Native so suggest a polyfill
+   * instead of failing silently.
+   * @see https://github.com/mswjs/msw/issues/1408
+   */
+  invariant(
+    typeof URL !== 'undefined',
+    devUtils.formatMessage(
+      `Global "URL" class is not defined. This likely means that you're running MSW in an environment that doesn't support all Node.js standard API (e.g. React Native). If that's the case, please use an appropriate polyfill for the "URL" class, like "react-native-url-polyfill".`,
+    ),
+  )
+}