Bun 테스트 설정

bun test 는 bunfig.toml 파일과 명령줄 옵션을 통해 구성할 수 있습니다. 이 페이지에서는 bun test 에 사용 가능한 구성 옵션을 문서화합니다.

설정 파일

bunfig.toml 파일에 [test] 섹션을 추가하여 bun test 동작을 구성할 수 있습니다.

toml

[test]
# 옵션은 여기에 작성

테스트 검색

root

root 옵션은 프로젝트 루트에서 스캔하는 기본 동작을 재정의하는 테스트 검색을 위한 루트 디렉토리를 지정합니다.

toml

[test]
root = "src"  # src 디렉토리에서만 테스트 스캔

이 옵션은 다음을 원할 때 유용합니다.

특정 디렉토리로 테스트 검색 제한
프로젝트의 특정 부분을 테스트 스캔에서 제외
테스트를 특정 하위 디렉토리 구조로 구성

예시

toml

[test]
# src 디렉토리에서만 테스트 실행
root = "src"

# 특정 테스트 디렉토리에서 테스트 실행
root = "tests"

# 여러 특정 디렉토리에서 테스트 실행 (현재 지원되지 않음 - 대신 패턴 사용)
# root = ["src", "lib"]  # 이 구문은 지원되지 않음

프리로드 스크립트

preload 옵션을 사용하여 테스트 실행 전에 스크립트를 로드합니다.

toml

[test]
preload = ["./test-setup.ts", "./global-mocks.ts"]

이것은 명령줄에서 --preload 를 사용하는 것과 동일합니다.

bash

bun test --preload ./test-setup.ts --preload ./global-mocks.ts

일반적인 프리로드 사용 사례

// 전역 테스트 설정
import { beforeAll, afterAll } from "bun:test";

beforeAll(() => {
  // 테스트 데이터베이스 설정
  setupTestDatabase();
});

afterAll(() => {
  // 정리
  cleanupTestDatabase();
});

// 전역 목
import { mock } from "bun:test";

// 환경 변수 목
process.env.NODE_ENV = "test";
process.env.API_URL = "http://localhost:3001";

// 외부 종속성 목
mock.module("./external-api", () => ({
  fetchData: mock(() => Promise.resolve({ data: "test" })),
}));

타임아웃

기본 타임아웃

모든 테스트의 기본 타임아웃을 설정합니다.

toml

[test]
timeout = 10000  # 10 초 (기본값 5000ms)

이것은 개별 테스트 타임아웃으로 재정의되지 않는 한 모든 테스트에 적용됩니다.

// 이 테스트는 bunfig.toml 의 기본 타임아웃을 사용합니다
test("기본 타임아웃 사용", () => {
  // 테스트 구현
});

// 이 테스트는 기본 타임아웃을 재정의합니다
test("커스텀 타임아웃", () => {
  // 테스트 구현
}, 30000); // 30 초

리포터

JUnit 리포터

설정 파일에서 직접 JUnit 리포터 출력 파일 경로를 구성합니다.

toml

[test.reporter]
junit = "path/to/junit.xml"  # JUnit XML 리포트 출력 경로

이것은 --reporter=junit 및 --reporter-outfile CLI 플래그를 보완합니다.

bash

# 동등한 명령줄 사용법
bun test --reporter=junit --reporter-outfile=./junit.xml

여러 리포터

여러 리포터를 동시에 사용할 수 있습니다.

bash

# CLI 접근 방식
bun test --reporter=junit --reporter-outfile=./junit.xml

# 설정 파일 접근 방식

toml

[test.reporter]
junit = "./reports/junit.xml"

[test]
# 커버리지 리포팅도 활성화
coverage = true
coverageReporter = ["text", "lcov"]

메모리 사용량

smol 모드

테스트 러너를 위해 특별히 --smol 메모리 절약 모드를 활성화합니다.

toml

[test]
smol = true  # 테스트 실행 중 메모리 사용량 감소

이것은 명령줄에서 --smol 플래그를 사용하는 것과 동일합니다.

bash

bun test --smol

smol 모드는 다음을 통해 메모리 사용량을 줄입니다.

JavaScript 힙에 대한 메모리 사용량 감소
가비지 컬렉션 더 적극적으로 수행
가능한 경우 버퍼 크기 감소

이것은 다음에 유용합니다.

메모리가 제한된 CI 환경
상당한 메모리를 소비하는 대규모 테스트 스위트
메모리 제약이 있는 개발 환경

테스트 실행

concurrentTestGlob

동시 테스트 실행이 활성화된 상태로 glob 패턴과 일치하는 테스트 파일을 자동으로 실행합니다. 이는 테스트 스위트를 점진적으로 동시 실행으로 마이그레이션하거나 특정 테스트 유형을 동시에 실행할 때 유용합니다.

toml

[test]
concurrentTestGlob = "**/concurrent-*.test.ts"  # 이 패턴과 일치하는 파일을 동시에 실행

이 패턴과 일치하는 테스트 파일은 --concurrent 플래그가 전달된 것처럼 동작하여 해당 파일 내의 모든 테스트를 동시에 실행합니다. 이를 통해 다음을 수행할 수 있습니다.

테스트 스위트를 동시 실행으로 점진적으로 마이그레이션
단위 테스트는 순차적으로 유지하면서 통합 테스트는 동시에 실행
순차 실행이 필요한 테스트에서 빠른 동시 테스트 분리

--concurrent CLI 플래그가 지정되면 이 설정을 재정의하여 glob 패턴과 관계없이 모든 테스트가 동시에 실행됩니다.

randomize

숨겨진 종속성이 있는 테스트를 식별하기 위해 테스트를 무작위 순서로 실행합니다.

toml

[test]
randomize = true

seed

재현 가능한 무작위 테스트 순서를 위해 seed 를 지정합니다. randomize = true 가 필요합니다.

toml

[test]
randomize = true
seed = 2444615283

rerunEach

flaky 테스트를 식별하기 위해 각 테스트 파일을 여러 번 다시 실행합니다.

toml

[test]
rerunEach = 3

커버리지 옵션

기본 커버리지 설정

toml

[test]
# 기본적으로 커버리지 활성화
coverage = true

# 커버리지 리포터 설정
coverageReporter = ["text", "lcov"]

# 커버리지 출력 디렉토리 설정
coverageDir = "./coverage"

커버리지에서 테스트 파일 건너뛰기

테스트 패턴 (예: *.test.ts) 과 일치하는 파일을 커버리지 리포트에서 제외합니다.

toml

[test]
coverageSkipTestFiles = true  # 커버리지 리포트에서 테스트 파일 제외

커버리지 임계값

커버리지 임계값은 숫자 또는 특정 임계값이 있는 객체로 지정할 수 있습니다.

toml

[test]
# 간단한 임계값 - 줄, 함수, 문장에 적용
coverageThreshold = 0.8

# 상세 임계값
coverageThreshold = { lines = 0.9, functions = 0.8, statements = 0.85 }

이러한 임계값 중 하나를 설정하면 fail_on_low_coverage 가 활성화되어 커버리지가 임계값 미만일 경우 테스트 실행이 실패합니다.

임계값 예시

toml

[test]
# 전체적으로 90% 커버리지 요구
coverageThreshold = 0.9

# 다른 지표에 대해 다른 요구사항
coverageThreshold = {
  lines = 0.85,      # 85% 줄 커버리지
  functions = 0.90,  # 90% 함수 커버리지
  statements = 0.80  # 80% 문장 커버리지
}

커버리지 경로 무시 패턴

glob 패턴을 사용하여 특정 파일이나 파일 패턴을 커버리지 리포트에서 제외합니다.

toml

[test]
# 단일 패턴
coveragePathIgnorePatterns = "**/*.spec.ts"

# 여러 패턴
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "**/*.test.ts",
  "src/utils/**",
  "*.config.js",
  "generated/**",
  "vendor/**"
]

이러한 패턴 중 하나와 일치하는 파일은 커버리지 계산 및 리포팅에서 제외됩니다. 자세한 내용과 예시는 커버리지 문서 를 참조하세요.

일반적인 무시 패턴

toml

[test]
coveragePathIgnorePatterns = [
  # 테스트 파일
  "**/*.test.ts",
  "**/*.spec.ts",
  "**/*.e2e.ts",

  # 구성 파일
  "*.config.js",
  "*.config.ts",
  "webpack.config.*",
  "vite.config.*",

  # 빌드 출력
  "dist/**",
  "build/**",
  ".next/**",

  # 생성된 코드
  "generated/**",
  "**/*.generated.ts",

  # 벤더/서드파티
  "vendor/**",
  "third-party/**",

  # 테스트가 필요 없는 유틸리티
  "src/utils/constants.ts",
  "src/types/**"
]

소스맵 처리

내부적으로 Bun 은 모든 파일을 트랜스파일합니다. 즉 코드 커버리지는 리포트되기 전에 소스맵을 거쳐야 합니다. 이 동작을 옵트아웃할 수 있는 플래그로 노출하지만 트랜스파일 프로세스 중 Bun 이 코드를 이동시키고 변수 이름을 변경할 수 있으므로 혼란스러울 수 있습니다. 이 옵션은 주로 커버리지 문제 디버깅에 유용합니다.

toml

[test]
coverageIgnoreSourcemaps = true  # 커버리지 분석에 소스맵 사용 안 함

설정 상속

bun test 명령은 bunfig.toml 의 [install] 섹션에서 관련 네트워크 및 설치 구성 (레지스트리, cafile, prefer, exact 등) 을 상속합니다. 이는 테스트가 비공개 레지스트리와 상호작용하거나 테스트 실행 중 트리거되는 특정 설치 동작이 필요한 경우 중요합니다.

toml

[install]
# 이 설정은 bun test 에 의해 상속됨
registry = "https://npm.company.com/"
exact = true
prefer = "offline"

[test]
# 테스트별 구성
coverage = true
timeout = 10000

환경 변수

테스트 동작에 영향을 미치는 환경 변수를 구성에서 설정할 수도 있습니다.

toml

[env]
NODE_ENV = "test"
DATABASE_URL = "postgresql://localhost:5432/test_db"
LOG_LEVEL = "error"

[test]
coverage = true

전체 구성 예시

다음은 사용 가능한 모든 테스트 구성 옵션을 보여주는 포괄적인 예시입니다.

toml

[install]
# 테스트에서 상속하는 설치 설정
registry = "https://registry.npmjs.org/"
exact = true

[env]
# 테스트용 환경 변수
NODE_ENV = "test"
DATABASE_URL = "postgresql://localhost:5432/test_db"
API_URL = "http://localhost:3001"
LOG_LEVEL = "error"

[test]
# 테스트 검색
root = "src"
preload = ["./test-setup.ts", "./global-mocks.ts"]

# 실행 설정
timeout = 10000
smol = true

# 커버리지 구성
coverage = true
coverageReporter = ["text", "lcov"]
coverageDir = "./coverage"
coverageThreshold = { lines = 0.85, functions = 0.90, statements = 0.80 }
coverageSkipTestFiles = true
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "src/utils/**",
  "*.config.js",
  "generated/**"
]

# 고급 커버리지 설정
coverageIgnoreSourcemaps = false

# 리포터 구성
[test.reporter]
junit = "./reports/junit.xml"

CLI 재정의 동작

명령줄 옵션은 항상 구성 파일 설정을 재정의합니다.

toml

[test]
timeout = 5000
coverage = false

bash

# 이 CLI 플래그는 구성 파일을 재정의합니다
bun test --timeout 10000 --coverage
# timeout 은 10000ms 가 되고 coverage 는 활성화됩니다

조건부 구성

다른 환경에 대해 다른 구성을 사용할 수 있습니다.

toml

[test]
# 기본 테스트 구성
coverage = false
timeout = 5000

# CI 환경용 재정의
[test.ci]
coverage = true
coverageThreshold = 0.8
timeout = 30000

그런 다음 CI 에서.

bash

# CI 특정 설정 사용
bun test --config=ci

유효성 검사 및 문제 해결

잘못된 구성

Bun 은 잘못된 구성 옵션에 대해 경고합니다.

toml

[test]
invalidOption = true  # 이는 경고를 생성합니다

일반적인 구성 문제

경로 확인: 구성의 상대 경로는 구성 파일 위치를 기준으로 확인됩니다
패턴 매칭: Glob 패턴은 표준 glob 구문을 사용합니다
타입 불일치: 숫자 값이 문자열이어야 하는 경우를 제외하고 따옴표로 묶지 않았는지 확인하세요

toml

[test]
# 올바름
timeout = 10000

# 잘못됨 - 문자열로 처리됨
timeout = "10000"

구성 디버깅

사용 중인 구성을 확인하려면.

bash

# 유효한 구성 표시
bun test --dry-run

# 구성 로딩 확인을 위한 상세 출력
bun test --verbose

설정 파일 ​

테스트 검색 ​

root ​

예시 ​

프리로드 스크립트 ​

일반적인 프리로드 사용 사례 ​

타임아웃 ​

기본 타임아웃 ​

리포터 ​

JUnit 리포터 ​

여러 리포터 ​

메모리 사용량 ​

smol 모드 ​

테스트 실행 ​

concurrentTestGlob ​

randomize ​

seed ​

rerunEach ​

커버리지 옵션 ​

기본 커버리지 설정 ​

커버리지에서 테스트 파일 건너뛰기 ​

커버리지 임계값 ​

임계값 예시 ​

커버리지 경로 무시 패턴 ​

일반적인 무시 패턴 ​

소스맵 처리 ​

설정 상속 ​

환경 변수 ​

전체 구성 예시 ​

CLI 재정의 동작 ​

조건부 구성 ​

유효성 검사 및 문제 해결 ​

잘못된 구성 ​

일반적인 구성 문제 ​

구성 디버깅 ​

설정 파일

테스트 검색

root

예시

프리로드 스크립트

일반적인 프리로드 사용 사례

타임아웃

기본 타임아웃

리포터

JUnit 리포터

여러 리포터

메모리 사용량

smol 모드

테스트 실행

concurrentTestGlob

randomize

seed

rerunEach

커버리지 옵션

기본 커버리지 설정

커버리지에서 테스트 파일 건너뛰기

커버리지 임계값

임계값 예시

커버리지 경로 무시 패턴

일반적인 무시 패턴

소스맵 처리

설정 상속

환경 변수

전체 구성 예시

CLI 재정의 동작

조건부 구성

유효성 검사 및 문제 해결

잘못된 구성

일반적인 구성 문제

구성 디버깅