VITEST_MAX_WORKERS 환경 변수는 설정의 fileParallelism: false 와 명령줄의 --maxWorkers=1 까지 이깁니다. 이를 모른 채 Vitest 워커를 줄이려고 전역에 넣었다가, 같은 DB 를 쓰는 e2e 테스트를 판마다 다른 자리에서 깨뜨렸습니다.
이 글은 한 대의 기계에서 Vitest 가 코어를 다 차지하는 문제를 재고, 워커 수를 낮추고, 그 과정에서 사고를 낸 기록입니다. 어떤 원리가 무엇을 예측했고, 실제 결과가 어디서 어긋났는지를 차례로 적었습니다. 결국 «직렬 설정은 스스로 변수를 지우고, 변수는 그 프로젝트 폴더 안에서만 건다»는 모양으로 끝났습니다.
먼저 밝혀 둘 것이 있습니다. 조건별 측정은 다른 세션이 함께 도는 중에 조건마다 1~5회만 잰 값이라 시간의 오차가 큽니다. 그리고 수치는 모두 실행 한 벌의 전후 비교입니다. 여러 세션이 겹칠 때 포화가 실제로 줄었는지는 아직 재지 않았습니다. 환경은 TypeScript 모노레포(NestJS API · 워커 · Next.js), M2 Pro 12코어 · 메모리 32GB 맥북, Vitest 4.1.10, Node 24.22.1 입니다.
Vitest 기본 워커 «코어−1»은 혼자 돌 때의 가정입니다
Vitest 의 기본 워커 수는 코어 수에서 하나를 뺀 값입니다. 12코어라면 11개입니다. 기계에 테스트 실행이 하나뿐이라면 합리적인 값입니다. 문제는 이 값이 실행마다 따로 정해진다는 데 있습니다.
실행끼리는 서로의 존재를 모르니, 두 벌이 겹치면 워커 22개가, 세 벌이 겹치면 33개가 12코어 위에 올라옵니다. 코어보다 많은 일을 올려 둔 이 상태를 오버서브스크립션(oversubscription)이라고 부릅니다. 제 기계에서는 AI 코딩 세션 십수 개가 함께 돌며 각자 테스트를 실행하고 있었으니, 이 상태가 드문 일은 아니었습니다.
이 원리에서 예측을 두 가지 끌어냈습니다. 워커를 낮추면 순간 부하의 정점이 내려갈 것입니다. 대신 해야 할 일의 총량은 그대로이니, 혼자 돌 때는 시간이 늘어날 것입니다. 저만 겪는 일도 아니었습니다. 작은 저장소에서 워커 11개에 AI 에이전트 3개가 겹쳐 macOS CPU 속도 제한이 55%까지 내려간 사례가 있고, 테스트 때문에 노트북이 다운되어 워커를 코어 절반으로 제한한 사례도 있습니다.
Vitest 가 코어를 얼마나 차지하는지 20초 간격으로 관측했습니다
조치에 앞서 문제의 크기부터 재고 싶었습니다. 그래서 테스트를 새로 돌리지 않고, 평소의 실행을 20초 간격으로 45표본 관측했습니다.
| Vitest 프로세스 수 | CPU 유휴 중앙값 | CPU 온도 | 기계 전체 전력 |
|---|---|---|---|
| 0개 | 75.3% | 61.7°C | 33.1W |
| 1~5개 | 48.1% | 67.1°C | 43.0W |
| 6개 이상 | 0.2% | 75.4°C | 66.0W |
45개 표본 중 14개에서 CPU 유휴가 5% 미만이었고, Vitest 프로세스는 최대 52개까지 올라갔습니다. 다만 발열 압력(thermal pressure)은 45개 전부 정상이었습니다. 온도 75~80°C 자체는 정상 범위여서 없앨 대상이 아니라고 판단했습니다. 줄이려는 것은 온도가 아니라 코어 포화였습니다.
첫 조치로 push 훅에서 무거운 테스트를 빼고 타입 검사만 남겼습니다. 전량 검사는 병합 직전에 한 번만 돕니다. 그 뒤 구간에서는 유휴 5% 미만 표본이 3개, 프로세스 최대치가 16개였습니다. 숫자만 보면 큰 효과처럼 보이지만, 두 구간은 테스트가 돌던 표본이 40개와 26개로 작업량이 달랐습니다. 이 차이를 전부 훅 변경의 효과로 볼 수는 없고, 최고 온도는 79.9°C 에서 81.3°C 로 오히려 높았습니다.
Vitest maxWorkers 를 줄이면 무엇이 달라지나
이번에는 같은 커밋에서 조건을 바꿔 가며 쟀습니다. 시간은 회차마다 크게 흔들려서 CPU초(모든 코어의 CPU 시간 합)를 주 지표로 삼았습니다. 규모는 백엔드 유닛 약 1만 건, 프런트 유닛 측정 묶음 약 2,600건(130파일, 프런트 전체의 일부)입니다.
| 조건 | 백엔드 유닛 | 프런트 유닛 |
|---|---|---|
| Node + Vitest 4 · 워커 11(기준) | 평균 50.3초(41.8~59.9) · 210 CPU초 · 5회 | 중앙값 33.0초(28.9~45.0) · 231 CPU초 · 5회 |
| Vitest 5.0.5 | 평균 39.1초 · 193 CPU초 · 2회 | 31.6 / 50.9초 · 227 / 233 CPU초 · 2회 |
| 워커 4 | 평균 39.2초(35.6~44.5) · 188 CPU초 · 3회 | 42.5 / 50.4초 · 192 / 205 CPU초 · 2회 |
| Bun 위 Vitest | 평균 30.6초 · 154 CPU초 · 3회 | 중앙값 29.1초(27.9~60.0) · 227 CPU초 · 3회 |
프런트 유닛은 워커 수를 더 촘촘히 나눠 129파일로 따로 비교했습니다. 회차는 앞의 표와 마찬가지로 조건마다 1~5회 범위이고, threads 풀은 한 번만 잰 값입니다. 측정 묶음이 다르므로 위 표의 값과 직접 견주지는 않습니다.
| 조건(129파일) | 시간 | CPU초 | 전력(기계 전체) |
|---|---|---|---|
| 워커 11개 | 38~41초 | 257~259 | 약 67W |
| 워커 6개 | 43~47초 | 244~248 | 약 67W |
| 워커 4개 | 45~49초 | 213~219 | 약 60W |
threads 풀 6개(1회) |
37초 | 216 | 약 68W |
첫 번째 어긋남은 백엔드 유닛에서 나왔습니다. 시간이 늘 것이라고 예측했는데, 워커를 4개로 줄이니 평균 시간도 CPU초도 함께 줄었습니다. 코어를 다 쓰는 쪽이 오히려 더 느렸던 것입니다. 이 측정만으로 원인까지 말할 수는 없고, 회차도 5회와 3회뿐이니 시간 차이는 조심스럽게 읽어야 합니다.
프런트 유닛은 예측대로였습니다. 워커를 11개에서 4개로 줄이면 CPU 는 11~18% 줄고, 혼자 돌 때 시간은 측정 묶음에 따라 10~53% 늘었습니다. 회차가 적어 시간의 폭이 큽니다. 묶음별로 나누면 130파일 묶음은 시간 +29~53%, CPU −11~−17%이고, 129파일 묶음은 시간 +10~29%, CPU −15~−18%입니다. 129파일 묶음에서 전력은 약 67W 에서 약 60W 로 약 10% 내려갔습니다.
전력은 내려갔지만 시간이 늘어나니, 129파일 묶음의 전력과 시간으로 어림하면 총 에너지는 거의 같습니다. 즉 워커 제한은 일을 덜 하게 만드는 조치가 아니라 순간 부하를 낮추는 조치라는 생각이 들었습니다. 전력은 기계 전체의 값이고 팬 속도는 재지 못했으니, 체감까지 좋아졌다고 말할 근거는 없습니다.
6개는 전력이 11개와 같아서 효과가 약했습니다. 세 벌이 겹쳐도 12코어 안에 드는 4개를 골랐습니다. 이 값 하나로 실행 1회의 프로세스 수는 13개에서 6개로 줄었습니다(30파일, 두 번 실측). 여기까지는 순조로웠습니다. 사고는 이 숫자를 확인하고 끝났다고 여긴 직후에 났습니다.
VITEST_MAX_WORKERS 전역 설정이 직렬 테스트를 깼습니다
~/.zshenv 에 export VITEST_MAX_WORKERS=4 를 넣고, 유닛 30파일에서 13개가 6개로 줄어든 것을 확인한 뒤 끝냈다고 봤습니다. 제 분석 메모에는 «e2e 는 fileParallelism: false 라 영향 없다»고 적혀 있었습니다. 돌이켜 생각해보면 이것은 재지 않은 추론이었습니다.
e2e 는 실제 MySQL 을 쓰고, 약 200파일 수천 건을 샤드로 나눠 돌립니다. 변수를 넣은 뒤부터 이 e2e 가 판마다 다른 자리에서 빨개졌습니다. 테스트 데이터의 행이 0개이거나, 정리 단계에서 교착이 나거나, 401 이 돌아오거나, FK 제약에 걸렸습니다. 하나하나가 코드 결함처럼 보이는 증상이었습니다.
원인이 확정된 것은 약 40분 뒤입니다. 원인을 좁힌 것은 제가 아니라 다른 세션이었습니다. 같은 두 파일이 변수가 있으면 5회 중 5회 빨강, env -u VITEST_MAX_WORKERS 로 지우면 5회 중 5회 초록이었습니다. 애석하게도 제가 넣은 한 줄이 원인이었습니다.
왜 fileParallelism: false 가 졌나
Vitest 의 resolveConfig 는 워커 수를 두 번 정합니다. 4.1.10 과 5.0.5 의 소스에서 둘 다 같은 구조인 것을 확인했습니다.
# resolveConfig 안의 순서 (소스를 읽고 요약한 것)
1. fileParallelism: false 이면 → 워커 수를 1 로 정한다
2. 같은 함수 뒤쪽에서 process.env.VITEST_MAX_WORKERS 가 있으면 → 그 값으로 다시 덮어쓴다
결과: VITEST_MAX_WORKERS=4 이면 fileParallelism: false 도, --maxWorkers=1 도 4 로 덮인다그래서 직렬로 돌아야 할, 같은 DB 를 쓰는 파일들이 동시에 돌았습니다. 명령줄이 환경 변수보다 앞선다는 흔한 설정 우선순위와도 다른 동작입니다.
처방은 직렬 설정 파일에서 VITEST_MAX_WORKERS 를 지우는 한 줄입니다
Vitest 가 설정 파일을 읽는 시점은 그 덮어쓰기보다 앞섭니다. 그러니 직렬 설정 파일이 읽힐 때 변수를 지우면 듣습니다.
import { defineConfig } from 'vitest/config';
delete process.env.VITEST_MAX_WORKERS;
export default defineConfig({
test: {
fileParallelism: false,
},
});검증은 이번에는 방법을 바꿨습니다. 처방 뒤 변수를 일부러 켠 채로 그 빨갛던 파일들과 DB 테스트를 다시 돌려 초록을 확인했습니다. 실패가 나던 조건을 그대로 둔 채로 재야, 고쳤다는 말에 의미가 있다는 생각이 들었습니다.
둘째 실수: 전역 환경 변수의 폭발 반경을 재지 않았습니다
부끄럽지만 실수가 하나 더 있습니다. 처방을 넣고 변수를 되살린 뒤에야 다른 레포를 훑어 보았더니, 같은 기계의 다른 프로젝트들에도 fileParallelism: false 가 있었습니다. 실제로 깨졌는지는 확인하지 못했습니다. ~/.zshenv 는 그 기계의 모든 셸에 닿는데, 저는 한 레포의 문제를 풀면서 그 범위를 처음에 재지 않은 것입니다.
최종 형태는 변수를 그 프로젝트 폴더 안에서만 거는 것입니다.
case "$PWD/" in
"$HOME"/work/my-monorepo/*|"$HOME"/work/my-monorepo-*) export VITEST_MAX_WORKERS=4 ;;
esac그래도 옛 브랜치의 빈틈은 남습니다. 처방이 들어가기 전의 커밋에서 손으로 e2e 를 돌리면 다시 깨지는데, 적용 시점의 워크트리 다수가 그런 상태였습니다. 레포 밖 실행 스크립트 한 곳에도 unset 을 넣었지만 전부 막지는 못합니다.
이 사고에서 남긴 세 가지
확인 방법이 그 오류를 잡을 수 없으면 확인이 아닙니다. 저는 유닛으로 재고 e2e 를 추론했습니다. 프로세스 수가 13개에서 6개로 줄었다는 측정은 직렬 실행이 깨지는지를 원리적으로 볼 수 없습니다. Tailwind 가 주석까지 읽는다는 것을 뒤늦게 안 글에서도 증명의 범위를 한 칸 넓혀 읽은 일을 적었는데, 같은 모양의 실수를 또 한 셈입니다.
전역 환경 변수는 변경 전에 폭발 반경을 먼저 잽니다. 바꾸는 줄은 하나여도 닿는 곳은 그 기계의 모든 프로젝트입니다.
추론은 추론이라고 적어도, 그 위에 조치를 올리면 사고가 납니다. 메모에 재지 않은 문장 하나가 있었고, 그 위에 전역 설정을 올렸습니다.
맥미니에는 같은 값이 아니라 다른 값을 걸었습니다
보조 맥미니는 코어 10개에 메모리 16GB 이고, AI 세션 2개와 병합 직전 전량 검사가 함께 삽니다. 코어 수가 다르니 4를 그대로 옮길 이유가 없었습니다. 세 벌이 겹쳐도 코어 안에 드는 3개를 세션 폴더에만 걸었고, 30파일 기준 프로세스 수는 12개에서 6개로 줄었습니다.
전량 검사에는 제한을 걸지 않았습니다. 이 검사는 칸 하나로 차례로 돌아 세션끼리 겹치지 않고, 전체 시간을 프런트 유닛(약 97초)이 정합니다. 이 검사는 ssh 로 홈 폴더에서 시작하므로 PWD 조건에도 걸리지 않습니다. 최근 6번의 유닛 단계에서 메모리 압력은 전부 정상이었고 남은 메모리는 최소 4.8GB 였습니다. 다만 10초 간격 표본이라 순간 최대치는 놓쳤을 수 있습니다.
검토하고 쓰지 않은 것들
Bun 위 Vitest는 테스트를 고치지 않고도 실패 0건으로 돌았고, 백엔드 유닛은 평균 시간이 50.3초에서 30.6초로(39% 감소), CPU초가 210에서 154로(27% 감소) 줄었습니다. 프런트 유닛의 CPU초는 거의 그대로였습니다.
그런데 운영은 Node 라 최종 검증을 또 돌려야 하고, 같은 검사 111개 중 17개가 Node 와 다르게 나왔습니다(JSON 오류 문구, Worker resourceLimits 무시, 파일 형식 판정, 압축 바이트, 오류 문구 8종). «Bun 에서 통과해도 Node 운영에서 샐 수 있는» 방향이 위험해 보여 보류했습니다. Bun 전환 자체를 검토한 글은 따로 있고, 여기서는 테스트 실행에 한정한 판단입니다.
bun test 전환은 더 멀었습니다. 백엔드는 21파일이 불러오기에 실패하고 66건이 실패했는데, 오류 줄 111개 중 110개가 vi.hoisted · vi.stubEnv 처럼 없는 기능 때문이었습니다. 프런트는 측정 묶음 약 2,600건 중 1,086건이 실패했고, 그중 1,023건은 document 가 없어서였습니다. 다른 도구(Jest, node:test, Rstest, vp test)는 찾아본 범위에서 Vitest 를 확실히 앞서는 것이 없었습니다. 직접 돌려 본 대안은 Bun 뿐입니다.
요령도 이미 몇 가지 해 둔 상태였습니다. 파일 격리를 끄는 일은 백엔드에서는 파일이 남기는 상태를 정적으로 보고 자동 분류하지만, 프런트에서는 컴포넌트 8파일 중 7개가 깨지고 9초가 109초가 되어 기각했습니다. DOM 이 필요 없는 테스트는 node 환경으로 옮겼고, happy-dom 교체는 기각했습니다. e2e 샤드는 직렬 611초를 샤드 3개 289초로 줄였지만, 전체 CPU 를 줄인다는 근거는 없습니다.
Vitest 5.0.5 로도 올렸습니다. 코드 변경 없이 유닛 · e2e · DB 테스트 전량(합쳐 2만 건이 넘습니다)이 통과했고, 5.1.0 은 나온 지 얼마 안 되어 측정한 5.0.5 로 고정했습니다. 바뀌는 기본값은 하나씩 대조했습니다.
clearMocks기본값이 true 가 됩니다. 매 테스트 전에 호출 기록만 지우고 구현은 남깁니다.- 파일 끝의
vi.restoreAllMocks()는 그대로 둡니다. 격리를 끈 구성의 전제이기 때문입니다. - vite 가 필수 peer 가 되고,
-t구분자는' > '입니다. - await 없는 resolves/rejects 는 실패로 던집니다.
절차에서는 두 가지를 지켰습니다. 파일 수를 대조했고(«전부 통과»는 테스트를 빠짐없이 모았을 때만 의미가 있습니다), 다른 변경과 묶지 않고 혼자 전량 검사를 돌렸습니다(빨개졌을 때 원인을 가르기 위해서입니다). 효과는 크게 기대하지 않습니다. 공식 발표도 forks + jsdom + 격리 조합은 Vitest 4.1 대비 ±3% 이내라고 하고, 맥미니의 유닛 단계는 102~103초가 98~100초가 되었습니다(3회씩, 합친 코드가 달라 전부 버전을 올린 효과는 아닙니다). 앞의 표에서 백엔드 유닛은 평균 39.1초 · 193 CPU초로 더 크게 줄었지만 2회뿐인 값이라, 이것을 버전 효과로 단정하지는 않습니다.
정리: 줄인 것과 아직 모르는 것
Vitest 워커 제한으로 얻은 것은 실행 한 벌의 프로세스 수와 순간 부하입니다. 백엔드 유닛은 시간도 함께 줄었고, 프런트 유닛은 혼자 돌 때의 시간을 내주고 CPU 와 전력을 낮췄습니다. 어림으로 총 에너지는 거의 같으니 일이 줄어든 것은 아닙니다.
그래서 이 글의 결론은 조심스럽습니다. 여러 세션이 겹칠 때 포화가 실제로 줄었는지는 미측정입니다. 세 벌이 12코어 안에 든다는 것은 산수이지 측정이 아닙니다. 그리고 이 제한은 e2e · DB 테스트와 Jest 에는 듣지 않습니다. 이 둘의 겹침은 무거운 테스트를 줄 세워 막는 영역입니다.
돌이켜 생각해보면 숫자를 재는 일보다 어려웠던 것은, 잰 숫자가 어디까지를 말해 주는지 지키는 일이었습니다. 유닛의 13이 6이 된 것은 분명한 사실이었지만, 그 사실은 e2e 에 대해 아무것도 말해 주지 않았습니다. 전역에 무언가를 넣기 전에는 그것이 닿는 곳부터 재야겠다고 다짐했습니다.