Article Angular

Article

Vitest Is Angular’s Primary Test Runner: A Practical Karma Migration

Move an existing Angular unit-test suite from Karma and Jasmine to the Angular CLI’s Vitest runner without treating it as a blind search-and-replace.

2 min read Angular

With Angular 21, Vitest became Angular’s primary unit-test runner. New CLI projects use it by default, and ng test now runs Vitest through Angular’s integrated test builder. For an established project, the good news is that Angular’s TestBed and most component tests stay familiar. The migration work is concentrated in configuration, Jasmine-specific matchers, and Zone-dependent async tests.

Configure the runner before refactoring tests

Update Angular first and commit the result. The current Angular migration is experimental and requires the application build system, so make that baseline work before changing a spec. Install Vitest and a DOM implementation, then point the test target at Angular’s unit-test builder:

npm install --save-dev vitest jsdom
{
  "projects": {
    "my-app": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test"
        }
      }
    }
  }
}

The CLI constructs the Vitest configuration from angular.json, so no separate config file is required for ordinary Angular tests. When you genuinely need one, note that a stray vitest.config.ts is ignored: the builder reads the runnerConfig option, which takes an explicit path, or true to pick up a shared vitest-base.config.*. Reach for that deliberately, not as a reflex.

Once the project is configured for Vitest, optionally let Angular make the routine Jasmine-to-Vitest changes:

ng g @schematics/angular:refactor-jasmine-vitest

Review its diff before changing test code. The schematic handles common patterns, but it deliberately leaves complex and nested spies for a human review.

Convert Jasmine APIs deliberately

Vitest provides Jest-compatible globals. The common replacements are small:

// Jasmine
spyOn(api, 'save').and.returnValue(of(result));
expect(api.save).toHaveBeenCalledWith(payload);

// Vitest
vi.spyOn(api, 'save').mockReturnValue(of(result));
expect(api.save).toHaveBeenCalledWith(payload);

Import what your TypeScript setup requires:

import {describe, expect, it, vi} from 'vitest';

Do not mechanically rename every matcher. Read failing tests one group at a time, especially custom Jasmine matchers and clock-based tests. Vitest fake timers use vi.useFakeTimers() and vi.advanceTimersByTime().

Make asynchronous tests native

The durable pattern is async/await, not a dependency on patched timer APIs:

it('renders the saved name', async () => {
  component.name.set('Ada');

  await fixture.whenStable();

  expect(fixture.nativeElement.textContent).toContain('Ada');
});

If a large legacy suite relies on fakeAsync, flush, or waitForAsync, Angular documents a temporary zone.js/plugins/vitest-patch. Treat it as compatibility scaffolding while you convert tests to native async code and Vitest timers.

Do not delete configuration blindly

Before removing karma.conf.js, record what it does. Karma reporters, plugins, custom browser launchers, coverage settings, and test-only styles all need an intentional home. Angular’s migration guide calls out one subtlety: test-only build options formerly placed in the Karma target belong in a dedicated build configuration when they differ from the normal development build.

When browser execution is genuinely necessary, configure a Vitest browser provider and the browsers option. Otherwise, Angular runs Vitest in a Node environment with jsdom by default.

Only after the migrated suite is green should you delete karma.conf.js, src/test.ts, and the Karma/Jasmine packages. That sequencing makes failures explainable and the final dependency cleanup safe. The official Karma-to-Vitest migration guide and Angular testing overview cover the schematic, configuration boundaries, and compatibility patch in detail.

Related articles

Keep reading

Search

Search the publication

Search articles and topic pages without leaving the page.