vitest: clarify important default behavior difference for spies (#34)

* docs: clarify important default behavior difference for spies

- Changed "almost the same" to "is similar to" for spy concept comparison
- Added new section explaining critical difference in default behavior:
  * Jasmine: spyOn() returns undefined by default (stubs the method)
  * Vitest: vi.spyOn() executes original implementation by default
- This is crucial information for migration from Jasmine to Vitest

* docs: add section about cleaning up spies

* docs: add context about Angular team's decision on spy behavior

Author: JohannesHoppe

blog/2025-11-migrate-to-vitest/README.md

@@ -361,7 +361,7 @@ Because of this, most projects will probably not need additional changes here.
 
 ### Spies and mocks
 
-The spying concept works almost the same as in Jasmine, but it is provided through the [`vi` object](https://vitest.dev/api/vi.html#vi-spyon):
+The spying concept is similar to Jasmine and is provided through the [`vi` object](https://vitest.dev/api/vi.html#vi-spyon):
 
 ```ts
 // Jasmine
@@ -393,6 +393,57 @@ const onItem = jasmine.createSpy('onItem').and.returnValue(true);
 const onItem = vi.fn().mockName('onItem').mockReturnValue(true);
 ```
 
+#### Important difference: Default behavior of spies
+
+In Jasmine, a spy returns `undefined` by default if no specific return value has been configured.
+In Vitest, however, the **original implementation is executed** unless you explicitly set a mock value:
+
+```ts
+const book = { rating: 3 };
+
+// Jasmine
+const spy = spyOn(service, 'rateUp');
+const result = service.rateUp(book);
+// result = undefined (Spy stubbed the method)
+
+// Vitest
+const spy = vi.spyOn(service, 'rateUp');
+const result = service.rateUp(book);
+// result = { rating: 4 } (Original method is called!)
+```
+
+This difference is especially important when migrating existing Jasmine tests to Vitest.
+If you need the original Jasmine behavior (i.e., returning `undefined`), you must explicitly use `.mockReturnValue(undefined)`.
+
+#### Cleaning up spies
+
+Angular TestBed creates a new test environment before each test.
+This means services are also re-instantiated. Spies on services therefore disappear automatically between tests.
+
+However, spies on **global objects** remain active:
+
+```ts
+vi.spyOn(Math, 'random').mockReturnValue(0.5);
+vi.spyOn(console, 'log');
+```
+
+Without explicit cleanup, such spies would "leak" into subsequent tests and cause unexpected behavior (test pollution).
+
+**If** you mock global objects, you should clean up spies in `afterEach()`:
+
+```ts
+import { afterEach, vi } from 'vitest';
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+```
+
+Alternatively, you can set the option `test.restoreMocks: true` in `vitest.config.ts`, and Vitest will handle the cleanup automatically.
+
+Unfortunately, this setting is not the default.
+The Angular team has [deliberately chosen the standard Vitest behavior](https://github.com/angular/angular-cli/issues/30478), forgoing maximum Jasmine compatibility.
+
 ### Asynchrony without Zone.js using Vitest timers
 
 Since Angular 21, unit tests run zoneless by default.