<div id="readability-page-1" class="page"><section itemprop="text">
 
 <h2 id="node-25에서-vitest-4와-js-dom-691-연결하는-삽질기">Node 25에서 vitest 4와 js-dom 6.9.1 연결하는 삽질기</h2>

AI에게 vitest 초기 환경 설정을 맡겼더니 괴상한 설정 파일을 만들었다. 그냥 <code>vitest.config.ts</code> 파일에 <code>jest-dom</code>을 import 한 번 하면 될 것 같은데, 왜 이런 코드를 짰을까?

<h2 id="삽질의-시작">삽질의 시작</h2>

AI가 짠 <code>vitest.config.ts</code>를 확인해 보니, 4 가지 요소를 들고 있었다.

<div><pre><code>// vitest.config.ts

// 1) jest-dom matcher 등록
import * as matchers from '@testing-library/jest-dom/matchers';
import { expect } from 'vitest';
expect.extend(matchers);

// 2) 타입 augmentation
import type {} from '@testing-library/jest-dom/vitest';

// 3) localStorage 폴리필 (20 줄 짜리 Map-backed Storage 구현체)
// 특히 거지 같은 코드
if (typeof globalThis.localStorage?.getItem !== 'function') { ... }
</code></pre></div>

js-dom 라이브러리가 내부적으로 해야할 일을 왜 직접 구현해야 할까? localStorage 폴리필도 정말로 필요한 것일까? 설정은 항상 가장 단순해야 한다.

그래서 다 지워버렸다. 그러자 즉시 오류가 튀어나왔다.

<h2 id="현상--localstorageclear-is-not-a-function">현상 — <code>localStorage.clear is not a function</code></h2>

<code>vitest.config.ts</code> 을 다음과 같이 한 줄로 줄였다:

<div><pre><code>import '@testing-library/jest-dom/vitest';
</code></pre></div>

<code>yarn test:run</code> 결과:

<div><pre><code>FAIL src/features/Auth/lib/tests/cognito.test.ts
 TypeError: localStorage.clear is not a function
 src/features/Auth/lib/tests/cognito.test.ts:24:18
 22| describe('renewAccessTokens', () =&gt; {
 23| beforeEach(() =&gt; {
 24| localStorage.clear();
 ^
</code></pre></div>

동시에 다음 경고가 발생:

<div><pre><code>Warning: `--localstorage-file` was provided without a valid path
</code></pre></div>

localStorage에 clear 메서드가 없다고? js-dom이 만들어 주는 거 아니었나?

<h3 id="추적-1--vitest-config-확인">추적 1 — vitest config 확인</h3>

<code>vitest.config.ts</code> 는 이미 <code>environment: 'jsdom'</code> 이 설정돼 있었다. jsdom 환경이면 localStorage 가 정상 제공되어야 한다. 그러나 실패. 즉 jsdom 의 정상적인 초기화가 방해 받고 있었다.

<h3 id="추적-2--node-자체-동작-확인">추적 2 — Node 자체 동작 확인</h3>

그러면 Node 자체가 뭔가 localStorage 를 글로벌에 박고 있는 건 아닐까? Node 25 부터 Web Storage API 가 기본 활성화됐다는 소문이 있었는데, 그게 원인일 수 있다.

<div><pre><code>$ node --version
v25.9.0

$ node -e 'console.log(typeof localStorage, typeof localStorage?.clear)'
object undefined
(node:...) Warning: `--localstorage-file` was provided without a valid path
</code></pre></div>

테스트 환경이 아닌 Node 단독으로도 같은 증상과 같은 경고가 발생했다. <code>localStorage</code> 가 객체로 존재하지만 <code>clear</code> 가 없는 것이 문제였다.
이제 js-dom이 문제가 아니라는 사실이 명확해졌다. 문제는 <code>Node25</code>이다. Node가 localStorage를 만들다 말았다.

Node25는 대체 무슨 짓을 하고 있는 것일까?

<h3 id="추적-3--node-의-web-storage-cli-옵션">추적 3 — Node 의 Web Storage CLI 옵션</h3>

Node25가 뭔가 하고 있다면, CLI 옵션이 있을 것이다. <code>node --help</code> 를 검색해 보니 있었다.

<div><pre><code>$ node --help | grep -i storage
 --experimental-storage-inspection
 --localstorage-file=... file used to persist localStorage data
 --webstorage, --no-experimental-webstorage
 experimental Web Storage API
</code></pre></div>

help 검색 결과를 요약하자면, <code>--webstorage</code> — Node 25 의 <code>experimental Web Storage</code>가 있고, <code>--no-webstorage</code> 로 비활성 가능하다고 한다.

experimental 기능인데 왜 default로 떠 있는지는 모르겠지만, 그렇다고 한다.

<h3 id="추적-4----no-webstorage-효과-확인">추적 4 — <code>--no-webstorage</code> 효과 확인</h3>

experimental Web Storage를 비활성화 해 보았다.

<div><pre><code>$ node --no-webstorage -e 'console.log(typeof localStorage)'
ReferenceError: localStorage is not defined

$ NODE_OPTIONS=--no-webstorage yarn test:run cognito.test.ts
Tests 6 passed (6)
</code></pre></div>

Node 의 Web Storage 가 비활성되면 <code>localStorage</code> 자체가 없어지고, jsdom 이 정상적(?)으로 초기화 하여 테스트를 통과한다.

<h3 id="추적-5--node-24-에서-직접-확인">추적 5 — Node 24 에서 직접 확인</h3>

Node25가 하는 짓이 너무나 황당하여 좀 더 조사해 보니, Node 24는 experimental Web Storage를 활성화 하지 않는다고 한다. 그래서 Node 24 에서도 같은 코드를 돌려 보았다.

<div><pre><code>$ /Users/.../v24.15.0/bin/node -e 'console.log(typeof localStorage)'
ReferenceError: localStorage is not defined

# Node 24 + 폴리필 없이
$ PATH=.../v24.15.0/bin:$PATH yarn test:run
Test Files 11 passed (11)
Tests 68 passed (68)
</code></pre></div>

Node 24 에서는 <code>--experimental-webstorage</code> 가 opt-in (기본 OFF) 이라 <code>localStorage</code> 가 시작 시 undefined로 초기화 된다. 그래서 jsdom 이 localStorage를 정상적으로 만들어준다. 폴리필은 불필요하다. jsDom 자체가 일종의 폴리필이니까.

<h2 id="정리">정리</h2>

<ol>
 <li>Node 25 가 Web Storage 를 기본 활성 으로 승격 (Node 22 에선 opt-in 이었음).</li>
 <li>Node 25 실행 옵션에 <code>--no-webstorage</code> 를 안 넣으면 <code>clear</code>, <code>getItem</code> 등의 메서드가 빠진 <code>globalThis.localStorage</code>가 만들어짐 + warning.</li>
 <li>Vitest worker 의 jsdom env 가 <code>window.localStorage</code> 생성 시도.</li>
 <li>jsdom 은 <code>globalThis.localStorage</code> 가 이미 존재함을 확인하고, 폴리필을 넣지 않음. 하지만 <code>globalThis.localStorage</code>은 <code>window.localStorage</code> 의 모든 메서드를 실행할 수 없다.</li>
 <li>테스트가 <code>globalThis.localStorage.clear()</code> 실행 → clear 메서드가 없기 때문에 undefined 를 실행하려고 함 → TypeError 발생.</li>
</ol>

근본 원인은 Node가 불완전한 Web Storage 를 만들어서 jsDom의 기본 가정(localStorage가 없으면 localStorage를 만들자)과 충돌 하는 것이다. Node 25 에서 그 충돌이 기본값 이 됐다.

<h2 id="나의-선택은">나의 선택은?</h2>

Node 24를 쓰자.

<table>
 <thead>
 <tr>
 <th>옵션</th>
 <th>채택?</th>
 <th>이유</th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td>localStorage 폴리필을 <code>vitest.config.ts</code> 에 추가</td>
 <td>✗</td>
 <td>코드는 너저분하고 설명이 필요해진다</td>
 </tr>
 <tr>
 <td>package.json에 <code>engines: "&gt;=24 &lt;25"</code> + <code>.nvmrc=24</code> 만 유지</td>
 <td>✓</td>
 <td>Node 25 사용자는 명세 위반 — 명시적 실패가 가장 좋은 피드백</td>
 </tr>
 </tbody>
</table>

원래 vitest.config.ts 의 폴리필은 Node 25 사용자를 위해 있었던 것이기 때문에, 24 버전을 쓰면 폴리필은 불필요하다

<h2 id="그-외-vitests-v4-와-js-dom의-호환-문제">그 외… vitests v4 와 js-dom의 호환 문제</h2>

아래 코드를 넣어주지 않으면 jest-dom의 type을 불러올 수 없다. vitest 4를 js-dom이 연결하지 못 하기 때문이다.

<div><pre><code>import type {} from '@testing-library/jest-dom/vitest';
</code></pre></div>

vitest의 expect에서도 오류가 발생한다. expect 메서드가 jsDom의 rejects.toThrow와 연결되지 않기 때문이다. 그래서 아래와 같이 vitest의 expect를 강제로 확장해줘야 한다. vitest v4 이전에는 js-dom이 알아서 실행하는 코드였다.

<div><pre><code>import * as matchers from '@testing-library/jest-dom/matchers';
import { expect } from 'vitest';

expect.extend(matchers);
</code></pre></div>

<h2 id="완성본">완성본</h2>

불가피하게 거대한 주석을 남겨야 했다.

<div><pre><code>// issue #1. jest-dom 6.9.1이 vitest 4를 지원하지 않는 문제를 해결하기 위해
// vitest의 expect 가 js-dom의 matcher를 인식하도록 직접 등록한다.
// 이렇게 등록하지 않으면 expect.rejects.toThrow 가 깨진다
// jest-dom이 vitest4를 지원하기 시작하면
// `import '@testing-library/jest-dom/vitest'` 로 교체하라(정석)
import * as matchers from '@testing-library/jest-dom/matchers';
import { expect } from 'vitest';

expect.extend(matchers);

// issue #2. jest-dom의 모든 메서드를 vitest에서 사용할 수 있도록 타입을 불러온다
import type {} from '@testing-library/jest-dom/vitest';
</code></pre></div>

아무래도 이런 문제가 계속 발생하면 vitest 4를 버려야 할 것 같다.

<h2 id="참고">참고</h2>

<ul>
 <li>jest-dom 6.9.1 발행: 2025-10-01 (이후 정체).</li>
 <li>Vitest 4.0.0 발행: 2025-10-22.</li>
 <li>Node 25 의 <code>--webstorage</code> 기본 활성화는 Node 22 → 25 동안 opt-in → default 로 승격된 결과. <code>--no-webstorage</code> 로 비활성 가능.</li>
</ul>

EOD

20260504

 
 </section></div>

Never test

Node 25에서 vitest 4와 js-dom 6.9.1 연결하는 삽질기
AI에게 vitest 초기 환경 설정을 맡겼더니 괴상한 설정 파일을 만들었다. 그냥 vitest.config.ts 파일에 jest-dom을 import 한 번 하면 될 것 같은데, 왜 이런 코드를 짰을까?
삽질의 시작
AI가 짠 vitest.config.ts를 확인해 보니, 4 가지 요소를 들고 있었다.
// vitest.config.ts
// 1) jest-dom matcher 등록
import * as matchers from '@testing-library/jest-dom/matchers';
import { expect } from 'vitest';
expect.extend(matchers);
// 2) 타입 augmentation
import type {} from '@testing-library/jest-dom/vitest';
// 3) localStorage 폴리필 (20 줄 짜리 Map-backed Storage 구현체)
// 특히 거지 같은 코드
if (typeof globalThis.localStorage?.getItem !== 'function') { ... }
js-dom 라이브러리가 내부적으로 해야할 일을 왜 직접 구현해야 할까? localStorage 폴리필도 정말로 필요한 것일까? 설정은 항상 가장 단순해야 한다.
그래서 다 지워버렸다. 그러자 즉시 오류가 튀어나왔다.
현상 — localStorage.clear is not a function
vitest.config.ts 을 다음과 같이 한 줄로 줄였다:
import '@testing-library/jest-dom/vitest';
yarn test:run 결과:
FAIL src/features/Auth/lib/tests/cognito.test.ts
 TypeError: localStorage.clear is not a function
 src/features/Auth/lib/tests/cognito.test.ts:24:18
 22| describe('renewAccessTokens', () => {
 23| beforeEach(() => {
 24| localStorage.clear();
 ^
동시에 다음 경고가 발생:
Warning: `--localstorage-file` was provided without a valid path
localStorage에 clear 메서드가 없다고? js-dom이 만들어 주는 거 아니었나?
추적 1 — vitest config 확인
vitest.config.ts 는 이미 environment: 'jsdom' 이 설정돼 있었다. jsdom 환경이면 localStorage 가 정상 제공되어야 한다. 그러나 실패. 즉 jsdom 의 정상적인 초기화가 방해 받고 있었다.
추적 2 — Node 자체 동작 확인
그러면 Node 자체가 뭔가 localStorage 를 글로벌에 박고 있는 건 아닐까? Node 25 부터 Web Storage API 가 기본 활성화됐다는 소문이 있었는데, 그게 원인일 수 있다.
$ node --version
v25.9.0
$ node -e 'console.log(typeof localStorage, typeof localStorage?.clear)'
object undefined
(node:...) Warning: `--localstorage-file` was provided without a valid path
테스트 환경이 아닌 Node 단독으로도 같은 증상과 같은 경고가 발생했다. localStorage 가 객체로 존재하지만 clear 가 없는 것이 문제였다.
이제 js-dom이 문제가 아니라는 사실이 명확해졌다. 문제는 Node25이다. Node가 localStorage를 만들다 말았다.
Node25는 대체 무슨 짓을 하고 있는 것일까?
추적 3 — Node 의 Web Storage CLI 옵션
Node25가 뭔가 하고 있다면, CLI 옵션이 있을 것이다. node --help 를 검색해 보니 있었다.
$ node --help | grep -i storage
 --experimental-storage-inspection
 --localstorage-file=... file used to persist localStorage data
 --webstorage, --no-experimental-webstorage
 experimental Web Storage API
help 검색 결과를 요약하자면, --webstorage — Node 25 의 experimental Web Storage가 있고, --no-webstorage 로 비활성 가능하다고 한다.
experimental 기능인데 왜 default로 떠 있는지는 모르겠지만, 그렇다고 한다.
추적 4 — --no-webstorage 효과 확인
experimental Web Storage를 비활성화 해 보았다.
$ node --no-webstorage -e 'console.log(typeof localStorage)'
ReferenceError: localStorage is not defined
$ NODE_OPTIONS=--no-webstorage yarn test:run cognito.test.ts
Tests 6 passed (6)
Node 의 Web Storage 가 비활성되면 localStorage 자체가 없어지고, jsdom 이 정상적(?)으로 초기화 하여 테스트를 통과한다.
추적 5 — Node 24 에서 직접 확인
Node25가 하는 짓이 너무나 황당하여 좀 더 조사해 보니, Node 24는 experimental Web Storage를 활성화 하지 않는다고 한다. 그래서 Node 24 에서도 같은 코드를 돌려 보았다.
$ /Users/.../v24.15.0/bin/node -e 'console.log(typeof localStorage)'
ReferenceError: localStorage is not defined
# Node 24 + 폴리필 없이
$ PATH=.../v24.15.0/bin:$PATH yarn test:run
Test Files 11 passed (11)
Tests 68 passed (68)
Node 24 에서는 --experimental-webstorage 가 opt-in (기본 OFF) 이라 localStorage 가 시작 시 undefined로 초기화 된다. 그래서 jsdom 이 localStorage를 정상적으로 만들어준다. 폴리필은 불필요하다. jsDom 자체가 일종의 폴리필이니까.
정리
Node 25 가 Web Storage 를 기본 활성 으로 승격 (Node 22 에선 opt-in 이었음).
Node 25 실행 옵션에 --no-webstorage 를 안 넣으면 clear, getItem 등의 메서드가 빠진 globalThis.localStorage가 만들어짐 + warning.
Vitest worker 의 jsdom env 가 window.localStorage 생성 시도.
jsdom 은 globalThis.localStorage 가 이미 존재함을 확인하고, 폴리필을 넣지 않음. 하지만 globalThis.localStorage은 window.localStorage 의 모든 메서드를 실행할 수 없다.
테스트가 globalThis.localStorage.clear() 실행 → clear 메서드가 없기 때문에 undefined 를 실행하려고 함 → TypeError 발생.
근본 원인은 Node가 불완전한 Web Storage 를 만들어서 jsDom의 기본 가정(localStorage가 없으면 localStorage를 만들자)과 충돌 하는 것이다. Node 25 에서 그 충돌이 기본값 이 됐다.
나의 선택은?
Node 24를 쓰자.
옵션
 채택?
 이유
 
localStorage 폴리필을 vitest.config.ts 에 추가
 ✗
 코드는 너저분하고 설명이 필요해진다
 
package.json에 engines: ">=24 <25" + .nvmrc=24 만 유지
 ✓
 Node 25 사용자는 명세 위반 — 명시적 실패가 가장 좋은 피드백
 
원래 vitest.config.ts 의 폴리필은 Node 25 사용자를 위해 있었던 것이기 때문에, 24 버전을 쓰면 폴리필은 불필요하다
그 외… vitests v4 와 js-dom의 호환 문제
아래 코드를 넣어주지 않으면 jest-dom의 type을 불러올 수 없다. vitest 4를 js-dom이 연결하지 못 하기 때문이다.
import type {} from '@testing-library/jest-dom/vitest';
vitest의 expect에서도 오류가 발생한다. expect 메서드가 jsDom의 rejects.toThrow와 연결되지 않기 때문이다. 그래서 아래와 같이 vitest의 expect를 강제로 확장해줘야 한다. vitest v4 이전에는 js-dom이 알아서 실행하는 코드였다.
import * as matchers from '@testing-library/jest-dom/matchers';
import { expect } from 'vitest';
expect.extend(matchers);
완성본
불가피하게 거대한 주석을 남겨야 했다.
// issue #1. jest-dom 6.9.1이 vitest 4를 지원하지 않는 문제를 해결하기 위해
// vitest의 expect 가 js-dom의 matcher를 인식하도록 직접 등록한다.
// 이렇게 등록하지 않으면 expect.rejects.toThrow 가 깨진다
// jest-dom이 vitest4를 지원하기 시작하면
// `import '@testing-library/jest-dom/vitest'` 로 교체하라(정석)
import * as matchers from '@testing-library/jest-dom/matchers';
import { expect } from 'vitest';
expect.extend(matchers);
// issue #2. jest-dom의 모든 메서드를 vitest에서 사용할 수 있도록 타입을 불러온다
import type {} from '@testing-library/jest-dom/vitest';
아무래도 이런 문제가 계속 발생하면 vitest 4를 버려야 할 것 같다.
참고
jest-dom 6.9.1 발행: 2025-10-01 (이후 정체).
Vitest 4.0.0 발행: 2025-10-22.
Node 25 의 --webstorage 기본 활성화는 Node 22 → 25 동안 opt-in → default 로 승격된 결과. --no-webstorage 로 비활성 가능.
EOD
20260504

Node 25에서 vitest 4와 js-dom 6.9.1 연결하는 삽질기

댓글