Mocking Services and HttpClient in Angular Vitest: vi.fn, Spies, and DI

The spy names changed, the idea did not#

The first test you open after moving to Vitest is usually the one with a spy in it, and the spy does not compile. jasmine.createSpy is gone, spyOn(...).and.returnValue(...) is gone, expect(spy).toHaveBeenCalledTimes is the same but spy.calls.count() is not. The reflex is to think the test framework got harder. It did not. Most of the surface is a one-to-one rename, and Angular 22's refactor-jasmine-vitest schematic does the mechanical pass for you.

The official migration guide names the conversions directly: it Replaces jasmine.createSpy with vi.fn, Converts spyOn calls to the equivalent vi.spyOn, and Replaces jasmine.objectContaining with expect.objectContaining. Read the table below as the map the schematic follows, and the next section as the one call the schematic cannot make for you.

The one rename that is a behavior change#

spyOn to vi.spyOn looks like a pure rename. It is the one row in that table that changes what the test does. Jasmine's default spy strategy is and.stub(): a bare spyOn(service, 'save') replaces the method with a no-op that returns undefined. Vitest's vi.spyOn does the opposite by default. It wraps the real method and calls through to it, so the original code still runs unless you add .mockReturnValue or .mockImplementation.

That difference is silent and it bites. A Jasmine test that spied on save() to stop a real HTTP call from firing will, after a literal rename to vi.spyOn, let that call fire again. The test may still pass while hitting a real backend or throwing deep in a dependency the test never meant to exercise. This is the call the schematic cannot make: it converts the syntax, but it cannot know you relied on Jasmine's stub-by-default.

So when I review a spyOn to vi.spyOn diff, the only question I ask is: did this spy intend to suppress the real method? If yes, the conversion is incomplete until it has an explicit .mockReturnValue(...) or .mockImplementation(() => {}). I would not merge a bare vi.spyOn on a method with side effects.

import { vi } from 'vitest';

// 1. Standalone fake (was jasmine.createSpy): returns what you tell it.
const load = vi.fn().mockReturnValue(of([{ id: 1 }]));

// 2. Spy that SUPPRESSES the real method (Jasmine's default; Vitest is not).
const svc = TestBed.inject(OrdersService);
vi.spyOn(svc, 'save').mockResolvedValue({ ok: true });

// 3. Spy that only OBSERVES and lets the real method run (Vitest's default).
const audit = vi.spyOn(svc, 'audit');
svc.confirm();
expect(audit).toHaveBeenCalledWith('confirm');

The Angular-idiomatic mock is a DI provider, not a spy#

Spies are the answer when you want to watch or bend one method on an object you already have. They are the wrong tool for replacing a whole collaborator. In Angular the unit under test gets its collaborators through the injector, so the natural place to substitute a fake is the same place: the providers array. You hand TestBed a fake object and tell it to use that instead of the real service.

The fake is a plain object whose methods are vi.fn()s. No vi.spyOn on a real instance, no real service constructed, no transitive dependency dragged in. The provide/useValue pair is the same shape the Angular testing guide shows for stubbing a dependency, and it reads the same to anyone who has written an Angular test since 2017. vi.fn() just replaces jasmine.createSpy() inside it.

I prefer this over module-level mocking for any service the component or service under test injects, because it mocks at the boundary the application actually uses (the injector) rather than reaching past it to the module system. It also keeps the fake typed against the real interface, so a method rename breaks the test instead of silently passing.

import { vi } from 'vitest';
import { TestBed } from '@angular/core/testing';

// A typed fake: every method is a vi.fn(). Typed against the real service,
// so a signature change in OrdersService fails this test instead of passing.
const ordersMock: Partial<Record<keyof OrdersService, ReturnType<typeof vi.fn>>> = {
  load: vi.fn().mockReturnValue(of([{ id: 1, total: 90 }])),
  save: vi.fn().mockResolvedValue({ ok: true }),
};

beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [{ provide: OrdersService, useValue: ordersMock }],
  });
});

it('loads orders on init', () => {
  const facade = TestBed.inject(OrdersFacade);
  facade.init();
  expect(ordersMock.load).toHaveBeenCalledOnce();
});

HttpClient: the testing backend is unchanged#

The most common worry after the runner swap is the HTTP tests, and it is the most misplaced. provideHttpClientTesting and HttpTestingController are Angular APIs, not Karma APIs. They never depended on the test runner, so they work under Vitest exactly as they did under Karma. Nothing about the request-matching layer changed.

For a plain HTTP test, the only provider you need is provideHttpClientTesting(). The moment you are testing client configuration (an interceptor, for example) you add provideHttpClient(...) as well, and order matters: the docs are explicit that provideHttpClient() must come before provideHttpClientTesting(), because the testing provider overwrites parts of the real one. The injected HttpTestingController gives you expectOne, match, expectNone, the request's flush and error, and verify to assert no request went unanswered.

I keep httpTesting.verify() in afterEach on every HTTP spec. It is the one assertion that catches a request the component fired that the test forgot to expect, which is exactly the kind of regression a mocked service would hide.

import { TestBed } from '@angular/core/testing';
import { provideHttpClient } from '@angular/common/http';
import { provideHttpClientTesting, HttpTestingController } from '@angular/common/http/testing';

let httpTesting: HttpTestingController;

beforeEach(() => {
  TestBed.configureTestingModule({
    // provideHttpClient(...) first, then the testing provider overrides the backend.
    providers: [provideHttpClient(), provideHttpClientTesting()],
  });
  httpTesting = TestBed.inject(HttpTestingController);
});

afterEach(() => httpTesting.verify()); // no request left unanswered

it('GETs the order and maps it', () => {
  const service = TestBed.inject(OrdersService);
  let result: Order | undefined;
  service.load(1).subscribe((o) => (result = o));

  const req = httpTesting.expectOne('/api/orders/1');
  expect(req.request.method).toBe('GET');
  req.flush({ id: 1, total: 90 });

  expect(result?.total).toBe(90);
});

When vi.mock is right, and why it fights DI#

vi.mock replaces a module's exports across the whole file. That is the right tool when the thing you need to fake is not injected: a bare ES import your code calls directly, a third-party SDK with no Angular provider, a Date or crypto helper imported as a function. For those, DI has no seam, and vi.mock is the only seam there is.

It is the wrong tool for an injected Angular service, and the reason is mechanical, not stylistic. Vitest hoists every vi.mock call to the top of the file, above your imports, so the factory runs before any test setup and cannot see a TestBed value or a variable defined later (that is what vi.hoisted exists to work around). It replaces the class the module exports, but Angular does not resolve a service by importing its class at call time; it resolves the provider registered in the injector. So a vi.mock of the service file can leave the component still receiving the real provider, and you debug a mock that looks installed but never applied.

Given an injected service, I would refuse vi.mock and use the DI provider every time. I reach for vi.mock only when there is no injector seam to use, and even then I keep the mocked surface as small as the test needs, because a hoisted module mock is the easiest thing in a Vitest suite to leak into the next test.

import { vi } from 'vitest';

// RIGHT use: a third-party module the code imports directly, no DI seam.
// Hoisted above imports, so it is replaced before the code under test loads.
vi.mock('nanoid', () => ({ nanoid: () => 'test-id-123' }));

// WRONG use for an injected service: this replaces the class export, but the
// component still gets whatever provider the injector holds. Prefer:
TestBed.configureTestingModule({
  providers: [{ provide: OrdersService, useValue: { load: vi.fn() } }],
});

Clear, reset, restore: pick one and configure it#

Spies leak between tests when nobody resets them, and Vitest gives you three verbs that are easy to confuse. mockClear wipes call history and leaves the implementation. mockReset wipes history and drops the implementation back to an empty vi.fn(). mockRestore does the reset and puts the original method back, so it only means something for spies created with vi.spyOn.

Rather than call these by hand in every afterEach, set the policy once in the test target options. restoreMocks: true runs the equivalent of vi.restoreAllMocks() after each test, which both resets call history and un-patches every vi.spyOn, so a spy in one spec cannot bleed into the next. That is the setting I want on by default, because a leaked spy is a flaky test waiting to be blamed on something else.