import Test from "/snippets/cli/test.mdx";

Bun 은 빠르고 내장된 Jest 호환 테스트 러너를 제공합니다. 테스트는 Bun 런타임으로 실행되며 다음 기능을 지원합니다.

• TypeScript 및 JSX
• 라이프사이클 훅
• 스냅샷 테스트
• UI 및 DOM 테스트
• --watch 를 사용한 워치 모드
• --preload 를 사용한 스크립트 프리로딩

NOTE

Bun 은 Jest 와의 호환성을 목표로 하지만 모든 것이 구현된 것은 아닙니다. 호환성을 추적하려면 [이슈 트래킹](https://github.com/oven-sh/bun/issues/1825) 을 참조하세요.

테스트 실행

bun test

테스트는 Jest 와 유사한 API 를 사용하는 JavaScript 또는 TypeScript 로 작성됩니다. 전체 문서는 테스트 작성 을 참조하세요.

import { expect, test } from "bun:test";

test("2 + 2", () => {
  expect(2 + 2).toBe(4);
});

러너는 작업 디렉토리를 재귀적으로 검색하여 다음 패턴과 일치하는 파일을 찾습니다.

• *.test.{js|jsx|ts|tsx}
• *_test.{js|jsx|ts|tsx}
• *.spec.{js|jsx|ts|tsx}
• *_spec.{js|jsx|ts|tsx}

bun test 에 추가 위치 인수를 전달하여 실행할 테스트 파일 세트를 필터링할 수 있습니다. 경로가 필터 중 하나와 일치하는 테스트 파일이 실행됩니다. 일반적으로 이러한 필터는 파일 또는 디렉토리 이름입니다. glob 패턴은 아직 지원되지 않습니다.

bun test <filter> <filter> ...

테스트 이름 으로 필터링하려면 -t/--test-name-pattern 플래그를 사용하세요.

# 이름에 "addition" 이 포함된 모든 테스트 또는 테스트 스위트 실행
bun test --test-name-pattern addition

테스트 러너에서 특정 파일을 실행하려면 필터 이름과 구별하기 위해 경로가 ./ 또는 / 로 시작하는지 확인하세요.

bun test ./test/specific-file.test.ts

테스트 러너는 모든 테스트를 단일 프로세스에서 실행합니다. 모든 --preload 스크립트를 로드한 후 (자세한 내용은 라이프사이클 참조) 모든 테스트를 실행합니다. 테스트가 실패하면 테스트 러너는 0 이 아닌 종료 코드로 종료됩니다.

CI/CD 통합

bun test 는 다양한 CI/CD 통합을 지원합니다.

GitHub Actions

bun test 는 GitHub Actions 내에서 실행 중인지 자동으로 감지하고 콘솔에 직접 GitHub Actions 주석을 출력합니다.

워크플로우에서 bun 을 설치하고 bun test 를 실행하는 것 외에는 구성이 필요하지 않습니다.

GitHub Actions 워크플로우에서 bun 설치 방법

GitHub Actions 워크플로우에서 bun test 를 사용하려면 다음 단계를 추가하세요.

jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies # (프로젝트에 종속성이 있는 경우)
        run: bun install # 선호하는 경우 npm/yarn/pnpm 대신 사용 가능
      - name: Run tests
        run: bun test

그러면 GitHub Actions 주석을 받게 됩니다.

JUnit XML 리포트 (GitLab 등)

JUnit XML 리포터와 함께 bun test 를 사용하려면 --reporter-outfile 과 함께 --reporter=junit 을 사용할 수 있습니다.

bun test --reporter=junit --reporter-outfile=./bun.xml

이것은 평소와 같이 stdout/stderr 에 계속 출력하고 테스트 실행이 끝날 때 지정된 경로에 JUnit XML 리포트를 씁니다.

JUnit XML 은 CI/CD 파이프라인에서 테스트 결과를 보고하는 데 널리 사용되는 형식입니다.

타임아웃

--timeout 플래그를 사용하여 테스트당 타임아웃을 밀리초 단위로 지정하세요. 테스트가 타임아웃되면 실패로 표시됩니다. 기본값은 5000 입니다.

# 기본값은 5000 입니다
bun test --timeout 20

동시 테스트 실행

기본적으로 Bun 은 각 테스트 파일 내에서 모든 테스트를 순차적으로 실행합니다. 독립적인 테스트가 있는 테스트 스위트의 속도를 크게 높이기 위해 비동기 테스트를 병렬로 실행하도록 동시 실행을 활성화할 수 있습니다.

--concurrent 플래그

각 파일 내에서 모든 테스트를 동시에 실행하려면 --concurrent 플래그를 사용하세요.

bun test --concurrent

이 플래그가 활성화되면 test.serial 로 명시적으로 표시되지 않는 한 모든 테스트가 병렬로 실행됩니다.

--max-concurrency 플래그

--max-concurrency 플래그로 동시에 실행되는 최대 테스트 수를 제어하세요.

# 동시 테스트를 4 개로 제한
bun test --concurrent --max-concurrency 4

# 기본값: 20
bun test --concurrent

이것은 많은 동시 테스트를 실행할 때 리소스 고갈을 방지하는 데 도움이 됩니다. 기본값은 20 입니다.

test.concurrent

--concurrent 플래그를 사용하지 않더라도 개별 테스트가 동시에 실행되도록 표시하세요.

import { test, expect } from "bun:test";

// 이 테스트는 서로 병렬로 실행됩니다
test.concurrent("concurrent test 1", async () => {
  await fetch("/api/endpoint1");
  expect(true).toBe(true);
});

test.concurrent("concurrent test 2", async () => {
  await fetch("/api/endpoint2");
  expect(true).toBe(true);
});

// 이 테스트는 순차적으로 실행됩니다
test("sequential test", () => {
  expect(1 + 1).toBe(2);
});

test.serial

--concurrent 플래그가 활성화되어 있더라도 테스트가 순차적으로 실행되도록 강제하세요.

import { test, expect } from "bun:test";

let sharedState = 0;

// 이 테스트는 순서대로 실행되어야 합니다
test.serial("first serial test", () => {
  sharedState = 1;
  expect(sharedState).toBe(1);
});

test.serial("second serial test", () => {
  // 이전 테스트에 의존
  expect(sharedState).toBe(1);
  sharedState = 2;
});

// --concurrent 가 활성화되어 있으면 이 테스트는 동시에 실행될 수 있습니다
test("independent test", () => {
  expect(true).toBe(true);
});

// 테스트 한정자 체이닝
test.failing.each([1, 2, 3])("chained qualifiers %d", input => {
  expect(input).toBe(0); // 이 테스트는 각 입력에 대해 실패할 것으로 예상됨
});

테스트 다시 실행

--rerun-each 플래그를 사용하여 각 테스트를 여러 번 실행하세요. 이는 flaky 또는 비결정적 테스트 실패를 감지하는 데 유용합니다.

bun test --rerun-each 100

테스트 실행 순서 무작위화

--randomize 플래그를 사용하여 테스트를 무작위 순서로 실행하세요. 이는 공유 상태나 실행 순서에 의존하는 테스트를 감지하는 데 도움이 됩니다.

bun test --randomize

--randomize 를 사용할 때 무작위화에 사용된 seed 가 테스트 요약에 표시됩니다.

bun test --randomize

# ... 테스트 출력 ...
 --seed=12345
 2 pass
 8 fail
Ran 10 tests across 2 files. [50.00ms]

--seed 로 재현 가능한 무작위 순서

--seed 플래그를 사용하여 무작위화의 seed 를 지정하세요. 이를 통해 순서 의존 실패를 디버깅할 때 동일한 테스트 순서를 재현할 수 있습니다.

# 이전 무작위 실행 재현
bun test --seed 123456

--seed 플래그는 --randomize 를 의미하므로 둘 다 지정할 필요가 없습니다. 동일한 seed 값을 사용하면 항상 동일한 테스트 실행 순서가 생성되어 테스트 상호 의존성으로 인한 간헐적 실패를 디버깅하기 쉽습니다.

--bail 로 중단

사전 결정된 수의 테스트 실패 후 일찍 테스트 실행을 중단하려면 --bail 플래그를 사용하세요. 기본적으로 Bun 은 모든 테스트를 실행하고 모든 실패를 리포트하지만 때로는 CI 환경에서 CPU 사용량을 줄이기 위해 일찍 종료하는 것이 좋습니다.

# 1 회 실패 후 중단
bun test --bail

# 10 회 실패 후 중단
bun test --bail=10

워치 모드

bun run 과 유사하게 --watch 플래그를 bun test 에 전달하여 변경 사항을 감시하고 테스트를 다시 실행할 수 있습니다.

bun test --watch

라이프사이클 훅

Bun 은 다음 라이프사이클 훅을 지원합니다.

훅	설명
beforeAll	모든 테스트 전에 한 번 실행됩니다.
beforeEach	각 테스트 전에 실행됩니다.
afterEach	각 테스트 후에 실행됩니다.
afterAll	모든 테스트 후에 한 번 실행됩니다.

이러한 훅은 테스트 파일 내부 또는 --preload 플래그로 프리로드되는 별도 파일에서 정의할 수 있습니다.

bun test --preload ./setup.ts

전체 문서는 테스트 > 라이프사이클 을 참조하세요.

목

mock 함수로 목 함수를 생성하세요.

import { test, expect, mock } from "bun:test";
const random = mock(() => Math.random());

test("random", () => {
  const val = random();
  expect(val).toBeGreaterThan(0);
  expect(random).toHaveBeenCalled();
  expect(random).toHaveBeenCalledTimes(1);
});

또는 jest.fn() 을 사용할 수 있으며 동일하게 작동합니다.

import { test, expect, mock } from "bun:test"; 
import { test, expect, jest } from "bun:test"; 

const random = mock(() => Math.random()); 
const random = jest.fn(() => Math.random()); 

전체 문서는 테스트 > 목 을 참조하세요.

스냅샷 테스트

bun test 는 스냅샷을 지원합니다.

// toMatchSnapshot 사용 예
import { test, expect } from "bun:test";

test("snapshot", () => {
  expect({ a: 1 }).toMatchSnapshot();
});

스냅샷을 업데이트하려면 --update-snapshots 플래그를 사용하세요.

bun test --update-snapshots

전체 문서는 테스트 > 스냅샷 을 참조하세요.

UI 및 DOM 테스트

Bun 은 인기 있는 UI 테스트 라이브러리와 호환됩니다.

• HappyDOM
• DOM Testing Library
• React Testing Library

전체 문서는 테스트 > DOM 테스트 를 참조하세요.

성능

Bun 의 테스트 러너는 빠릅니다.

AI 에이전트 통합

AI 코딩 어시스턴트와 함께 Bun 의 테스트 러너를 사용할 때 가독성을 향상시키고 컨텍스트 노이즈를 줄이기 위해 더 조용한 출력을 활성화할 수 있습니다. 이 기능은 필수 실패 정보를 유지하면서 테스트 출력 상세도를 최소화합니다.

환경 변수

다음 환경 변수 중 하나를 설정하여 AI 친화적 출력을 활성화하세요.

• CLAUDECODE=1 - Claude Code 용
• REPL_ID=1 - Replit 용
• AGENT=1 - 일반 AI 에이전트 플래그

동작

AI 에이전트 환경이 감지되면.

• 테스트 실패만 세부적으로 표시됩니다
• 통과, 건너뛰기 및 todo 테스트 표시기가 숨겨집니다
• 요약 통계는 그대로 유지됩니다

# 예: Claude Code 를 위해 조용한 출력 활성화
CLAUDECODE=1 bun test

# 실패와 요약은 계속 표시되지만 상세한 통과 테스트 출력은 숨김

이 기능은 테스트 실패에 대한 가시성을 유지하면서 출력 상세도 축소가 컨텍스트 효율성을 향상시키는 AI 지원 개발 워크플로우에서 특히 유용합니다.