마이그레이션 가이드

Vitest 0.34.6에서 마이그레이션

최소 요구 사항

Vitest 1.0은 Vite 5.0과 Node.js 18 이상이 필요합니다.

모든 @vitest/* 하위 패키지는 Vitest 1.0 버전을 사용해야 합니다.

스냅샷 업데이트 #3961

스냅샷에서 따옴표는 더 이상 이스케이프 처리되지 않으며, 문자열이 한 줄인 경우에도 모든 스냅샷은 백틱(\)을 사용합니다.

1. 따옴표는 더 이상 이스케이프되지 않습니다.

expect({ foo: 'bar' }).toMatchInlineSnapshot(`
  Object {
-    \\"foo\\": \\"bar\\",
+    "foo": "bar",
  }
`)

2. 한 줄 스냅샷은 이제 "'" 대신 "`" 따옴표를 사용합니다.

- expect('some string').toMatchInlineSnapshot('"some string"')
+ expect('some string').toMatchInlineSnapshot(`"some string"`)

@vitest/snapshot 패키지에도 변경 사항이 있습니다. 직접 사용하지 않는 경우 변경할 필요는 없습니다.

• equalityCheck 메서드를 재정의하기 위해 SnapshotClient를 확장할 필요가 없습니다. 인스턴스를 초기화할 때 isEqual로 전달하면 됩니다.
• client.setTest는 client.startCurrentRun으로 이름이 변경되었습니다.
• client.resetCurrent는 client.finishCurrentRun으로 이름이 변경되었습니다.

풀 표준화 #4172

테스트 러너를 더 쉽게 구성할 수 있도록 설정 옵션이 간소화되었습니다. --threads 또는 관련 플래그를 사용하는 경우 아래 마이그레이션 예제를 참조하십시오.

• --threads는 이제 --pool=threads입니다.
• --no-threads는 이제 --pool=forks입니다.
• --single-thread는 이제 --poolOptions.threads.singleThread입니다.
• --experimental-vm-threads는 이제 --pool=vmThreads입니다.
• --experimental-vm-worker-memory-limit는 이제 --poolOptions.vmThreads.memoryLimit입니다.
• --isolate는 이제 --poolOptions.<pool-name>.isolate 및 browser.isolate입니다.
• test.maxThreads는 이제 test.poolOptions.<pool-name>.maxThreads입니다.
• test.minThreads는 이제 test.poolOptions.<pool-name>.minThreads입니다.
• test.useAtomics는 이제 test.poolOptions.<pool-name>.useAtomics입니다.
• test.poolMatchGlobs.child_process는 이제 test.poolMatchGlobs.forks입니다.
• test.poolMatchGlobs.experimentalVmThreads는 이제 test.poolMatchGlobs.vmThreads입니다.

{
  scripts: {
-    "test": "vitest --no-threads"
     // 동일한 동작을 원할 경우:
+    "test": "vitest --pool forks --poolOptions.forks.singleFork"
     // 또는 다중 병렬 포크를 사용할 경우:
+    "test": "vitest --pool forks"

  }
}

{
  scripts: {
-    "test": "vitest --experimental-vm-threads"
+    "test": "vitest --pool vmThreads"
  }
}

{
  scripts: {
-    "test": "vitest --isolate false"
+    "test": "vitest --poolOptions.threads.isolate false"
  }
}

{
  scripts: {
-    "test": "vitest --no-threads --isolate false"
+    "test": "vitest --pool forks --poolOptions.forks.isolate false"
  }
}

커버리지 변경 사항 #4265, #4442

이제 coverage.all 옵션이 기본적으로 활성화되어 있습니다. 즉, coverage.include 패턴과 일치하는 모든 프로젝트 파일은 실행 여부와 관계없이 처리됩니다.

커버리지 임계값 API 구조가 변경되었으며, 이제 glob 패턴을 사용하여 특정 파일에 대한 임계값을 지정할 수 있습니다.

export default defineConfig({
  test: {
    coverage: {
-      perFile: true,
-      thresholdAutoUpdate: true,
-      100: true,
-      lines: 100,
-      functions: 100,
-      branches: 100,
-      statements: 100,
+      thresholds: {
+        perFile: true,
+        autoUpdate: true,
+        100: true,
+        lines: 100,
+        functions: 100,
+        branches: 100,
+        statements: 100,
+      }
    }
  }
})

Mock 타입 #4400

Jest 스타일의 'Mock' 명명 규칙을 따르기 위해 몇 가지 타입이 제거되었습니다.

- import { EnhancedSpy, SpyInstance } from 'vitest'
+ import { MockInstance } from 'vitest'

WARNING

SpyInstance는 MockInstance로 대체되었으며, 다음 주요 릴리스에서 제거될 예정입니다.

타이머 Mock #3925

vi.useFakeTimers()는 더 이상 process.nextTick을 자동으로 Mock하지 않습니다. vi.useFakeTimers({ toFake: ['nextTick'] })을 사용하여 명시적으로 지정해야 process.nextTick을 Mock할 수 있습니다.

그러나 --pool=forks를 사용하는 경우 process.nextTick 모킹은 불가능합니다. process.nextTick 모킹이 필요한 경우 다른 --pool 옵션을 사용하십시오.

Jest에서 마이그레이션

Vitest는 Jest와의 호환성을 고려하여 설계되었으며, Jest에서 최대한 쉽게 마이그레이션할 수 있도록 API가 설계되었습니다. 이러한 노력에도 불구하고 다음과 같은 차이점이 발생할 수 있습니다.

기본 전역 변수 활성화

Jest는 전역 API가 기본적으로 활성화되어 있습니다. Vitest는 그렇지 않습니다. globals 구성 설정을 통해 전역 변수를 활성화하거나, vitest 모듈에서 가져오기를 사용하도록 코드를 업데이트할 수 있습니다.

전역 변수를 비활성화 상태로 유지하기로 결정한 경우, testing-library와 같은 일반적인 라이브러리는 자동 DOM 정리를 실행하지 않습니다.

모듈 Mock

Jest에서 모듈을 Mock할 때 팩토리 함수의 반환 값은 기본 내보내기(default export)입니다. Vitest에서는 팩토리 함수가 각 내보내기를 명시적으로 정의하는 객체를 반환해야 합니다. 예를 들어, 다음 jest.mock은 다음과 같이 업데이트해야 합니다.

jest.mock('./some-path', () => 'hello'); 
vi.mock('./some-path', () => ({
  default: 'hello', 
})); 

자세한 내용은 vi.mock API 섹션을 참조하십시오.

자동 Mock 동작

Jest와는 달리 <root>/__mocks__에 있는 Mock 모듈은 vi.mock()을 호출해야 로드됩니다. Jest와 마찬가지로 모든 테스트에서 모킹해야 하는 경우 setupFiles 내에서 Mock할 수 있습니다.

Mock된 패키지의 원본 가져오기

패키지를 부분적으로만 Mock하는 경우 이전에 Jest의 함수 requireActual을 사용했을 수 있습니다. Vitest에서는 이러한 호출을 vi.importActual로 바꿔야 합니다.

const { cloneDeep } = jest.requireActual('lodash/cloneDeep'); 
const { cloneDeep } = await vi.importActual('lodash/cloneDeep'); 

외부 라이브러리로 Mock 확장

Jest는 기본적으로 수행하지만, 모듈을 Mock하고 이 Mock을 동일한 모듈을 사용하는 다른 외부 라이브러리로 확장하려는 경우, server.deps.inline을 사용하여 외부 라이브러리가 소스 코드의 일부가 되도록 Mock할 타사 라이브러리를 명시적으로 지정해야 합니다.

server.deps.inline: ["lib-name"]

Mock된 Promise의 반환 값에 접근

Jest와 Vitest 모두 Mock 호출의 결과는 mock.results 배열에 저장되며, 각 호출의 반환 값은 value 속성에서 확인할 수 있습니다. 그러나 Promise를 Mock하거나 스파이하는 경우(예: mockResolvedValue 사용), Jest에서는 value 속성이 Promise이지만, Vitest에서는 Promise가 해결될 때의 값이 됩니다.

await expect(spy.mock.results[0].value).resolves.toBe(123); 
expect(spy.mock.results[0].value).toBe(123); 

환경 변수

Jest와 마찬가지로 Vitest도 이전에 설정되지 않은 경우 NODE_ENV를 test로 설정합니다. Vitest는 또한 JEST_WORKER_ID에 해당하는 VITEST_POOL_ID를 가지고 있습니다(항상 maxThreads보다 작거나 같음). 따라서 해당 변수를 사용하는 경우 이름을 변경해야 합니다. Vitest는 또한 실행 중인 워커의 고유 식별자인 VITEST_WORKER_ID를 노출합니다. 이 숫자는 maxThreads의 영향을 받지 않으며 생성된 각 워커마다 증가합니다.

속성 대체

객체를 수정하려는 경우 Jest에서 replaceProperty API를 사용하는 경우, Vitest에서도 동일하게 수행하기 위해 vi.stubEnv 또는 vi.spyOn을 사용할 수 있습니다.

Done 콜백

Vitest v0.10.0부터는 콜백 스타일로 테스트를 정의하는 방식이 더 이상 사용되지 않습니다. async/await 함수를 사용하거나 Promise를 사용하여 콜백 스타일을 흉내내도록 다시 작성할 수 있습니다.

it('should work', (done) => {  // [!code --]
it('should work', () => new Promise(done => { // [!code ++]
  // ...
  done()
}) // [!code --]
})) // [!code ++]

훅

beforeAll/beforeEach 훅은 Vitest에서 정리 함수를 반환할 수 있습니다. 따라서 undefined나 null이 아닌 값을 반환하는 경우 훅 선언을 수정해야 할 수 있습니다.

beforeEach(() => setActivePinia(createTestingPinia())); 
beforeEach(() => {
  setActivePinia(createTestingPinia());
}); 

Jest에서는 훅이 순차적으로 호출됩니다. 기본적으로 Vitest는 훅을 병렬로 실행합니다. Jest의 동작을 사용하려면 sequence.hooks 옵션을 업데이트하십시오.

export default defineConfig({
  test: {
    sequence: {
      hooks: 'list', 
    }, 
  },
});

타입

Vitest는 jest 네임스페이스를 지원하지 않으므로, vitest에서 직접 타입을 임포트해야 합니다.

let fn: jest.Mock<string, [string]>; 
import type { Mock } from 'vitest'; 
let fn: Mock<[string], string>; 

또한 Vitest에서는 차이점에서 볼 수 있듯이 Returns 대신 첫 번째 인수로 Args 타입을 가집니다.

타이머

Vitest는 Jest의 레거시 타이머를 지원하지 않습니다.

타임아웃

jest.setTimeout을 사용한 경우 vi.setConfig로 마이그레이션해야 합니다.

jest.setTimeout(5_000); 
vi.setConfig({ testTimeout: 5_000 }); 

Vue 스냅샷

이 기능은 Jest에만 해당되는 것은 아니지만, 이전에 vue-cli 프리셋과 함께 Jest를 사용했다면 jest-serializer-vue 패키지를 설치하고 setupFiles에서 사용해야 합니다.

vite.config.js

import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    setupFiles: ['./tests/unit/setup.js'],
  },
});

tests/unit/setup.js

import vueSnapshotSerializer from 'jest-serializer-vue';

expect.addSnapshotSerializer(vueSnapshotSerializer);

그렇지 않으면 스냅샷에 많은 이스케이프된 " 문자가 포함됩니다.