feat(runtime-utils): allow modifying + removing endpoints

resolves #551

Author: danielroe

examples/app-vitest-full/tests/nuxt/server.spec.ts

@@ -21,7 +21,7 @@ describe('server mocks and data fetching', () => {
     await server.close()
   })
 
-  it('can mock fetch requests', async () => {
+  it('can mock fetch requests within components', async () => {
     registerEndpoint('https://jsonplaceholder.typicode.com/todos/1', () => ({
       title: 'title from mocked api',
     }))
@@ -31,7 +31,7 @@ describe('server mocks and data fetching', () => {
     )
   })
 
-  it('can mock fetch requests', async () => {
+  it('can mock fetch requests made directly', async () => {
     registerEndpoint('/with-query', () => ({
       title: 'mocked',
     }))
@@ -42,6 +42,20 @@ describe('server mocks and data fetching', () => {
     })
   })
 
+  it('can override and remove request mocks', async () => {
+    const unsubFirst = registerEndpoint('/overrides', () => ({ title: 'first' }))
+    expect(await $fetch<unknown>('/overrides')).toStrictEqual({ title: 'first' })
+
+    const unsubSecond = registerEndpoint('/overrides', () => ({ title: 'second' }))
+    expect(await $fetch<unknown>('/overrides')).toStrictEqual({ title: 'second' })
+
+    unsubSecond()
+    expect(await $fetch<unknown>('/overrides')).toStrictEqual({ title: 'first' })
+
+    unsubFirst()
+    expect($fetch<unknown>('/overrides')).rejects.toMatchInlineSnapshot(`[FetchError: [GET] "/overrides": 404 Cannot find any path matching /_/overrides.]`)
+  })
+
   it('can mock fetch requests with explicit methods', async () => {
     registerEndpoint('/method', {
       method: 'POST',

src/runtime-utils/mock.ts

@@ -32,36 +32,45 @@ type OptionalFunction<T> = T | (() => Awaitable<T>)
  * ```
  * @see https://nuxt.com/docs/getting-started/testing#registerendpoint
  */
-export function registerEndpoint(
-  url: string,
-  options:
-    | EventHandler
-    | {
-      handler: EventHandler
-      method: HTTPMethod
-    },
-) {
+const endpointRegistry: Record<string, Array<{ handler: EventHandler, method?: HTTPMethod }>> = {}
+export function registerEndpoint(url: string, options: EventHandler | { handler: EventHandler, method: HTTPMethod }) {
   // @ts-expect-error private property
   const app: App = window.__app
 
-  if (!app) return
+  if (!app) {
+    throw new Error('registerEndpoint() can only be used in a `@nuxt/test-utils` runtime environment')
+  }
 
-  const config
-    = typeof options === 'function'
-      ? {
-          handler: options,
-          method: undefined,
-        }
-      : options
-
-  app.use('/_' + url, defineEventHandler(config.handler), {
-    match(_, event) {
-      return config.method ? event?.method === config.method : true
-    },
-  })
+  const config = typeof options === 'function' ? { handler: options, method: undefined } : options
+  config.handler = defineEventHandler(config.handler)
 
   // @ts-expect-error private property
-  window.__registry.add(url)
+  const hasBeenRegistered: boolean = window.__registry.has(url)
+
+  endpointRegistry[url] ||= []
+  endpointRegistry[url].push(config)
+
+  if (!hasBeenRegistered) {
+    // @ts-expect-error private property
+    window.__registry.add(url)
+
+    app.use('/_' + url, defineEventHandler((event) => {
+      const latestHandler = [...endpointRegistry[url]].reverse().find(config => config.method ? event.method === config.method : true)
+      return latestHandler?.handler(event)
+    }), {
+      match(_, event) {
+        return endpointRegistry[url]?.some(config => config.method ? event?.method === config.method : true)
+      },
+    })
+  }
+
+  return () => {
+    endpointRegistry[url].splice(endpointRegistry[url].indexOf(config), 1)
+    if (endpointRegistry[url].length === 0) {
+      // @ts-expect-error private property
+      window.__registry.delete(url)
+    }
+  }
 }
 
 /**