Jest 객체

Jest 객체 (The Jest Object)

jest 객체는 모든 테스트 파일 안에서 자동으로 스코프에 들어와요. jest 객체의 메서드들은 mock을 만들고 Jest의 전반적인 동작을 제어하는 데 쓰여요. import { jest } from '@jest/globals'로 명시적으로 import 할 수도 있어요.

출처: Jest 공식 문서 - The Jest Object

Methods 개요

Mock Modules (모듈 mock)

• jest.disableAutomock(), jest.enableAutomock()
• jest.createMockFromModule(moduleName)
• jest.mock(moduleName, factory, options)
• jest.mocked(source, options?), jest.unmock(moduleName), jest.deepUnmock(moduleName)
• jest.doMock(moduleName, factory, options), jest.dontMock(moduleName)
• jest.setMock(moduleName, moduleExports)
• jest.requireActual(moduleName), jest.requireMock(moduleName)
• jest.onGenerateMock(cb)
• jest.resetModules(), jest.isolateModules(fn), jest.isolateModulesAsync(fn)

Mock Functions (mock 함수)

• jest.fn(implementation?), jest.isMockFunction(fn)
• jest.replaceProperty(object, propertyKey, value)
• jest.spyOn(object, methodName), jest.spyOn(object, methodName, accessType?)
• jest.clearAllMocks(), jest.resetAllMocks(), jest.restoreAllMocks()

Fake Timers (가짜 타이머)

• jest.useFakeTimers(fakeTimersConfig?), jest.useRealTimers()
• jest.runAllTicks(), jest.runAllTimers(), jest.runAllTimersAsync(), jest.runAllImmediates()
• jest.advanceTimersByTime(msToRun), jest.advanceTimersByTimeAsync(msToRun)
• jest.runOnlyPendingTimers(), jest.runOnlyPendingTimersAsync()
• jest.advanceTimersToNextTimer(steps), jest.advanceTimersToNextTimerAsync(steps)
• jest.advanceTimersToNextFrame(), jest.clearAllTimers()
• jest.getTimerCount(), jest.now()
• jest.setSystemTime(now?: number | Date | Temporal.Instant | Temporal.ZonedDateTime)
• jest.setTimerTickMode(mode), jest.getRealSystemTime()

Misc (기타)

• jest.getSeed(), jest.isEnvironmentTornDown()
• jest.retryTimes(numRetries, options?), jest.setTimeout(timeout)

Mock Modules

jest.disableAutomock()

모듈 로더의 자동 mocking을 비활성화해요. 효과를 보려면 automock 구성 옵션으로 자동 mocking을 켜야 해요. babel-jest를 쓸 때 disableAutomock() 호출은 코드 블록 맨 위로 자동 호이스팅되는데, 그걸 피하려면 autoMockOff()를 써요. 체이닝을 위해 jest 객체를 반환해요.

jest.enableAutomock()

모듈 로더의 자동 mocking을 활성화해요. babel-jest에선 자동 호이스팅되는데, 피하려면 autoMockOn을 써요. 체이닝을 위해 jest 객체를 반환해요.

jest.createMockFromModule(moduleName)

자동 mock을 만들 때 타입별 동작이 달라요.

• Class: 원래 클래스의 인터페이스를 유지하고 모든 멤버 함수·프로퍼티를 mock해요.
• Object: 깊이 복제한 객체를 만들고 키는 유지, 값은 mock돼요.
• Array: 원본을 무시한 빈 배열을 만들어요.
• Primitives: 원래 프로퍼티와 같은 원시 값을 가진 프로퍼티를 만들어요.

jest.mock(moduleName, factory, options)

모듈을 mock해요. factory로 반환값을 지정할 수 있어요.

jest.mock('../moduleName', () => {
  return jest.fn(() => 42);
});

const moduleName = require('../moduleName');
moduleName(); // Will return '42';

jest.mock으로 mock된 모듈은 그 호출이 있는 파일에서만 mock돼요. 다른 파일에서 그 모듈을 import하면 (mock 파일이 테스트보다 뒤에 실행되더라도) 원래 구현을 받아요.

jest.unmock(moduleName)

require()에서 지정한 모듈의 mock 버전을 절대 반환하지 않도록 해요 (항상 실제 모듈을 반환). 특정 테스트가 검증하려는 모듈을 지정할 때 가장 흔히 쓰여요.

jest.deepUnmock(moduleName)

지정한 모듈과 그 의존성까지 mock 버전을 반환하지 않도록 해요.

jest.doMock(moduleName, factory, options)

jest.resetModules()와 함께 쓰면 테스트마다 서로 다른 mock을 주입할 수 있어요. jest.mock과 달리 호이스팅되지 않고, 동적 import와 함께 써야 해요.

beforeEach(() => {
  jest.resetModules();
});

test('moduleName 1', () => {
  jest.doMock('../moduleName', () => {
    return jest.fn(() => 1);
  });
  const moduleName = require('../moduleName');
  expect(moduleName()).toBe(1);
});

jest.setMock(moduleName, moduleExports)

지정 모듈에 대해 모듈 시스템이 반환할 mock 객체를 명시적으로 공급해요. 흔치 않은 상황에서 mock 모듈 레지스트리의 슬롯을 수동으로 채울 때 써요. jest.mock()을 쓰는 것이 권장돼요.

jest.requireActual(moduleName)

일반적으로 require해야 하는지 검사하는 걸 모두 우회하고 mock이 아닌 실제 모듈을 반환해요.

jest.requireMock(moduleName)

실제 모듈 대신 mock 모듈을 반환해요.

jest.onGenerateMock(cb)

Jest가 모듈용 mock을 생성할 때마다 콜백을 호출해요. 콜백은 modulePath: string(mock 대상 모듈의 절대 경로)과 moduleMock: T(생성된 mock 객체)를 받아요. 이 객체를 반환 전에 수정하거나 교체할 수 있어요. __mocks__ 폴더 mock이나 jest.mock('...', () => {...}) 같은 수동 mock에는 호출되지 않아요.

jest.resetModules()

모듈 레지스트리를 재설정해요. 테스트 사이에 require 캐시를 비우고 싶을 때 써요.

beforeEach(() => {
  jest.resetModules();
});

test('works', () => {
  const sum = require('../sum');
});

test('works too', () => {
  const sum = require('../sum'); // 이전 테스트와 다른 sum 복사본
});

jest.isolateModules(fn)

콜백 안에서만 별도의 모듈 레지스트리를 사용해요.

let myModule;
jest.isolateModules(() => {
  myModule = require('myModule');
});
const otherCopyOfMyModule = require('myModule');

jest.isolateModulesAsync(fn)는 비동기 콜백용이에요. 완료를 await로 기다려야 해요.

let myModule;
await jest.isolateModulesAsync(async () => {
  myModule = await import('myModule');
  // do async stuff here
});
const otherCopyOfMyModule = await import('myModule');

Mock Functions

jest.fn(implementation?)

mock 함수를 만들어요. TypeScript 사용법은 Mock Functions 페이지를 참고해요.

jest.isMockFunction(fn)

주어진 함수가 mock 함수인지 판별해요.

jest.replaceProperty(object, propertyKey, value)

object[propertyKey]를 value로 교체해요. 프로퍼티는 반드시 이미 존재해야 해요. getter/setter로 정의된 프로퍼티를 mock하려면 jest.spyOn(object, methodName, accessType)을, 함수를 mock하려면 jest.spyOn(object, methodName)을 써요. jest.replaceProperty로 교체한 프로퍼티는 jest.restoreAllMocks로 원래 값으로 복원할 수 있어요.

jest.spyOn(object, methodName)

jest.fn과 유사한 mock 함수를 만들고 object[methodName]에 대한 호출도 추적해요. 기본적으로 jest.spyOn은 스파이 대상 메서드를 실행해요 (대부분의 다른 테스트 라이브러리와 다른 동작). 원래 함수를 덮어쓰려면 .mockImplementation(() => ...)을 사용해요. jest.restoreAllMocks를 afterEach에서 호출하면 초기 상태로 복원해요.

accessType 인자('get'/'set')를 주면 getter/setter를 스파이할 수 있어요 (Jest 22.1.0+).

jest.clearAllMocks() / resetAllMocks() / restoreAllMocks()

각각 모든 mock의 mockClear(), mockReset(), mockRestore()를 호출해요.

Fake Timers

• jest.useFakeTimers() — 타이머를 가짜 구현으로 교체. doNotFake 배열로 제외할 API를, legacyFakeTimers로 구식 구현을 지정할 수 있어요.
• jest.useRealTimers() — 전역 date, performance, time, timer API의 원래 구현을 복원. afterEach에서 쓰면 좋아요.
• jest.runAllTicks(), jest.runAllTimers() — 모든 타이머 실행.
• jest.runAllImmediates() — 모든 immediate 실행.
• jest.advanceTimersByTime(msToRun) — 시간을 지정 밀리초만큼 앞당겨요.
• jest.runOnlyPendingTimers() — 현재 대기 중인 타이머만 실행.
• jest.advanceTimersToNextTimer(steps) — 다음 타이머까지 앞당겨요.
• jest.setSystemTime(now) — 가짜 시계의 시스템 시간을 설정해요.
• jest.setTimerTickMode(mode) — manual(명시 호출로만 진행), nextAsync(이벤트 루프를 끊고 다음 타이머 실행), interval(advanceTimeDelta, 기본 20)을 지정해요.
• jest.getRealSystemTime() — 가짜 시계 대신 실제 시스템 시간을 반환해요.

Misc

• jest.getSeed() — 현재 랜덤 시드를 반환해요.
• jest.isEnvironmentTornDown() — 테스트 환경이 tear-down 됐으면 true를 반환해요.
• jest.retryTimes(numRetries, options?) — 테스트 재시도 횟수를 지정. 파일 최상위나 describe 블록 안에서 선언해야 해요. 기본 jest-circus 러너에서만 사용 가능해요.
• jest.setTimeout(timeout) — 테스트 기본 타임아웃을 설정해요.

더 알아보기

• Mock Functions - mock 함수 사용
• Mock Function API - mock 인스턴스 API
• Fake Timers / Timer Mocks - 타이머 제어