fix: improve error message on registration failed

src/setupWorker/start/utils/activateMocking.ts

@@ -18,7 +18,7 @@ export const activateMocking = (
             'color:orangered;font-weight:bold;',
           )
           console.log(
-            '%cDocumentation: %chttps://redd.gitbook.io/msw',
+            '%cDocumentation: %chttps://mswjs.io/docs',
             'font-weight:bold',
             'font-weight:normal',
           )

src/setupWorker/start/utils/getWorkerInstance.ts

@@ -46,7 +46,6 @@ export const getWorkerInstance = async (
       ]
     })
   }
-
   const [error, instance] = await until<ServiceWorkerInstanceTuple>(
     async () => {
       const registration = await navigator.serviceWorker.register(url, options)
@@ -55,10 +54,26 @@ export const getWorkerInstance = async (
   )
 
   if (error) {
+    const isWorkerMissing = 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)
+
+      console.error(`\
+[MSW] 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`)
+
+      return null
+    }
+
+    // Fallback error message for any other registration errors.
     console.error(
-      '[MSW] Failed to register Service Worker (%s). %o',
-      url,
-      error,
+      `[MSW] Failed to register a Service Worker:\n\m${error.message}`,
     )
     return null
   }

test/msw-api/setup-worker/start/error.mocks.ts

@@ -0,0 +1,10 @@
+import { setupWorker, rest } from 'msw'
+
+const worker = setupWorker(
+  rest.get('/user', (req, res, ctx) => {
+    return res(ctx.status(200))
+  }),
+)
+
+// @ts-ignore
+window.__MSW_START__ = worker.start

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

@@ -0,0 +1,38 @@
+import * as path from 'path'
+import { TestAPI, runBrowserWith } from '../../../support/runBrowserWith'
+import { captureConsole } from '../../../support/captureConsole'
+
+let runtime: TestAPI
+
+beforeAll(async () => {
+  runtime = await runBrowserWith(path.resolve(__dirname, 'error.mocks.ts'))
+})
+
+afterAll(() => runtime.cleanup())
+
+test('prints a custom error message when given a non-existing worker script', async () => {
+  const errors: string[] = []
+  captureConsole(runtime.page, errors, (message) => {
+    return message.type() === 'error'
+  })
+
+  await runtime.page.evaluate(() => {
+    // @ts-ignore
+    return window.window.__MSW_START__({
+      serviceWorker: {
+        url: 'invalidServiceWorker',
+      },
+    })
+  })
+
+  const workerNotFoundMessage = errors.find((message) => {
+    return (
+      message.startsWith(
+        `[MSW] Failed to register a Service Worker for scope ('${runtime.page.url()}')`,
+      ) &&
+      message.includes('Did you forget to run "npx msw init <PUBLIC_DIR>"?')
+    )
+  })
+
+  expect(workerNotFoundMessage).toBeTruthy()
+})