De Karma para Vitest no Angular: a config que realmente roda

O test target inteiro é uma linha#

Depois do Karma você espera um arquivo de config. Não existe. O test target inteiro de Vitest no angular.json é a linha do builder: { "builder": "@angular/build:unit-test" }. Sem vitest.config.ts, sem karma.conf.js, sem test.ts de bootstrap pra manter.

O ng new no Angular v21 gera exatamente isso, mais um tsconfig.spec.json cuja única linha notável é "types": ["vitest/globals"]. É o que faz describe, it e expect funcionarem sem import. O runner usa jsdom por padrão. Esse é o setup inteiro.

Algumas docs mostram um target avançado carregando um providersFile. Isso é opcional, não o default. Comece pela linha única e adicione knobs só quando um teste precisar.

// O tsconfig.spec.json define "types": ["vitest/globals"], então describe, it
// e expect não precisam de import. O builder roda isso em jsdom por padrão.
describe('AppComponent', () => {
  it('cria', () => {
    const fixture = TestBed.createComponent(AppComponent);
    expect(fixture.componentInstance).toBeTruthy();
  });
});

De onde vêm polyfills, styles e assets#

A razão de o test target poder ser uma linha é que ele não redefine seu app. Ele reusa o build target do projeto (a configuração de development) para compilar o app sob teste. Então os polyfills, styles e assets que você define no build já estão valendo. Você não os repete no test.

Esse detalhe tem uma consequência que vale saber antes de escrever um único teste. Como os polyfills de build incluem zone.js, o zone.js é carregado nos testes também. Mas o runner do Vitest nunca envolve cada teste na zone de teste do Angular, então fakeAsync, tick e waitForAsync lançam o erro de ProxyZone. A config está certa. Os helpers de tempo é que precisam de reescrita, um trabalho separado.

O install: adicionar Vitest, tirar Karma#

Migrar um projeto Karma existente é, na maior parte, cirurgia de dependência. Adiciona Vitest e jsdom, remove os pacotes de Karma e Jasmine, e aponta o target test pro builder de unit-test. O Angular 22 traz um schematic migrate-karma-to-vitest que automatiza a troca; os passos abaixo são o que ele faz por baixo, e o que revisar quando termina.

A primeira rodada é ng test. No CI, adicione --no-watch, já que o watch mode liga por padrão num terminal e desliga fora dele. Rode os specs simples primeiro e confirme que passam antes de tocar em qualquer coisa que mexa com tempo.

npm install --save-dev vitest jsdom @vitest/coverage-v8
npm rm karma karma-chrome-launcher karma-jasmine karma-jasmine-html-reporter karma-coverage jasmine-core @types/jasmine
ng test --no-watch

As opções que valem adicionar#

Mantenha o target mínimo e adicione só o que um teste de fato precisa. Essas são as que mais aparecem, todas em architect.test.options para você não redigitar a cada rodada.

A config é a parte fácil#

Se o target é uma linha, por que a migração leva uma tarde? Porque a config nunca foi o trabalho. O trabalho são os specs que quebram quando a test zone some: os testes de fakeAsync e waitForAsync que precisam de uma reescrita para fake timers do Vitest. E antes de começar, vale decidir se a migração compensa para uma suíte específica.

A config te dá um runner verde em uma linha. O resto do trabalho é manter ele verde.