---
title: "Quando migrar uma suíte Angular para Vitest"
description: "Vitest virou o test runner padrão do Angular CLI, mas migrar uma suíte existente ainda é experimental: quais specs migrar primeiro, o que o fakeAsync quebra, e como manter o CI confiável."
deck: "[Vitest é o default test runner desde o Angular v21](https://angular.dev/guide/testing) (novembro/2025), mas suítes Karma/Jasmine existentes pedem filtro de migração. A [documentação oficial de migração](https://angular.dev/guide/testing/migrating-to-vitest) é explícita: 'Migrating an existing project to Vitest is considered experimental.' Doug Parker já [anunciava a depreciação do Karma em abril/2023](https://blog.angular.dev/moving-angular-cli-to-jest-and-web-test-runner-ef85ef69ceca); o caminho foi longo."
author: "André Ramos"
url: "https://andreramos.dev/pt/angular/move-angular-test-suite-to-vitest/"
lang: "pt-BR"
type: "article"
---

# Quando migrar uma suíte Angular para Vitest

> [Vitest é o default test runner desde o Angular v21](https://angular.dev/guide/testing) (novembro/2025), mas suítes Karma/Jasmine existentes pedem filtro de migração. A [documentação oficial de migração](https://angular.dev/guide/testing/migrating-to-vitest) é explícita: 'Migrating an existing project to Vitest is considered experimental.' Doug Parker já [anunciava a depreciação do Karma em abril/2023](https://blog.angular.dev/moving-angular-cli-to-jest-and-web-test-runner-ef85ef69ceca); o caminho foi longo.

## Default não é obrigação

Para projetos novos do Angular CLI, Vitest é o default atual. Isso é um sinal forte sobre a direção dos testes no Angular. Não é a mesma coisa que dizer que toda suíte Karma/Jasmine existente deve migrar em uma branch.

Uma migração de test runner só é bem-sucedida se o time confia no resultado depois. Se a migração deixa o CI mais rápido, mas ninguém acredita nas falhas ou nos passes, o projeto perdeu sinal.

## A primeira fatia importa

| Candidato | Boa primeira fatia? | Por quê |
|---|---|---|
| Pipes puros | Sim | Pouca dependência de DOM e paridade fácil de assertions. |
| Services sem globais de browser | Sim | Feedback rápido com setup simples. |
| Helpers de validação | Sim | Útil para forms sem complexidade de UI. |
| Componentes pequenos | Talvez | Bom se evitam overlays, animações e timers complexos. |
| Specs de overlay, canvas, drag/drop ou browser pesado | Depois | Começam pelo caminho mais difícil da migração. |

## O que rodar primeiro

A primeira branch de migração deve provar configuração, comportamento no CI e um conjunto pequeno de padrões de teste. Não comece apagando Karma de uma aplicação grande.

O caminho oficial de migração inclui configuração manual, browser mode opcional e um schematic experimental para refatorar Jasmine para Vitest. Isso significa que todo diff gerado ainda precisa de review.

*Comandos para um piloto pequeno de Vitest*

```bash
npm install --save-dev vitest jsdom
ng test --no-watch
ng g @schematics/angular:refactor-jasmine-vitest --include=src/app/orders
```

## O que me faria esperar

Espere se a suíte depende muito de `fakeAsync`, `flush`, APIs apenas de browser, launchers customizados de Karma ou setup global de teste que ninguém entende hoje. Isso não bloqueia para sempre, mas é um péssimo começo.

O guia oficial de migração para Vitest é explícito: helpers baseados em Zone.js, como `fakeAsync`, `flush` e `waitForAsync`, não são suportados. Exemplos novos nesta série devem preferir async nativo, assertions em Observables ou timers do Vitest, a menos que estejam claramente marcados como código Karma/Jasmine.

A proposta correta não é 'migrar todos os testes para Vitest'. É 'migrar esta fatia, comparar tempo e qualidade do CI, documentar padrões sem suporte e decidir a próxima fatia'.

## Artefato reaproveitável: Critérios de aceite para piloto Vitest

- Uma fatia pequena migrada e revisada.
- Tempo de CI comparado antes e depois.
- Padrões sem suporte documentados, especialmente helpers de teste baseados em Zone.js.
- Necessidade de browser mode decidida explicitamente.
- Karma mantido até o time confiar no caminho novo.

## Fontes consultadas

- https://angular.dev/guide/testing
- https://angular.dev/guide/testing/migrating-to-vitest
- https://angular.dev/api/schematics/refactor-jasmine-vitest
- https://vitest.dev/guide
- https://blog.angular.dev/moving-angular-cli-to-jest-and-web-test-runner-ef85ef69ceca
- https://blog.angular.dev/announcing-angular-v20-b5c9c06cf301
- https://blog.angular.dev/announcing-angular-v21-57946c34f14b
- https://angular.dev/roadmap

## Leia também

- [Testando componentes no Angular com Vitest: TestBed, jsdom e browser mode](https://andreramos.dev/pt/angular/vitest-component-testing-angular/)
- [Mockando serviços e HttpClient no Angular com Vitest: vi.fn, spies e DI](https://andreramos.dev/pt/angular/mocking-angular-services-vitest/)
- [De Karma para Vitest no Angular: a config que realmente roda](https://andreramos.dev/pt/angular/karma-to-vitest-angular-config/)