msw 2.12.13 → 2.13.0

package/src/core/experimental/frames/http-frame.test.ts

@@ -0,0 +1,360 @@
+import { http } from '../../http'
+import { graphql } from '../../graphql'
+import { ws } from '../../ws'
+import { bypass } from '../../bypass'
+import { HttpNetworkFrame, HttpNetworkFrameEventMap } from './http-frame'
+import { InMemoryHandlersController } from '#core/experimental/handlers-controller'
+
+beforeAll(() => {
+  vi.spyOn(console, 'error').mockImplementation(() => {})
+})
+
+afterEach(() => {
+  vi.clearAllMocks()
+})
+
+afterAll(() => {
+  vi.restoreAllMocks()
+})
+
+function spyOnNetworkFrame(frame: HttpNetworkFrame) {
+  const events: Array<
+    HttpNetworkFrameEventMap[keyof HttpNetworkFrameEventMap]
+  > = []
+
+  frame.events.on('*', (event) => events.push(event))
+
+  return {
+    events,
+  }
+}
+
+it('filters only request type handlers', async () => {
+  class HttpFrame extends HttpNetworkFrame {
+    respondWith = vi.fn()
+    passthrough = vi.fn()
+    errorWith = vi.fn()
+  }
+
+  const frame = new HttpFrame({
+    request: new Request('http://localhost/api'),
+  })
+
+  const httpHandlers = [http.post('http://localhost/api/user', () => {})]
+  const graphqlHandlers = [graphql.query('GetUser', () => {})]
+  const webSocketHandlers = [
+    ws.link('ws://localhost').addEventListener('connection', () => {}),
+  ]
+
+  const controller = new InMemoryHandlersController([
+    ...httpHandlers,
+    ...webSocketHandlers,
+    ...graphqlHandlers,
+  ])
+
+  expect(frame.getHandlers(controller)).toEqual([
+    ...httpHandlers,
+    ...graphqlHandlers,
+  ])
+  expect(frame.getHandlers(new InMemoryHandlersController([]))).toEqual([])
+})
+
+it('resolves a matching request', async () => {
+  class HttpFrame extends HttpNetworkFrame {
+    respondWith = vi.fn()
+    passthrough = vi.fn()
+    errorWith = vi.fn()
+  }
+
+  const frame = new HttpFrame({
+    request: new Request('http://localhost/api'),
+  })
+  const { events } = spyOnNetworkFrame(frame)
+  const unhandledFrameCallback = vi.fn()
+
+  const matches = await frame.resolve(
+    [
+      http.get('http://localhost/api', () => {
+        return new Response(null, { status: 204 })
+      }),
+    ],
+    unhandledFrameCallback,
+    { quiet: true },
+  )
+
+  expect.soft(matches).toBe(true)
+  expect.soft(frame.respondWith).toHaveBeenCalledExactlyOnceWith(
+    expect.objectContaining({
+      status: 204,
+    }),
+  )
+  expect.soft(frame.passthrough).not.toHaveBeenCalled()
+  expect.soft(frame.errorWith).not.toHaveBeenCalled()
+  expect.soft(unhandledFrameCallback).not.toHaveBeenCalled()
+  expect.soft(events).toEqual([
+    expect.objectContaining({
+      type: 'request:start',
+      requestId: frame.data.id,
+      request: frame.data.request,
+    }),
+    expect.objectContaining({
+      type: 'request:match',
+      requestId: frame.data.id,
+      request: frame.data.request,
+    }),
+    expect.objectContaining({
+      type: 'request:end',
+      requestId: frame.data.id,
+      request: frame.data.request,
+    }),
+  ])
+})
+
+it('resolves a non-matching request', async () => {
+  class HttpFrame extends HttpNetworkFrame {
+    respondWith = vi.fn()
+    passthrough = vi.fn()
+    errorWith = vi.fn()
+  }
+
+  const frame = new HttpFrame({
+    request: new Request('http://localhost/api'),
+  })
+  const { events } = spyOnNetworkFrame(frame)
+  const unhandledFrameCallback = vi.fn()
+
+  const matches = await frame.resolve(
+    [
+      http.get('http://example.com/resource', () => {
+        return new Response(null, { status: 204 })
+      }),
+    ],
+    unhandledFrameCallback,
+    { quiet: true },
+  )
+
+  expect.soft(matches).toBe(false)
+  expect.soft(frame.passthrough).toHaveBeenCalledOnce()
+  expect.soft(frame.respondWith).not.toHaveBeenCalled()
+  expect.soft(frame.errorWith).not.toHaveBeenCalled()
+  expect.soft(unhandledFrameCallback).toHaveBeenCalledExactlyOnceWith(
+    expect.objectContaining({
+      frame,
+    }),
+  )
+  expect.soft(events).toEqual([
+    expect.objectContaining({
+      type: 'request:start',
+      requestId: frame.data.id,
+      request: frame.data.request,
+    }),
+    expect.objectContaining({
+      type: 'request:unhandled',
+      requestId: frame.data.id,
+      request: frame.data.request,
+    }),
+    expect.objectContaining({
+      type: 'request:end',
+      requestId: frame.data.id,
+      request: frame.data.request,
+    }),
+  ])
+})
+
+it('resolves a matched passthrough', async () => {
+  class HttpFrame extends HttpNetworkFrame {
+    respondWith = vi.fn()
+    passthrough = vi.fn()
+    errorWith = vi.fn()
+  }
+
+  const frame = new HttpFrame({
+    request: new Request('http://localhost/api'),
+  })
+  const { events } = spyOnNetworkFrame(frame)
+  const unhandledFrameCallback = vi.fn()
+
+  const matches = await frame.resolve(
+    [
+      http.get('http://localhost/api', () => {
+        // Intentionally do nothing to passthrough.
+      }),
+    ],
+    unhandledFrameCallback,
+    { quiet: true },
+  )
+
+  expect.soft(matches).toBeNull()
+  expect.soft(frame.passthrough).toHaveBeenCalledOnce()
+  expect.soft(frame.respondWith).not.toHaveBeenCalled()
+  expect.soft(frame.errorWith).not.toHaveBeenCalled()
+  expect.soft(unhandledFrameCallback).not.toHaveBeenCalled()
+  expect.soft(events).toEqual([
+    expect.objectContaining({
+      type: 'request:start',
+      requestId: frame.data.id,
+      request: frame.data.request,
+    }),
+    expect.objectContaining({
+      type: 'request:match',
+      requestId: frame.data.id,
+      request: frame.data.request,
+    }),
+    expect.objectContaining({
+      type: 'request:end',
+      requestId: frame.data.id,
+      request: frame.data.request,
+    }),
+  ])
+})
+
+it('resolves a bypassed request', async () => {
+  class HttpFrame extends HttpNetworkFrame {
+    respondWith = vi.fn()
+    passthrough = vi.fn()
+    errorWith = vi.fn()
+  }
+
+  const frame = new HttpFrame({
+    request: bypass(new Request('http://localhost/api')),
+  })
+  const { events } = spyOnNetworkFrame(frame)
+  const unhandledFrameCallback = vi.fn()
+
+  const matches = await frame.resolve(
+    [
+      http.get('http://localhost/api', () => {
+        return new Response(null, { status: 204 })
+      }),
+    ],
+    unhandledFrameCallback,
+    { quiet: true },
+  )
+
+  expect.soft(matches).toBeNull()
+  expect.soft(frame.passthrough).toHaveBeenCalledOnce()
+  expect.soft(frame.respondWith).not.toHaveBeenCalled()
+  expect.soft(frame.errorWith).not.toHaveBeenCalled()
+  expect.soft(unhandledFrameCallback).not.toHaveBeenCalled()
+  expect.soft(events).toEqual([
+    expect.objectContaining({
+      type: 'request:start',
+      requestId: frame.data.id,
+      request: frame.data.request,
+    }),
+    expect.objectContaining({
+      type: 'request:end',
+      requestId: frame.data.id,
+      request: frame.data.request,
+    }),
+  ])
+})
+
+it('errors the request on unhandled exception', async () => {
+  class HttpFrame extends HttpNetworkFrame {
+    respondWith = vi.fn()
+    passthrough = vi.fn()
+    errorWith = vi.fn()
+  }
+
+  const frame = new HttpFrame({
+    request: new Request('http://localhost/api'),
+  })
+  const { events } = spyOnNetworkFrame(frame)
+  const unhandledFrameCallback = vi.fn()
+
+  const exception = new Error('Unhandled exception')
+  const matches = await frame.resolve(
+    [
+      http.get('http://localhost/api', () => {
+        throw exception
+      }),
+    ],
+    unhandledFrameCallback,
+    { quiet: true },
+  )
+
+  expect.soft(matches).toBeNull()
+  expect.soft(frame.errorWith).toHaveBeenCalledExactlyOnceWith(exception)
+  expect.soft(frame.passthrough).not.toHaveBeenCalled()
+  expect.soft(frame.respondWith).not.toHaveBeenCalled()
+  expect.soft(unhandledFrameCallback).not.toHaveBeenCalled()
+  expect.soft(events).toEqual([
+    expect.objectContaining({
+      type: 'request:start',
+      requestId: frame.data.id,
+      request: frame.data.request,
+    }),
+    expect.objectContaining({
+      type: 'unhandledException',
+      error: exception,
+      requestId: frame.data.id,
+      request: frame.data.request,
+    }),
+  ])
+
+  expect.soft(console.error).toHaveBeenCalledTimes(2)
+  expect.soft(console.error).toHaveBeenNthCalledWith(1, exception)
+  expect
+    .soft(console.error)
+    .toHaveBeenNthCalledWith(
+      2,
+      '[MSW] Encountered an unhandled exception during the handler lookup for "GET http://localhost/api". Please see the original error above.',
+    )
+})
+
+it('does not print an unhandled exception if the "unhandledException" listener is present', async () => {
+  class HttpFrame extends HttpNetworkFrame {
+    respondWith = vi.fn()
+    passthrough = vi.fn()
+    errorWith = vi.fn()
+  }
+
+  const frame = new HttpFrame({
+    request: new Request('http://localhost/api'),
+  })
+  const { events } = spyOnNetworkFrame(frame)
+  const unhandledFrameCallback = vi.fn()
+
+  const unhandledExceptionListener = vi.fn()
+  frame.events.on('unhandledException', unhandledExceptionListener)
+
+  const exception = new Error('Unhandled exception')
+  const matches = await frame.resolve(
+    [
+      http.get('http://localhost/api', () => {
+        throw exception
+      }),
+    ],
+    unhandledFrameCallback,
+    { quiet: true },
+  )
+
+  expect.soft(matches).toBeNull()
+  expect.soft(frame.errorWith).toHaveBeenCalledExactlyOnceWith(exception)
+  expect.soft(frame.passthrough).not.toHaveBeenCalled()
+  expect.soft(frame.respondWith).not.toHaveBeenCalled()
+  expect.soft(unhandledFrameCallback).not.toHaveBeenCalled()
+  expect.soft(events).toEqual([
+    expect.objectContaining({
+      type: 'request:start',
+      requestId: frame.data.id,
+      request: frame.data.request,
+    }),
+    expect.objectContaining({
+      type: 'unhandledException',
+      error: exception,
+      requestId: frame.data.id,
+      request: frame.data.request,
+    }),
+  ])
+
+  expect.soft(console.error).not.toHaveBeenCalled()
+  expect.soft(unhandledExceptionListener).toHaveBeenCalledExactlyOnceWith(
+    expect.objectContaining({
+      error: exception,
+      requestId: frame.data.id,
+      request: frame.data.request,
+    }),
+  )
+})

package/src/core/experimental/frames/http-frame.ts

@@ -0,0 +1,271 @@
+import { TypedEvent } from 'rettime'
+import { until } from 'until-async'
+import { createRequestId } from '@mswjs/interceptors'
+import { NetworkFrame, NetworkFrameResolutionContext } from './network-frame'
+import { toPublicUrl } from '../../utils/request/toPublicUrl'
+import { executeHandlers } from '../../utils/executeHandlers'
+import { storeResponseCookies } from '../../utils/request/storeResponseCookies'
+import { isPassthroughResponse, shouldBypassRequest } from '../request-utils'
+import { devUtils } from '../../utils/internal/devUtils'
+import {
+  executeUnhandledFrameHandle,
+  type UnhandledFrameHandle,
+} from '../on-unhandled-frame'
+import { HandlersController, AnyHandler } from '../handlers-controller'
+import { type RequestHandler } from '../../handlers/RequestHandler'
+
+interface HttpNetworkFrameOptions {
+  id?: string
+  request: Request
+}
+
+export class RequestEvent<
+  DataType extends { requestId: string; request: Request } = {
+    requestId: string
+    request: Request
+  },
+  ReturnType = void,
+  EventType extends string = string,
+> extends TypedEvent<DataType, ReturnType, EventType> {
+  public readonly requestId: string
+  public readonly request: Request
+
+  constructor(type: EventType, data: DataType) {
+    super(...([type, {}] as any))
+    this.requestId = data.requestId
+    this.request = data.request
+  }
+}
+
+export class ResponseEvent<
+  DataType extends {
+    requestId: string
+    request: Request
+    response: Response
+  } = {
+    requestId: string
+    request: Request
+    response: Response
+  },
+  ReturnType = void,
+  EventType extends string = string,
+> extends TypedEvent<DataType, ReturnType, EventType> {
+  public readonly requestId: string
+  public readonly request: Request
+  public readonly response: Response
+
+  constructor(type: EventType, data: DataType) {
+    super(...([type, {}] as any))
+    this.requestId = data.requestId
+    this.request = data.request
+    this.response = data.response
+  }
+}
+
+export class UnhandledExceptionEvent<
+  DataType extends {
+    error: Error
+    requestId: string
+    request: Request
+  } = {
+    error: Error
+    requestId: string
+    request: Request
+  },
+  ReturnType = void,
+  EventType extends string = string,
+> extends TypedEvent<DataType, ReturnType, EventType> {
+  public readonly error: Error
+  public readonly requestId: string
+  public readonly request: Request
+
+  constructor(type: EventType, data: DataType) {
+    super(...([type, {}] as any))
+    this.error = data.error
+    this.requestId = data.requestId
+    this.request = data.request
+  }
+}
+
+export type HttpNetworkFrameEventMap = {
+  'request:start': RequestEvent
+  'request:match': RequestEvent
+  'request:unhandled': RequestEvent
+  'request:end': RequestEvent
+  'response:mocked': ResponseEvent
+  'response:bypass': ResponseEvent
+  unhandledException: UnhandledExceptionEvent
+}
+
+export abstract class HttpNetworkFrame extends NetworkFrame<
+  'http',
+  {
+    id: string
+    request: Request
+  },
+  HttpNetworkFrameEventMap
+> {
+  constructor(options: HttpNetworkFrameOptions) {
+    const id = options.id || createRequestId()
+    super('http', { id, request: options.request })
+  }
+
+  public getHandlers(controller: HandlersController): Array<AnyHandler> {
+    return controller.getHandlersByKind('request')
+  }
+
+  public abstract respondWith(response?: Response): void
+
+  public async getUnhandledMessage(): Promise<string> {
+    const { request } = this.data
+
+    const url = new URL(request.url)
+    const publicUrl = toPublicUrl(url) + url.search
+    const requestBody =
+      request.body == null ? null : await request.clone().text()
+
+    const details = `\n\n  \u2022 ${request.method} ${publicUrl}\n\n${requestBody ? `  \u2022 Request body: ${requestBody}\n\n` : ''}`
+    const message = `intercepted a request without a matching request handler:${details}If you still wish to intercept this unhandled request, please create a request handler for it.\nRead more: https://mswjs.io/docs/http/intercepting-requests`
+
+    return message
+  }
+
+  public async resolve(
+    handlers: Array<RequestHandler>,
+    onUnhandledFrame: UnhandledFrameHandle,
+    resolutionContext?: NetworkFrameResolutionContext,
+  ): Promise<boolean | null> {
+    const { id: requestId, request } = this.data
+    const requestCloneForLogs = resolutionContext?.quiet
+      ? null
+      : request.clone()
+
+    this.events.emit(new RequestEvent('request:start', { requestId, request }))
+
+    // Requests wrapped in explicit "bypass(request)".
+    if (shouldBypassRequest(request)) {
+      this.events.emit(new RequestEvent('request:end', { requestId, request }))
+      this.passthrough()
+      return null
+    }
+
+    const [lookupError, lookupResult] = await until(() => {
+      return executeHandlers({
+        requestId,
+        request,
+        handlers,
+        resolutionContext: {
+          baseUrl: resolutionContext?.baseUrl?.toString(),
+          quiet: resolutionContext?.quiet,
+        },
+      })
+    })
+
+    if (lookupError != null) {
+      if (
+        !this.events.emit(
+          new UnhandledExceptionEvent('unhandledException', {
+            error: lookupError,
+            requestId,
+            request,
+          }),
+        )
+      ) {
+        // Surface the error to the developer since they haven't handled it.
+        console.error(lookupError)
+        devUtils.error(
+          'Encountered an unhandled exception during the handler lookup for "%s %s". Please see the original error above.',
+          request.method,
+          request.url,
+        )
+      }
+
+      this.errorWith(lookupError)
+      return null
+    }
+
+    // No matching handlers.
+    if (lookupResult == null) {
+      this.events.emit(
+        new RequestEvent('request:unhandled', {
+          requestId,
+          request,
+        }),
+      )
+
+      /**
+       * @note The unhandled frame handle must be executed during the request resolution
+       * since it can influence it (e.g. error the request if the "error" startegy was used).
+       */
+      await executeUnhandledFrameHandle(this, onUnhandledFrame).then(
+        () => this.passthrough(),
+        (error) => this.errorWith(error),
+      )
+
+      this.events.emit(
+        new RequestEvent('request:end', {
+          requestId,
+          request,
+        }),
+      )
+
+      return false
+    }
+
+    const { response, handler, parsedResult } = lookupResult
+
+    this.events.emit(
+      new RequestEvent('request:match', {
+        requestId,
+        request,
+      }),
+    )
+
+    // Handlers that returned no mocked response.
+    if (response == null) {
+      this.events.emit(
+        new RequestEvent('request:end', {
+          requestId,
+          request,
+        }),
+      )
+
+      this.passthrough()
+      return null
+    }
+
+    // Handlers that returned explicit `passthrough()`.
+    if (isPassthroughResponse(response)) {
+      this.events.emit(
+        new RequestEvent('request:end', {
+          requestId,
+          request,
+        }),
+      )
+
+      this.passthrough()
+      return null
+    }
+
+    await storeResponseCookies(request, response)
+
+    this.respondWith(response.clone())
+
+    this.events.emit(
+      new RequestEvent('request:end', {
+        requestId,
+        request,
+      }),
+    )
+
+    if (!resolutionContext?.quiet) {
+      handler.log({
+        request: requestCloneForLogs!,
+        response,
+        parsedResult,
+      })
+    }
+
+    return true
+  }
+}

package/src/core/experimental/frames/network-frame.ts

@@ -0,0 +1,64 @@
+import { Emitter, type DefaultEventMap } from 'rettime'
+import type { AnyHandler, HandlersController } from '../handlers-controller'
+import type { UnhandledFrameHandle } from '../on-unhandled-frame'
+
+export type AnyNetworkFrame = NetworkFrame<string, unknown, any>
+
+export type ExtractFrameEvents<Frame> =
+  Frame extends NetworkFrame<any, any, infer Events> ? Events : never
+
+export interface NetworkFrameResolutionContext {
+  baseUrl?: string | URL
+  quiet?: boolean
+}
+
+/**
+ * The base for the network frames. Extend this abstract class
+ * to implement custom network frames.
+ */
+export abstract class NetworkFrame<
+  Protocol extends string,
+  Data,
+  Events extends DefaultEventMap,
+> {
+  public events: Emitter<Events>
+
+  constructor(
+    public readonly protocol: Protocol,
+    public readonly data: Data,
+  ) {
+    this.events = new Emitter()
+  }
+
+  public abstract getHandlers(controller: HandlersController): Array<AnyHandler>
+
+  /**
+   * Resolve the current frame against the given list of handlers.
+   * Optionally, use a custom resolution context to control behaviors
+   * like `baseUrl`.
+   *
+   * Returns `true` if the frame was handled, `false` if it wasn't, and `null`
+   * if its handling was skipped (e.g. the frame was bypassed).
+   */
+  public abstract resolve(
+    handlers: Array<AnyHandler>,
+    onUnhandledFrame: UnhandledFrameHandle,
+    resolutionContext?: NetworkFrameResolutionContext,
+  ): Promise<boolean | null>
+
+  /**
+   * Perform this network frame as-is.
+   */
+  public abstract passthrough(): void
+
+  /**
+   * Error the underling network frame.
+   * @param reason The reason for the error.
+   */
+  public abstract errorWith(reason?: unknown): void
+
+  /**
+   * Get a message to be used when this frame is unhandled.
+   */
+  public abstract getUnhandledMessage(): Promise<string>
+}