매처 확장하기

Vitest는 Chai와 Jest 모두와 호환되므로, 선호하는 대로 chai.use API 또는 expect.extend 중 하나를 사용하여 매처를 확장할 수 있습니다.

이 가이드에서는 expect.extend를 사용하여 매처를 확장하는 방법을 살펴봅니다. Chai의 API에 관심이 있다면 해당 가이드를 확인하세요.

기본 매처를 확장하려면 매처를 포함하는 객체를 expect.extend에 전달하여 호출합니다.

expect.extend({
  toBeFoo(received, expected) {
    const { isNot } = this;
    return {
      // `isNot` 값에 따라 "pass"를 변경하지 마세요. Vitest가 자동으로 처리합니다.
      pass: received === 'foo',
      message: () => `${received} is${isNot ? ' not' : ''} foo`,
    };
  },
});

TypeScript를 사용하는 경우, 다음 코드를 사용하여 앰비언트 선언 파일(예: vitest.d.ts)에서 기본 Assertion 인터페이스를 확장할 수 있습니다.

3.2.0+ 3.0.0+

import 'vitest';

interface CustomMatchers<R = unknown> {
  toBeFoo: () => R;
}

declare module 'vitest' {
  interface Matchers<T = any> extends CustomMatchers<T> {}
}

import 'vitest';

interface CustomMatchers<R = unknown> {
  toBeFoo: () => R;
}

declare module 'vitest' {
  interface Assertion<T = any> extends CustomMatchers<T> {}
  interface AsymmetricMatchersContaining extends CustomMatchers {}
}

TIP

Vitest 3.2부터는 Matchers 인터페이스를 확장하여 expect.extend, expect().*, expect.* 메서드에서 동시에 타입 안전한 어설션을 사용할 수 있습니다. 이전에는 각각에 대해 별도의 인터페이스를 정의해야 했습니다.

WARNING

앰비언트 선언 파일을 tsconfig.json에 포함하는 것을 잊지 마세요.

매처의 반환 값은 다음 인터페이스와 호환되어야 합니다.

interface ExpectationResult {
  pass: boolean;
  message: () => string;
  // 이 값들을 제공하면, 매처가 통과하지 못했을 때 자동으로 diff에 표시되므로,
  // 직접 diff를 출력할 필요가 없습니다.
  actual?: unknown;
  expected?: unknown;
}

WARNING

비동기 매처를 생성하는 경우, 테스트 자체에서 결과를 await하는 것을 잊지 마세요(await expect('foo').toBeFoo()):

expect.extend({
  async toBeAsyncAssertion() {
    // ...
  },
});

await expect().toBeAsyncAssertion();

매처 함수의 첫 번째 인수는 수신된 값(expect(received) 내부에 있는 값)입니다. 나머지 인수는 매처에 직접 전달됩니다.

매처 함수는 다음 속성들을 통해 this 컨텍스트에 접근할 수 있습니다.

`isNot`

매처가 not(expect(received).not.toBeFoo())과 함께 호출된 경우 true를 반환합니다.

`promise`

매처가 resolved 또는 rejected와 함께 호출된 경우, 이 값은 해당 수정자의 이름을 포함합니다. 그렇지 않으면 빈 문자열입니다.

`equals`

이것은 두 값을 비교할 수 있는 유틸리티 함수입니다. 값이 같으면 true를 반환하고, 그렇지 않으면 false를 반환합니다. 이 함수는 거의 모든 매처에서 내부적으로 사용됩니다. 기본적으로 비대칭 매처를 포함하는 객체를 지원합니다.

`utils`

이것은 메시지를 표시하는 데 사용할 수 있는 유틸리티 함수 세트를 포함합니다.

this 컨텍스트는 현재 테스트에 대한 정보도 포함합니다. expect.getState()를 호출하여 가져올 수도 있습니다. 가장 유용한 속성은 다음과 같습니다.

`currentTestName`

현재 테스트의 전체 이름(describe 블록 포함).

`testPath`

현재 테스트 파일의 경로.

매처 확장하기 ​

isNot ​

promise ​

equals ​

utils ​

currentTestName ​

testPath ​