타입 검사

샘플 프로젝트

GitHub - 온라인 플레이

Vitest는 expectTypeOf 또는 assertType 구문을 사용하여 타입 테스트를 작성할 수 있도록 지원합니다. 기본적으로 *.test-d.ts 파일 내의 모든 테스트는 타입 테스트로 처리되지만, typecheck.include 설정 옵션을 통해 이 동작을 변경할 수 있습니다.

내부적으로 Vitest는 설정에 따라 tsc나 vue-tsc를 호출하여 그 결과를 분석합니다. Vitest는 소스 코드에서 타입 오류를 발견할 경우 이를 출력합니다. 이 기능은 typecheck.ignoreSourceErrors 설정 옵션을 사용하여 비활성화할 수 있습니다.

Vitest는 이 파일들을 직접 실행하지 않고, 컴파일러가 정적으로만 분석한다는 점을 유의하십시오. 이는 동적 이름이나 test.each, test.for 등을 사용하더라도 테스트 이름이 평가되지 않고 그대로 표시됨을 의미합니다.

WARNING

Vitest 2.1 이전에는 typecheck.include가 include 패턴을 재정의했기 때문에 런타임 테스트가 실제로 실행되지 않고 타입 검사만 수행되었습니다.

Vitest 2.1부터는 include와 typecheck.include가 겹치면 Vitest는 타입 테스트와 런타임 테스트를 별도의 항목으로 보고합니다.

--allowOnly 및 -t와 같은 CLI 플래그 또한 타입 검사에서 지원됩니다.

import { assertType, expectTypeOf } from 'vitest';
import { mount } from './mount.js';

test('my types work properly', () => {
  expectTypeOf(mount).toBeFunction();
  expectTypeOf(mount).parameter(0).toMatchTypeOf<{ name: string }>();

  // @ts-expect-error name is a string
  assertType(mount({ name: 42 }));
});

테스트 파일 내에서 발생하는 모든 타입 오류는 테스트 오류로 처리됩니다. 따라서 프로젝트의 타입을 테스트하기 위해 원하는 모든 타입 관련 기법을 사용할 수 있습니다.

가능한 매처 목록은 API 섹션에서 확인할 수 있습니다.

오류 읽기

expectTypeOf API를 사용하는 경우, expect-type 문서의 오류 메시지를 참조하십시오.

타입이 일치하지 않을 때, .toEqualTypeOf 및 .toMatchTypeOf는 특별한 헬퍼 타입을 사용하여 가능한 한 실행 가능한 오류 메시지를 생성합니다. 하지만 이를 이해하는 데는 약간의 미묘한 차이가 있습니다. 어설션이 "연속적으로" 작성되므로, 실패는 "실제" 타입이 아닌 "예상" 타입에 있어야 합니다(expect<Actual>().toEqualTypeOf<Expected>()). 이는 타입 오류가 다소 혼란스러울 수 있음을 의미합니다. 따라서 이 라이브러리는 MismatchInfo 타입을 생성하여 기대하는 바를 명시적으로 나타내려고 합니다. 예를 들어:

expectTypeOf({ a: 1 }).toEqualTypeOf<{ a: string }>();

이는 {a: 1}이 {a: number} 타입이고 {a: string}이 아니기 때문에 실패할 어설션입니다. 이 경우 오류 메시지는 다음과 같이 나타납니다:

test/test.ts:999:999 - error TS2344: Type '{ a: string; }' does not satisfy the constraint '{ a: \\"Expected: string, Actual: number\\"; }'.
  Types of property 'a' are incompatible.
    Type 'string' is not assignable to type '\\"Expected: string, Actual: number\\"'.

999 expectTypeOf({a: 1}).toEqualTypeOf<{a: string}>()

보고된 타입 제약 조건은 "예상" 및 "실제" 타입을 모두 지정하는, 사람이 읽을 수 있는 메시지임을 유의하십시오. 'Types of property 'a' are incompatible // Type 'string' is not assignable to type "Expected: string, Actual: number"' 문장을 문자 그대로 해석하기보다는, 속성 이름('a')과 메시지(Expected: string, Actual: number`)를 살펴보십시오. 대부분의 경우 이를 통해 무엇이 잘못되었는지 파악할 수 있을 것입니다. 극도로 복잡한 타입은 디버깅에 더 많은 노력이 필요하며, 일부 실험이 요구될 수 있습니다. 오류 메시지가 실제로 오해의 소지가 있다면 이슈를 제기해 주십시오.

toBe... 메서드(toBeString, toBeNumber, toBeVoid 등)는 테스트 중인 Actual 타입이 일치하지 않을 때 호출 불가능한 타입으로 확인되면서 실패합니다. 예를 들어, expectTypeOf(1).toBeString()과 같은 어설션의 실패는 다음과 같이 나타날 것입니다:

test/test.ts:999:999 - error TS2349: This expression is not callable.
  Type 'ExpectString<number>' has no call signatures.

999 expectTypeOf(1).toBeString()
                    ~~~~~~~~~~

'This expression is not callable' 부분은 크게 도움이 되지 않습니다. 의미 있는 오류는 다음 줄인 'Type 'ExpectString<number>' has no call signatures'입니다. 이는 본질적으로 숫자를 전달했지만 문자열이어야 한다고 주장한 것과 같습니다.

만약 TypeScript가 "throw" 타입에 대한 지원을 추가한다면 이러한 오류 메시지는 크게 개선될 수 있을 것입니다. 그때까지는 어느 정도 주의 깊은 확인이 필요할 것입니다.

구체적인 "예상" 객체 vs 타입 인수

다음과 같은 어설션의 오류 메시지는:

expectTypeOf({ a: 1 }).toEqualTypeOf({ a: '' });

다음과 같은 어설션보다 덜 유용합니다:

expectTypeOf({ a: 1 }).toEqualTypeOf<{ a: string }>();

이는 TypeScript 컴파일러가 .toEqualTypeOf({a: ''}) 스타일에 대한 타입 인수를 추론해야 하고, 이 라이브러리는 이를 일반 Mismatch 타입과 비교하여 실패로만 표시할 수 있기 때문입니다. 따라서 가능한 경우 .toEqualTypeOf 및 toMatchTypeOf에 구체적인 타입 대신 타입 인수를 사용하십시오. 두 개의 구체적인 타입을 비교하는 것이 훨씬 편리할 경우, typeof를 사용할 수 있습니다:

const one = valueFromFunctionOne({ some: { complex: inputs } });
const two = valueFromFunctionTwo({ some: { other: inputs } });

expectTypeOf(one).toEqualTypeOf<typeof two>();

expectTypeOf API를 사용하고 오류를 파악하는 데 어려움을 느낀다면, 언제든지 보다 간단한 assertType API를 사용할 수 있습니다:

const answer = 42;

assertType<number>(answer);
// @ts-expect-error answer is not a string
assertType<string>(answer);

TIP

@ts-expect-error 구문을 사용할 때, 오타가 없는지 확인하는 것이 좋습니다. test.include 설정 옵션에 타입 파일을 포함함으로써 Vitest가 실제로 이 테스트를 _실행_하고 ReferenceError로 실패하도록 할 수 있습니다.

이는 오류를 예상하기 때문에 통과하지만, "answer"라는 단어에 오타가 있어 거짓 양성(false positive) 오류가 됩니다:

// @ts-expect-error answer is not a string
assertType<string>(answr);

타입 검사 실행

타입 검사를 활성화하려면 package.json의 Vitest 명령에 --typecheck 플래그를 추가하십시오:

{
  "scripts": {
    "test": "vitest --typecheck"
  }
}

이제 타입 검사를 실행할 수 있습니다:

npm

npm run test

yarn

yarn test

pnpm

pnpm run test

bun

bun test

Vitest는 설정에 따라 tsc --noEmit 또는 vue-tsc --noEmit를 사용하기 때문에, 파이프라인에서 이러한 스크립트를 제거할 수 있습니다.