vitest-dev
diff --git a/‎packages/spy/src/index.ts‎
Lines changed: 1 addition & 1 deletion b/‎packages/spy/src/index.ts‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎test/browser/test/mocking.test.ts‎
Lines changed: 1 addition & 1 deletion b/‎test/browser/test/mocking.test.ts‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎test/unit/test/mocking/vi-spyOn.test.ts‎
Lines changed: 33 additions & 0 deletions b/‎test/unit/test/mocking/vi-spyOn.test.ts‎
Lines changed: 33 additions & 0 deletions
@@ -410,7 +410,7 @@ export function spyOn<T extends object, K extends keyof any>(
         || error.message.includes('can\'t redefine non-configurable property'))
     ) {
       throw new TypeError(
-        `Cannot spy on export "${String(key)}". Module namespace is not configurable in ESM. See: https://vitest.dev/guide/browser/#limitations`,
+        `Cannot spy on export "${String(key)}". Module namespace is not configurable in ESM. See: https://vitest.dev/guide/mocking/modules#mocking-a-module`,
         { cause: error },
       )
     }
 
@@ -12,7 +12,7 @@ it('spying on an esm module prints an error', () => {
     }
   })()
   expect(error.name).toBe('TypeError')
-  expect(error.message).toMatchInlineSnapshot(`"Cannot spy on export "calculator". Module namespace is not configurable in ESM. See: https://vitest.dev/guide/browser/#limitations"`)
+  expect(error.message).toMatchInlineSnapshot(`"Cannot spy on export "calculator". Module namespace is not configurable in ESM. See: https://vitest.dev/guide/mocking/modules#mocking-a-module"`)
 
   expect(error.cause).toBeInstanceOf(TypeError)
 })
@@ -19,6 +19,39 @@ describe('vi.spyOn() edge cases', () => {
     expect(fn3.length).toBe(3)
   })
 
+  test('spying on a non-configurable ESM namespace export points to the module mocking docs, not browser mode', () => {
+    // Fake an ES module namespace: `Symbol.toStringTag` is 'Module' and the
+    // export is non-configurable, so `Object.defineProperty` throws
+    // "Cannot redefine property" — the same guard the real ESM path hits.
+    const namespace: Record<string, unknown> = {}
+    Object.defineProperty(namespace, Symbol.toStringTag, { value: 'Module' })
+    Object.defineProperty(namespace, 'answer', {
+      value: () => 42,
+      enumerable: true,
+      configurable: false,
+      writable: false,
+    })
+    Object.preventExtensions(namespace)
+
+    const error = (() => {
+      try {
+        vi.spyOn(namespace as any, 'answer')
+        expect.unreachable()
+      }
+      catch (err) {
+        return err as Error
+      }
+    })()
+
+    expect(error).toBeInstanceOf(TypeError)
+    expect(error.message).toContain('Cannot spy on export "answer"')
+    // This error fires in Node too, so it must not send users to the
+    // browser-mode-only docs (issue #9467). It should point at the
+    // environment-agnostic module mocking guide instead.
+    expect(error.message).toContain('https://vitest.dev/guide/mocking/modules#mocking-a-module')
+    expect(error.message).not.toContain('/guide/browser')
+  })
+
   test('can spy on a proxy with undefined descriptor\'s value', () => {
     const obj = new Proxy<{ fn: () => number }>({} as any, {
       get(_, prop) {
Original file line number	Diff line number	Diff line change
`@@ -410,7 +410,7 @@ export function spyOn<T extends object, K extends keyof any>(`
`410`	`410`	`\|\| error.message.includes('can\'t redefine non-configurable property'))`
`411`	`411`	`) {`
`412`	`412`	`throw new TypeError(`
`413`		- `Cannot spy on export "${String(key)}". Module namespace is not configurable in ESM. See: https://vitest.dev/guide/browser/#limitations`,
	`413`	+ `Cannot spy on export "${String(key)}". Module namespace is not configurable in ESM. See: https://vitest.dev/guide/mocking/modules#mocking-a-module`,
`414`	`414`	`{ cause: error },`
`415`	`415`	`)`
`416`	`416`	`}`
Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,7 @@ it('spying on an esm module prints an error', () => {`
`12`	`12`	`}`
`13`	`13`	`})()`
`14`	`14`	`expect(error.name).toBe('TypeError')`
`15`		- expect(error.message).toMatchInlineSnapshot(`"Cannot spy on export "calculator". Module namespace is not configurable in ESM. See: https://vitest.dev/guide/browser/#limitations"`)
	`15`	+ expect(error.message).toMatchInlineSnapshot(`"Cannot spy on export "calculator". Module namespace is not configurable in ESM. See: https://vitest.dev/guide/mocking/modules#mocking-a-module"`)
`16`	`16`
`17`	`17`	`expect(error.cause).toBeInstanceOf(TypeError)`
`18`	`18`	`})`