Переход с Karma на Vitest

Angular CLI использует Vitest в качестве средства запуска модульных тестов по умолчанию для новых проектов. В этом руководстве описан переход существующего проекта с Karma и Jasmine на Vitest.

Этапы перехода вручную

Прежде чем использовать схему автоматического рефакторинга, необходимо вручную настроить проект для использования средства запуска тестов Vitest.

1. Установите зависимости

Установите vitest и библиотеку эмуляции DOM. Хотя тестирование в браузере по-прежнему возможно (см. этап 5), Vitest по умолчанию использует библиотеку эмуляции DOM для имитации среды браузера в Node.js и ускорения выполнения тестов. CLI автоматически обнаружит и использует happy-dom, если пакет установлен; в противном случае будет использоваться jsdom. Необходимо установить один из этих пакетов.

npm install --save-dev vitest jsdom

yarn add --dev vitest jsdom

pnpm add -D vitest jsdom

bun add --dev vitest jsdom

2. Обновите angular.json

В файле angular.json найдите цель test для своего проекта и измените значение builder на @angular/build:unit-test.

{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test"
        }
      }
    }
  }
}

Сборщик unit-test по умолчанию использует "tsConfig": "tsconfig.spec.json" и "buildTarget": "::development". Если проекту нужны другие значения, их можно задать явно. Например, если конфигурация сборки development отсутствует или для тестирования нужны другие параметры, можно создать и использовать конфигурацию сборки testing или конфигурацию с похожим именем для buildTarget.

Ранее сборщик @angular/build:karma позволял задавать параметры сборки (например, polyfills, assets или styles) непосредственно в цели test. Новый сборщик @angular/build:unit-test этого не поддерживает. Если параметры сборки для тестов отличаются от параметров существующей конфигурации сборки development, необходимо перенести их в отдельную конфигурацию целевого объекта сборки. Если параметры сборки для тестов уже совпадают с параметрами конфигурации сборки development, ничего делать не нужно.

3. Обработайте пользовательские конфигурации karma.conf.js

Пользовательские конфигурации в karma.conf.js не переносятся автоматически. Прежде чем удалять файл karma.conf.js, проверьте, есть ли в нем пользовательские настройки, которые нужно перенести.

Многим параметрам Karma соответствуют параметры Vitest, которые можно задать в пользовательском файле конфигурации Vitest (например, vitest.config.ts) и подключить к angular.json с помощью параметра runnerConfig.

Типичные способы перехода:

• Репортеры: репортеры Karma необходимо заменить на совместимые с Vitest. Часто их можно настроить непосредственно в angular.json с помощью свойства test.options.reporters. Для более сложных конфигураций используйте пользовательский файл vitest.config.ts.
• Плагины: для плагинов Karma могут существовать аналоги для Vitest — их нужно найти и установить. Обратите внимание: сбор покрытия кода — встроенная возможность Angular CLI, которую можно включить с помощью ng test --coverage.
• Пользовательские средства запуска браузеров: их заменяют параметр browsers в angular.json и установка провайдера браузера, например @vitest/browser-playwright.

Сведения о других настройках см. в официальной документации Vitest.

4. Удалите Karma и файлы test.ts

Теперь можно удалить из проекта karma.conf.js и src/test.ts, а также деинсталлировать пакеты, связанные с Karma. Следующие команды относятся к пакетам, установленным в новом проекте Angular CLI; возможно, в вашем проекте есть другие пакеты, связанные с Karma, которые тоже нужно удалить.

npm uninstall karma karma-chrome-launcher karma-coverage karma-jasmine karma-jasmine-html-reporter jasmine-core

yarn remove karma karma-chrome-launcher karma-coverage karma-jasmine karma-jasmine-html-reporter jasmine-core

pnpm remove karma karma-chrome-launcher karma-coverage karma-jasmine karma-jasmine-html-reporter jasmine-core

bun remove karma karma-chrome-launcher karma-coverage karma-jasmine karma-jasmine-html-reporter jasmine-core

5. Настройте режим браузера (необязательно)

Если тесты необходимо запускать в настоящем браузере, установите провайдера браузера и настройте angular.json.

Установка провайдера браузера:

Выберите подходящий провайдер браузера из списка:

• Playwright: @vitest/browser-playwright для Chromium, Firefox и WebKit.
• WebdriverIO: @vitest/browser-webdriverio для Chrome, Firefox, Safari и Edge.
• Preview: @vitest/browser-preview для сред WebContainer (например, StackBlitz).

npm install --save-dev @vitest/browser-playwright

yarn add --dev @vitest/browser-playwright

pnpm add -D @vitest/browser-playwright

bun add --dev @vitest/browser-playwright

Настройка angular.json для режима браузера:

Добавьте параметр browsers в параметры цели test. Название браузера зависит от установленного провайдера (например, chromium для Playwright, chrome для WebdriverIO).

{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "browsers": ["chromium"]
          }
        }
      }
    }
  }
}

Безголовый режим включается автоматически, если задана переменная окружения CI или название браузера содержит «Headless» (например, ChromeHeadless). В противном случае тесты будут запускаться в браузере с графическим интерфейсом.

Автоматический рефакторинг тестов с помощью схем

Angular CLI предоставляет схему refactor-jasmine-vitest для автоматического рефакторинга тестов Jasmine с целью использования Vitest.

Обзор

Схема автоматически выполняет в файлах тестов (.spec.ts) следующие преобразования:

• Преобразует fit и fdescribe в it.only и describe.only.
• Преобразует xit и xdescribe в it.skip и describe.skip.
• Преобразует вызовы spyOn в соответствующие vi.spyOn.
• Заменяет jasmine.objectContaining на expect.objectContaining.
• Заменяет jasmine.any на expect.any.
• Заменяет jasmine.createSpy на vi.fn.
• Обновляет beforeAll, beforeEach, afterAll и afterEach, заменяя их аналогами Vitest.
• Преобразует fail() в vi.fail() из Vitest.
• Корректирует проверки ожидаемых значений в соответствии с API Vitest.
• Добавляет комментарии TODO для кода, который невозможно преобразовать автоматически.

Схема не выполняет следующие действия:

• Не устанавливает vitest и другие связанные зависимости.
• Не изменяет angular.json для использования сборщика Vitest и не переносит параметры сборки (например, polyfills или styles) из цели test.
• Не удаляет файлы karma.conf.js или test.ts.
• Не обрабатывает сложные или вложенные сценарии с шпионами — для них может потребоваться ручной рефакторинг.

Запуск схемы

После настройки проекта для Vitest можно запустить схему для рефакторинга файлов тестов.

Чтобы выполнить рефакторинг всех файлов тестов в проекте по умолчанию, запустите:

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

Параметры

Для настройки поведения схемы можно использовать следующие параметры:

После перехода

После завершения работы схемы рекомендуется выполнить следующие действия:

1. Запустите тесты: выполните ng test, чтобы убедиться, что после рефакторинга все тесты по-прежнему проходят.
2. Проверьте изменения: просмотрите изменения, внесенные схемой, и внимательно проверьте сложные тесты, особенно тесты с замысловатыми шпионами или моками, поскольку для них могут потребоваться дополнительные ручные исправления.

Команда ng test собирает приложение в режиме наблюдения и запускает настроенное средство запуска. Режим наблюдения включен по умолчанию при работе в интерактивном терминале вне CI.

Конфигурация

Angular CLI берет на себя настройку Vitest, формируя полную конфигурацию в памяти на основе параметров из angular.json.

Пользовательская конфигурация Vitest

Можно указать пользовательский файл конфигурации Vitest, чтобы переопределить настройки по умолчанию. Полный список доступных параметров см. в официальной документации Vitest.

1. Прямой путь: укажите прямой путь к файлу конфигурации Vitest в angular.json:

{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {"runnerConfig": "vitest.config.ts"}
        }
      }
    }
  }
}

2. Автоматический поиск базовой конфигурации: если задать для runnerConfig значение true, сборщик автоматически выполнит поиск общего файла vitest-base.config.* в корне проекта и рабочей области.

Патч zone.js для Vitest

Чтобы использовать такие функции, как fakeAsync, flush или waitForAsync, либо обеспечить совместимость существующих тестов с этими функциями, можно добавить zone.js/plugins/vitest-patch в полифилы цели тестирования в angular.json.

В любом случае мы настоятельно рекомендуем начать планировать переход существующих наборов тестов на нативные async и фальшивые таймеры Vitest, поскольку это общепринятый подход.

Пример использования фальшивых таймеров в Vitest см. здесь.

Сообщения об ошибках

Сообщайте о проблемах и запрашивайте новые функции на GitHub.

По возможности предоставьте минимальный пример, воспроизводящий проблему, чтобы помочь команде разобраться с ней.