setupWorker: Adds errors when failed to find a registration

src/setupWorker/start/createStart.ts

@@ -65,9 +65,19 @@ export const createStart = (context: SetupWorkerInternalContext) => {
 
       if (!worker) {
         if (options?.findWorker) {
-          console.warn(
-            `[MSW] worker.start() registered the service worker, but was provided a findWorker predicate that failed to find a worker instance. Please verify your configuration.`,
-          )
+          console.error(`\
+[MSW] Failed to locate the Service Worker registration using a custom "findWorker" predicate.
+
+Please ensure that the custom predicate properly locates the Service Worker registration at "${resolvedOptions.serviceWorker.url}".
+More details: https://mswjs.io/docs/api/setup-worker/start#findworker
+`)
+        } else {
+          console.error(`\
+[MSW] Failed to locate the Service Worker registration.
+
+This most likely means that the worker script URL "${resolvedOptions.serviceWorker.url}" cannot resolve against the actual public hostname (${location.host}). This may happen if your application runs behind a proxy, or has a dynamic hostname.
+
+Please consider using a custom "serviceWorker.url" option to point to the actual worker script location, or a custom "findWorker" option to resolve the Service Worker registration manually. More details: https://mswjs.io/docs/api/setup-worker/start`)
         }
 
         return null

src/setupWorker/start/utils/getWorkerInstance.ts

@@ -12,7 +12,7 @@ export const getWorkerInstance = async (
   options: RegistrationOptions = {},
   findWorker: FindWorker,
 ): Promise<ServiceWorkerInstanceTuple | null> => {
-  // Resolve the absolute Service Worker URL
+  // Resolve the absolute Service Worker URL.
   const absoluteWorkerUrl = getAbsoluteWorkerUrl(url)
 
   const [, mockRegistrations] = await until(async () => {
@@ -39,7 +39,7 @@ export const getWorkerInstance = async (
   const [existingRegistration] = mockRegistrations
 
   if (existingRegistration) {
-    // Update existing service worker to ensure it's up-to-date
+    // When the Service Worker is registered, update it and return the reference.
     return existingRegistration.update().then(() => {
       return [
         getWorkerByRegistration(
@@ -52,6 +52,7 @@ export const getWorkerInstance = async (
     })
   }
 
+  // When the Service Worker wasn't found, register it anew and return the reference.
   const [error, instance] = await until<ServiceWorkerInstanceTuple>(
     async () => {
       const registration = await navigator.serviceWorker.register(url, options)
@@ -64,6 +65,7 @@ export const getWorkerInstance = async (
     },
   )
 
+  // Handle Service Worker registration errors.
   if (error) {
     const isWorkerMissing = error.message.includes('(404)')
 

test/msw-api/setup-worker/start/find-worker.test.ts

@@ -1,6 +1,9 @@
 import * as path from 'path'
 import { runBrowserWith } from '../../../support/runBrowserWith'
-import { captureConsole } from '../../../support/captureConsole'
+import {
+  captureConsole,
+  filterLibraryLogs,
+} from '../../../support/captureConsole'
 
 test('resolves the "start" Promise and returns a ServiceWorkerRegistration when using a findWorker that returns true', async () => {
   const runtime = await runBrowserWith(
@@ -61,14 +64,16 @@ test('fails to return a ServiceWorkerRegistration when using a findWorker that r
     return text.includes('Error - no worker instance after starting')
   })
 
-  const mswDeveloperWarningMessageIndex = messages.warning.findIndex((text) => {
-    return text.includes(
-      '[MSW] worker.start() registered the service worker, but was provided a findWorker predicate that failed to find a worker instance. Please verify your configuration.',
-    )
-  })
+  const libraryErrors = messages.error.filter(filterLibraryLogs)
+
+  expect(libraryErrors).toContain(`\
+[MSW] Failed to locate the Service Worker registration using a custom "findWorker" predicate.
+
+Please ensure that the custom predicate properly locates the Service Worker registration at "/mockServiceWorker.js".
+More details: https://mswjs.io/docs/api/setup-worker/start#findworker\
+`)
 
   expect(activationMessageIndex).toEqual(-1)
-  expect(mswDeveloperWarningMessageIndex).toBeGreaterThan(-1)
   expect(errorMessageIndex).toBeGreaterThan(-1)
   expect(errorMessageIndex).toBeGreaterThan(activationMessageIndex)