[빌드 에러] node_modules/@testing-library/jest-dom/types/jest.d.ts: - error TS2304: Cannot find name 'expect'. ReturnType<typeof expect.stringContaining>

문제상황

vite+ vitest + react 환경에서 npm run build 시 build 가 실패하는 문제가 발생했었습니다. 해당 에러 전문은 아래와 같이 jest 에 대한 참조와 expect 를 찾을 수 없다는 것이 문제였습니다. 

 

node_modules/@testing-library/jest-dom/types/jest.d.ts:1:23 - error TS2688: Cannot find type definition file for 'jest'.
1 /// <reference types="jest" />
                        ~~~~

node_modules/@testing-library/jest-dom/types/jest.d.ts:9:27 - error TS2304: Cannot find name 'expect'.     

9         ReturnType<typeof expect.stringContaining>,
                            ~~~~~~

 

원인 및 해결 방법

해당 문제를 일으키는 실질적인 원인은 setup.ts 파일 작성 시 import "@testing-library/jest-dom" 으로 잘못 표기할 때 문제가 발생합니다. 이는 jest 환경에서 사용하는 import 방식 입니다.

// 틀린 방식 ❌
// jest-dom adds custom jest matchers for asserting on DOM nodes.
// allows you to do things like:
// expect(element).toHaveTextContent(/react/i)
// learn more: https://github.com/testing-library/jest-dom
import '@testing-library/jest-dom';

 

vitest 를 사용하여 jest-dom  라이브러리를 사용하기 위해서는 추가로 /vitest 경로로 진입해주어야 합니다. 즉, 아래와 같이 명시해야 합니다. 이와 관련한 설정 방법은 jest-dom 공식 깃허브의 리드미에서 소개하고 있습니다(https://github.com/testing-library/jest-dom?tab=readme-ov-file#with-vitest).

// 옳은 방식 ⭕
// jest-dom adds custom jest matchers for asserting on DOM nodes.
// allows you to do things like:
// expect(element).toHaveTextContent(/react/i)
// learn more: https://github.com/testing-library/jest-dom
import '@testing-library/jest-dom/vitest';

 

나가는 말

많은 블로그에서 vitest 기준이 아닌 jest 기준으로 vitest 를 사용함에도 불구하고, 작성하는 것을 보았습니다. 저 또한 이것을 빠르게 환경 구축하는데 참고 하였죠. 그런데, 실제 적용해보니 빌드 실패가 발생 합니다. 여기서 한 번 생각해볼 수 있습니다. 어느 누군가가 올린 글을 참고해서 에러가 발생했다면, 그건 잘못따라해서가 아니라 애초에 틀린 방법이었을 가능성이 높다는 점입니다. 물론 그 포스트를 작성한 분들은 당시의 환경에서는 가능했겠으나, jest-dom 과 같은 라이브러리는 매번 기능을 개선하고 확장하면서 사용법이 달라질 수 있으니, 언제나 공식문서를 참고하는 습관을 들이는 것이 좋다고 봅니다.