msw 2.0.12 → 2.0.13

package/src/browser/setupWorker/start/utils/getWorkerByRegistration.ts

@@ -0,0 +1,25 @@
+import { FindWorker } from '../../glossary'
+
+/**
+ * Attempts to resolve a Service Worker instance from a given registration,
+ * regardless of its state (active, installing, waiting).
+ */
+export function getWorkerByRegistration(
+  registration: ServiceWorkerRegistration,
+  absoluteWorkerUrl: string,
+  findWorker: FindWorker,
+): ServiceWorker | null {
+  const allStates = [
+    registration.active,
+    registration.installing,
+    registration.waiting,
+  ]
+  const relevantStates = allStates.filter((state): state is ServiceWorker => {
+    return state != null
+  })
+  const worker = relevantStates.find((worker) => {
+    return findWorker(worker.scriptURL, absoluteWorkerUrl)
+  })
+
+  return worker || null
+}

package/src/browser/setupWorker/start/utils/getWorkerInstance.ts

@@ -0,0 +1,94 @@
+import { until } from '@open-draft/until'
+import { devUtils } from '~/core/utils/internal/devUtils'
+import { getAbsoluteWorkerUrl } from '../../../utils/getAbsoluteWorkerUrl'
+import { getWorkerByRegistration } from './getWorkerByRegistration'
+import { ServiceWorkerInstanceTuple, FindWorker } from '../../glossary'
+
+/**
+ * Returns an active Service Worker instance.
+ * When not found, registers a new Service Worker.
+ */
+export const getWorkerInstance = async (
+  url: string,
+  options: RegistrationOptions = {},
+  findWorker: FindWorker,
+): Promise<ServiceWorkerInstanceTuple> => {
+  // Resolve the absolute Service Worker URL.
+  const absoluteWorkerUrl = getAbsoluteWorkerUrl(url)
+
+  const mockRegistrations = await navigator.serviceWorker
+    .getRegistrations()
+    .then((registrations) =>
+      registrations.filter((registration) =>
+        getWorkerByRegistration(registration, absoluteWorkerUrl, findWorker),
+      ),
+    )
+  if (!navigator.serviceWorker.controller && mockRegistrations.length > 0) {
+    // Reload the page when it has associated workers, but no active controller.
+    // The absence of a controller can mean either:
+    // - page has no Service Worker associated with it
+    // - page has been hard-reloaded and its workers won't be used until the next reload.
+    // Since we've checked that there are registrations associated with this page,
+    // at this point we are sure it's hard reload that falls into this clause.
+    location.reload()
+  }
+
+  const [existingRegistration] = mockRegistrations
+
+  if (existingRegistration) {
+    // When the Service Worker is registered, update it and return the reference.
+    return existingRegistration.update().then(() => {
+      return [
+        getWorkerByRegistration(
+          existingRegistration,
+          absoluteWorkerUrl,
+          findWorker,
+        ),
+        existingRegistration,
+      ]
+    })
+  }
+
+  // When the Service Worker wasn't found, register it anew and return the reference.
+  const registrationResult = await until<Error, ServiceWorkerInstanceTuple>(
+    async () => {
+      const registration = await navigator.serviceWorker.register(url, options)
+      return [
+        // Compare existing worker registration by its worker URL,
+        // to prevent irrelevant workers to resolve here (such as Codesandbox worker).
+        getWorkerByRegistration(registration, absoluteWorkerUrl, findWorker),
+        registration,
+      ]
+    },
+  )
+
+  // Handle Service Worker registration errors.
+  if (registrationResult.error) {
+    const isWorkerMissing = registrationResult.error.message.includes('(404)')
+
+    // Produce a custom error message when given a non-existing Service Worker url.
+    // Suggest developers to check their setup.
+    if (isWorkerMissing) {
+      const scopeUrl = new URL(options?.scope || '/', location.href)
+
+      throw new Error(
+        devUtils.formatMessage(`\
+Failed to register a Service Worker for scope ('${scopeUrl.href}') with script ('${absoluteWorkerUrl}'): Service Worker script does not exist at the given path.
+
+Did you forget to run "npx msw init <PUBLIC_DIR>"?
+
+Learn more about creating the Service Worker script: https://mswjs.io/docs/cli/init`),
+      )
+    }
+
+    // Fallback error message for any other registration errors.
+    throw new Error(
+      devUtils.formatMessage(
+        'Failed to register the Service Worker:\n\n%s',
+        registrationResult.error.message,
+      ),
+    )
+  }
+
+  return registrationResult.data
+}

package/src/browser/setupWorker/start/utils/prepareStartHandler.test.ts

@@ -0,0 +1,59 @@
+import { SetupWorkerInternalContext, StartOptions } from '../../glossary'
+import {
+  DEFAULT_START_OPTIONS,
+  resolveStartOptions,
+  prepareStartHandler,
+} from './prepareStartHandler'
+
+describe('resolveStartOptions', () => {
+  test('returns default options given no custom start options', () => {
+    expect(resolveStartOptions()).toEqual(DEFAULT_START_OPTIONS)
+    expect(resolveStartOptions(undefined)).toEqual(DEFAULT_START_OPTIONS)
+    expect(resolveStartOptions({})).toEqual(DEFAULT_START_OPTIONS)
+  })
+
+  test('deeply merges the default and custom start options', () => {
+    expect(
+      resolveStartOptions({
+        quiet: true,
+        serviceWorker: {
+          url: './custom.js',
+        },
+      }),
+    ).toEqual({
+      ...DEFAULT_START_OPTIONS,
+      quiet: true,
+      serviceWorker: {
+        url: './custom.js',
+        options: null,
+      },
+    })
+  })
+})
+
+describe('prepareStartHandler', () => {
+  test('exposes resolved start options to the generated star handler', () => {
+    const createStartHandler = vi.fn()
+    const context: SetupWorkerInternalContext = {} as any
+    const startHandler = prepareStartHandler(createStartHandler, context)
+    expect(startHandler).toBeInstanceOf(Function)
+
+    const initialOptions: StartOptions = {
+      quiet: true,
+      serviceWorker: {
+        url: './custom.js',
+      },
+    }
+    const resolvedOptions = resolveStartOptions(initialOptions)
+    startHandler(initialOptions)
+
+    // Calls the handler creator with both resolved and initial options.
+    expect(createStartHandler).toHaveBeenCalledWith(
+      resolvedOptions,
+      initialOptions,
+    )
+
+    // Sets the resolved options on the internal context.
+    expect(context).toHaveProperty('startOptions', resolvedOptions)
+  })
+})

package/src/browser/setupWorker/start/utils/prepareStartHandler.ts

@@ -0,0 +1,44 @@
+import { RequiredDeep } from '~/core/typeUtils'
+import { mergeRight } from '~/core/utils/internal/mergeRight'
+import {
+  SetupWorker,
+  SetupWorkerInternalContext,
+  StartHandler,
+  StartOptions,
+} from '../../glossary'
+
+export const DEFAULT_START_OPTIONS: RequiredDeep<StartOptions> = {
+  serviceWorker: {
+    url: '/mockServiceWorker.js',
+    options: null as any,
+  },
+  quiet: false,
+  waitUntilReady: true,
+  onUnhandledRequest: 'warn',
+  findWorker(scriptURL, mockServiceWorkerUrl) {
+    return scriptURL === mockServiceWorkerUrl
+  },
+}
+
+/**
+ * Returns resolved worker start options, merging the default options
+ * with the given custom options.
+ */
+export function resolveStartOptions(
+  initialOptions?: StartOptions,
+): RequiredDeep<StartOptions> {
+  return mergeRight(
+    DEFAULT_START_OPTIONS,
+    initialOptions || {},
+  ) as RequiredDeep<StartOptions>
+}
+
+export function prepareStartHandler(
+  handler: StartHandler,
+  context: SetupWorkerInternalContext,
+): SetupWorker['start'] {
+  return (initialOptions) => {
+    context.startOptions = resolveStartOptions(initialOptions)
+    return handler(context.startOptions, initialOptions || {})
+  }
+}

package/src/browser/setupWorker/start/utils/printStartMessage.test.ts

@@ -0,0 +1,84 @@
+import { printStartMessage } from './printStartMessage'
+
+beforeEach(() => {
+  vi.spyOn(console, 'groupCollapsed').mockImplementation(() => void 0)
+  vi.spyOn(console, 'log').mockImplementation(() => void 0)
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+test('prints out a default start message into console', () => {
+  printStartMessage({
+    workerScope: 'http://localhost:3000/',
+    workerUrl: 'http://localhost:3000/worker.js',
+  })
+
+  expect(console.groupCollapsed).toHaveBeenCalledWith(
+    '%c[MSW] Mocking enabled.',
+    expect.anything(),
+  )
+
+  // Includes a link to the documentation.
+  expect(console.log).toHaveBeenCalledWith(
+    '%cDocumentation: %chttps://mswjs.io/docs',
+    expect.anything(),
+    expect.anything(),
+  )
+
+  // Includes a link to the GitHub issues page.
+  expect(console.log).toHaveBeenCalledWith(
+    'Found an issue? https://github.com/mswjs/msw/issues',
+  )
+
+  // Includes service worker scope.
+  expect(console.log).toHaveBeenCalledWith(
+    'Worker scope:',
+    'http://localhost:3000/',
+  )
+
+  // Includes service worker script location.
+  expect(console.log).toHaveBeenCalledWith(
+    'Worker script URL:',
+    'http://localhost:3000/worker.js',
+  )
+})
+
+test('supports printing a custom start message', () => {
+  printStartMessage({ message: 'Custom start message' })
+
+  expect(console.groupCollapsed).toHaveBeenCalledWith(
+    '%c[MSW] Custom start message',
+    expect.anything(),
+  )
+})
+
+test('does not print any messages when log level is quiet', () => {
+  printStartMessage({ quiet: true })
+
+  expect(console.groupCollapsed).not.toHaveBeenCalled()
+  expect(console.log).not.toHaveBeenCalled()
+})
+
+test('prints a worker scope in the start message', () => {
+  printStartMessage({
+    workerScope: 'http://localhost:3000/user',
+  })
+
+  expect(console.log).toHaveBeenCalledWith(
+    'Worker scope:',
+    'http://localhost:3000/user',
+  )
+})
+
+test('prints a worker script url in the start message', () => {
+  printStartMessage({
+    workerUrl: 'http://localhost:3000/mockServiceWorker.js',
+  })
+
+  expect(console.log).toHaveBeenCalledWith(
+    'Worker script URL:',
+    'http://localhost:3000/mockServiceWorker.js',
+  )
+})

package/src/browser/setupWorker/start/utils/printStartMessage.ts

@@ -0,0 +1,40 @@
+import { devUtils } from '~/core/utils/internal/devUtils'
+
+export interface PrintStartMessageArgs {
+  quiet?: boolean
+  message?: string
+  workerUrl?: string
+  workerScope?: string
+}
+
+/**
+ * Prints a worker activation message in the browser's console.
+ */
+export function printStartMessage(args: PrintStartMessageArgs = {}) {
+  if (args.quiet) {
+    return
+  }
+
+  const message = args.message || 'Mocking enabled.'
+
+  console.groupCollapsed(
+    `%c${devUtils.formatMessage(message)}`,
+    'color:orangered;font-weight:bold;',
+  )
+  console.log(
+    '%cDocumentation: %chttps://mswjs.io/docs',
+    'font-weight:bold',
+    'font-weight:normal',
+  )
+  console.log('Found an issue? https://github.com/mswjs/msw/issues')
+
+  if (args.workerUrl) {
+    console.log('Worker script URL:', args.workerUrl)
+  }
+
+  if (args.workerScope) {
+    console.log('Worker scope:', args.workerScope)
+  }
+
+  console.groupEnd()
+}

package/src/browser/setupWorker/start/utils/validateWorkerScope.ts

@@ -0,0 +1,18 @@
+import { devUtils } from '~/core/utils/internal/devUtils'
+import { StartOptions } from '../../glossary'
+
+export function validateWorkerScope(
+  registration: ServiceWorkerRegistration,
+  options?: StartOptions,
+): void {
+  if (!options?.quiet && !location.href.startsWith(registration.scope)) {
+    devUtils.warn(
+      `\
+Cannot intercept requests on this page because it's outside of the worker's scope ("${registration.scope}"). If you wish to mock API requests on this page, you must resolve this scope issue.
+
+- (Recommended) Register the worker at the root level ("/") of your application.
+- Set the "Service-Worker-Allowed" response header to allow out-of-scope workers.\
+`,
+    )
+  }
+}

package/src/browser/setupWorker/stop/createFallbackStop.ts

@@ -0,0 +1,11 @@
+import { SetupWorkerInternalContext, StopHandler } from '../glossary'
+import { printStopMessage } from './utils/printStopMessage'
+
+export function createFallbackStop(
+  context: SetupWorkerInternalContext,
+): StopHandler {
+  return function stop() {
+    context.fallbackInterceptor?.dispose()
+    printStopMessage({ quiet: context.startOptions?.quiet })
+  }
+}

package/src/browser/setupWorker/stop/createStop.ts

@@ -0,0 +1,29 @@
+import { devUtils } from '~/core/utils/internal/devUtils'
+import { SetupWorkerInternalContext, StopHandler } from '../glossary'
+import { printStopMessage } from './utils/printStopMessage'
+
+export const createStop = (
+  context: SetupWorkerInternalContext,
+): StopHandler => {
+  return function stop() {
+    // Warn developers calling "worker.stop()" more times than necessary.
+    // This likely indicates a mistake in their code.
+    if (!context.isMockingEnabled) {
+      devUtils.warn(
+        'Found a redundant "worker.stop()" call. Note that stopping the worker while mocking already stopped has no effect. Consider removing this "worker.stop()" call.',
+      )
+      return
+    }
+
+    /**
+     * Signal the Service Worker to disable mocking for this client.
+     * Use this an an explicit way to stop the mocking, while preserving
+     * the worker-client relation. Does not affect the worker's lifecycle.
+     */
+    context.workerChannel.send('MOCK_DEACTIVATE')
+    context.isMockingEnabled = false
+    window.clearInterval(context.keepAliveInterval)
+
+    printStopMessage({ quiet: context.startOptions?.quiet })
+  }
+}

package/src/browser/setupWorker/stop/utils/printStopMessage.test.ts

@@ -0,0 +1,26 @@
+import { printStopMessage } from './printStopMessage'
+
+beforeAll(() => {
+  vi.spyOn(global.console, 'log').mockImplementation(() => void 0)
+})
+
+afterEach(() => {
+  vi.resetAllMocks()
+})
+
+afterAll(() => {
+  vi.restoreAllMocks()
+})
+
+test('prints a stop message to the console', () => {
+  printStopMessage()
+  expect(console.log).toHaveBeenCalledWith(
+    '%c[MSW] Mocking disabled.',
+    'color:orangered;font-weight:bold;',
+  )
+})
+
+test('does not print any message when log level is quiet', () => {
+  printStopMessage({ quiet: true })
+  expect(console.log).not.toHaveBeenCalled()
+})

package/src/browser/setupWorker/stop/utils/printStopMessage.ts

@@ -0,0 +1,12 @@
+import { devUtils } from '~/core/utils/internal/devUtils'
+
+export function printStopMessage(args: { quiet?: boolean } = {}): void {
+  if (args.quiet) {
+    return
+  }
+
+  console.log(
+    `%c${devUtils.formatMessage('Mocking disabled.')}`,
+    'color:orangered;font-weight:bold;',
+  )
+}

package/src/browser/tsconfig.browser.build.json

@@ -0,0 +1,6 @@
+{
+  "extends": "./tsconfig.browser.json",
+  "compilerOptions": {
+    "composite": false
+  }
+}

package/src/browser/tsconfig.browser.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../tsconfig.src.json",
+  "compilerOptions": {
+    // Expose browser-specific libraries only for the
+    // source code under the "src/browser" directory.
+    "lib": ["DOM", "WebWorker"]
+  },
+  "include": ["../../global.d.ts", "./global.browser.d.ts", "./**/*.ts"]
+}

package/src/browser/utils/deferNetworkRequestsUntil.test.ts

@@ -0,0 +1,48 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { deferNetworkRequestsUntil } from './deferNetworkRequestsUntil'
+
+beforeAll(() => {
+  // Stubs native `fetch` function to remove any external
+  // asynchronicity from this test suite.
+  window.fetch = vi.fn().mockImplementation(() => {
+    return Promise.resolve({
+      json: () => ({
+        response: 'body',
+      }),
+    })
+  })
+})
+
+afterAll(() => {
+  vi.restoreAllMocks()
+})
+
+test('defers any requests that happen while a given promise is pending', async () => {
+  const events: string[] = []
+
+  // Emulate a Service Worker registration Promise.
+  const workerPromise = new Promise<null>((resolve) => {
+    setTimeout(resolve, 1000)
+  })
+
+  workerPromise.then(() => {
+    events.push('promise resolved')
+  })
+
+  // Calling this functions intercepts all requests that happen while
+  // the given promise is pending, and defers their execution
+  // until the promise is resolved.
+  deferNetworkRequestsUntil(workerPromise)
+
+  // Perform a request.
+  const requestPromise = fetch('/user').then(() => {
+    events.push('response received')
+  })
+
+  await Promise.all([workerPromise, requestPromise])
+
+  // Assert the order of resolved events.
+  expect(events).toEqual(['promise resolved', 'response received'])
+})

package/src/browser/utils/deferNetworkRequestsUntil.ts

@@ -0,0 +1,29 @@
+import { until } from '@open-draft/until'
+
+/**
+ * Intercepts and defers any requests on the page
+ * until the Service Worker instance is ready.
+ * Must only be used in a browser.
+ */
+export function deferNetworkRequestsUntil(predicatePromise: Promise<any>) {
+  // Defer any `XMLHttpRequest` requests until the Service Worker is ready.
+  const originalXhrSend = window.XMLHttpRequest.prototype.send
+  window.XMLHttpRequest.prototype.send = function (
+    ...args: Parameters<XMLHttpRequest['send']>
+  ) {
+    // Keep this function synchronous to comply with `XMLHttpRequest.prototype.send`,
+    // because that method is always synchronous.
+    until(() => predicatePromise).then(() => {
+      window.XMLHttpRequest.prototype.send = originalXhrSend
+      this.send(...args)
+    })
+  }
+
+  // Defer any `fetch` requests until the Service Worker is ready.
+  const originalFetch = window.fetch
+  window.fetch = async (...args) => {
+    await until(() => predicatePromise)
+    window.fetch = originalFetch
+    return window.fetch(...args)
+  }
+}

package/src/browser/utils/getAbsoluteWorkerUrl.test.ts

@@ -0,0 +1,31 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { getAbsoluteWorkerUrl } from './getAbsoluteWorkerUrl'
+
+const rawLocation = window.location
+
+afterAll(() => {
+  Object.defineProperty(window, 'location', {
+    value: rawLocation,
+  })
+})
+
+it('returns absolute worker url relatively to the root', () => {
+  expect(getAbsoluteWorkerUrl('./worker.js')).toBe('http://localhost/worker.js')
+})
+
+it('returns an absolute worker url relatively to the current path', () => {
+  Object.defineProperty(window, 'location', {
+    value: {
+      href: 'http://localhost/path/to/page',
+    },
+  })
+
+  expect(getAbsoluteWorkerUrl('./worker.js')).toBe(
+    'http://localhost/path/to/worker.js',
+  )
+
+  // Leading slash must still resolve to the root.
+  expect(getAbsoluteWorkerUrl('/worker.js')).toBe('http://localhost/worker.js')
+})

package/src/browser/utils/getAbsoluteWorkerUrl.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns an absolute Service Worker URL based on the given
+ * relative URL (known during the registration).
+ */
+export function getAbsoluteWorkerUrl(workerUrl: string): string {
+  return new URL(workerUrl, location.href).href
+}

package/src/browser/utils/parseWorkerRequest.ts

@@ -0,0 +1,15 @@
+import { pruneGetRequestBody } from './pruneGetRequestBody'
+import type { ServiceWorkerIncomingRequest } from '../setupWorker/glossary'
+
+/**
+ * Converts a given request received from the Service Worker
+ * into a Fetch `Request` instance.
+ */
+export function parseWorkerRequest(
+  incomingRequest: ServiceWorkerIncomingRequest,
+): Request {
+  return new Request(incomingRequest.url, {
+    ...incomingRequest,
+    body: pruneGetRequestBody(incomingRequest),
+  })
+}

package/src/browser/utils/pruneGetRequestBody.test.ts

@@ -0,0 +1,53 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { TextEncoder } from 'util'
+import { pruneGetRequestBody } from './pruneGetRequestBody'
+
+test('sets empty GET request body to undefined', () => {
+  expect(
+    pruneGetRequestBody({
+      method: 'GET',
+    }),
+  ).toBeUndefined()
+
+  expect(
+    pruneGetRequestBody({
+      method: 'GET',
+      // There's no such thing as a GET request with a body.
+      body: new ArrayBuffer(5),
+    }),
+  ).toBeUndefined()
+})
+
+test('sets HEAD request body to undefined', () => {
+  expect(
+    pruneGetRequestBody({
+      method: 'HEAD',
+    }),
+  ).toBeUndefined()
+
+  expect(
+    pruneGetRequestBody({
+      method: 'HEAD',
+      body: new ArrayBuffer(5),
+    }),
+  ).toBeUndefined()
+})
+
+test('ignores requests of the other methods than GET', () => {
+  const body = new TextEncoder().encode('hello world')
+  expect(
+    pruneGetRequestBody({
+      method: 'POST',
+      body,
+    }),
+  ).toEqual(body)
+
+  expect(
+    pruneGetRequestBody({
+      method: 'PUT',
+      body,
+    }),
+  ).toEqual(body)
+})

package/src/browser/utils/pruneGetRequestBody.ts

@@ -0,0 +1,21 @@
+import type { ServiceWorkerIncomingRequest } from '../setupWorker/glossary'
+
+type Input = Pick<ServiceWorkerIncomingRequest, 'method' | 'body'>
+
+/**
+ * Ensures that an empty GET request body is always represented as `undefined`.
+ */
+export function pruneGetRequestBody(
+  request: Input,
+): ServiceWorkerIncomingRequest['body'] {
+  // Force HEAD/GET request body to always be empty.
+  // The worker reads any request's body as ArrayBuffer,
+  // and you cannot re-construct a GET/HEAD Request
+  // with an ArrayBuffer, even if empty. Also note that
+  // "request.body" is always undefined in the worker.
+  if (['HEAD', 'GET'].includes(request.method)) {
+    return undefined
+  }
+
+  return request.body
+}