테스트에서 검증해야 하는 값이 항상 작은 것은 아닙니다. CLI 도움말 출력, 설정 파일 렌더링 결과, API 응답 샘플, 코드 생성 결과처럼 구조가 크고 사람이 한 번에 확인해야 하는 값도 있습니다. 이런 값을 모두 deepStrictEqual()로 직접 쓰면 테스트가 길어지고, 작은 문구 변경도 어디가 바뀌었는지 읽기 어려워집니다.

Node.js 내장 test runner는 이런 상황을 위해 snapshot 테스트를 제공합니다. Node.js test runner 공식 문서에 따르면 snapshot 테스트는 임의의 값을 문자열로 직렬화한 뒤, 이미 저장된 snapshot 파일의 기준값과 비교합니다. 또한 snapshot 파일은 테스트 파일과 함께 소스 관리에 포함하는 것이 권장되며, --test-update-snapshots 플래그로 기준값을 생성하거나 갱신할 수 있습니다.

내장 테스트 러너 기본 사용법은 Node.js test runner 가이드를 먼저 참고하세요. 큰 객체의 핵심 필드만 검증해야 한다면 Node.js assert partialDeepStrictEqual 가이드와 비교해 보면 좋습니다. 문자열 일부만 확인하는 테스트는 Node.js assert.match 가이드와 역할이 나뉩니다.

snapshot 테스트가 맞는 상황

H3. 출력 전체의 모양을 검토해야 할 때 쓴다

snapshot은 결과의 전체 모양을 저장해 두고 다음 실행에서 달라졌는지 확인하는 방식입니다. 따라서 값 하나의 정답보다 “이 출력 구조가 의도치 않게 바뀌지 않았는가”가 중요할 때 잘 맞습니다. 예를 들어 CLI help, Markdown 렌더링 결과, JSON 설정 템플릿, 코드 생성 결과가 좋은 후보입니다.

import { test } from 'node:test';

function renderHelp() {
  return [
    'Usage: deploy [options]',
    '',
    'Options:',
    '  --env <name>     deployment environment',
    '  --dry-run        print the plan without applying it'
  ].join('\n');
}

test('renders deploy help output', (t) => {
  t.assert.snapshot(renderHelp());
});

처음 실행할 때 snapshot 파일이 없으면 테스트는 실패합니다. 그다음 --test-update-snapshots로 기준 파일을 생성하고, 이후 실행에서는 기존 snapshot과 비교합니다. 이 흐름은 결과를 자동 승인하는 것이 아니라, 사람이 검토할 기준 파일을 만들어 두는 과정으로 이해해야 합니다.

H3. 작은 계약 검증까지 snapshot에 맡기지는 않는다

snapshot은 넓게 보는 테스트입니다. 반대로 결제 금액, 권한 플래그, 상태 코드처럼 깨지면 안 되는 핵심 계약은 명시적인 assertion으로 쓰는 편이 더 좋습니다. snapshot에 모든 것을 넣으면 변경 diff는 보이지만, 무엇이 진짜 중요한 계약인지 테스트 이름만으로 알기 어려워집니다.

import assert from 'node:assert/strict';
import { test } from 'node:test';

function buildApiResponse(user) {
  return {
    status: 200,
    body: {
      id: user.id,
      name: user.name,
      permissions: ['read:post', 'write:comment']
    }
  };
}

test('builds public user response', (t) => {
  const response = buildApiResponse({ id: 'user_123', name: 'Sooya' });

  assert.strictEqual(response.status, 200);
  assert.deepStrictEqual(response.body.permissions, ['read:post', 'write:comment']);
  t.assert.snapshot(response.body);
});

이 예제에서는 상태 코드와 권한 목록을 명시적으로 검증하고, 응답 body의 전체 모양은 snapshot으로 봅니다. 핵심 계약은 assertion으로 읽히고, 주변 구조 변화는 snapshot diff로 검토할 수 있습니다. 실무에서는 이 조합이 snapshot 남용을 줄이는 데 도움이 됩니다.

기본 사용법

H3. t.assert.snapshot()으로 기준값과 비교한다

Node.js test runner에서는 테스트 컨텍스트의 t.assert.snapshot()을 사용합니다. 값을 넘기면 test runner가 직렬화한 문자열을 snapshot 파일의 항목과 비교합니다. 한 테스트 안에서 여러 snapshot을 호출하면 테스트 이름과 순번으로 각각 구분됩니다.

import { suite, test } from 'node:test';

suite('invoice renderer', () => {
  test('renders summary and line items', (t) => {
    const invoice = {
      title: 'July invoice',
      total: 32000,
      items: [
        { name: 'hosting', amount: 12000 },
        { name: 'support', amount: 20000 }
      ]
    };

    t.assert.snapshot(invoice);
    t.assert.snapshot(invoice.items.map((item) => item.name));
  });
});

생성되는 snapshot은 사람이 읽을 수 있는 형태여야 합니다. snapshot diff를 리뷰할 수 없다면 테스트가 실패했을 때 원인을 파악하기 어렵습니다. 값이 너무 크거나 순서가 불안정하다면 snapshot 전에 필요한 필드만 남기는 정규화 단계가 필요합니다.

H3. –test-update-snapshots는 기준값 생성과 갱신에만 사용한다

snapshot 파일을 처음 만들거나 의도적으로 갱신할 때는 --test-update-snapshots를 붙입니다. 이 플래그를 붙인 실행은 현재 출력으로 기준값을 다시 쓰기 때문에, 평소 CI 명령에는 넣지 않는 편이 안전합니다. 로컬에서 diff를 확인한 뒤 snapshot 파일을 함께 커밋하는 흐름이 좋습니다.

node --test --test-update-snapshots

node --test

일반 실행에서는 update 플래그 없이 기존 snapshot과 비교합니다. 변경이 의도된 것이라면 update 명령으로 파일을 갱신하고, 변경 이유를 코드 리뷰에서 설명하세요. 변경이 의도되지 않았다면 제품 코드나 테스트 입력을 수정해야 합니다.

H3. snapshot 파일은 테스트와 함께 커밋한다

공식 문서도 snapshot 파일을 테스트 파일과 함께 소스 관리에 포함하는 방식을 권장합니다. snapshot은 테스트의 기대값이므로, 테스트 코드만 있고 snapshot 파일이 없으면 다른 환경에서 같은 기준으로 검증할 수 없습니다. 리뷰에서는 제품 코드 변경과 snapshot 변경을 함께 봐야 합니다.

src/
  render-invoice.js
test/
  render-invoice.test.js
  render-invoice.test.js.snapshot

snapshot 파일이 너무 자주 바뀐다면 입력에 현재 시각, 랜덤 값, 실행 환경 경로가 섞였는지 확인하세요. 그런 값은 테스트 전에 고정하거나 제거해야 합니다. 불안정한 snapshot은 결국 리뷰어가 diff를 신뢰하지 않게 만듭니다.

fileSnapshot과 serializer 활용

H3. fileSnapshot은 파일 하나에 값 하나를 명시적으로 저장한다

t.assert.fileSnapshot()은 snapshot 파일 경로를 직접 지정하는 방식입니다. 공식 문서에 따르면 이 방식은 snapshot 파일 하나가 하나의 값만 담고, test runner의 추가 escaping을 적용하지 않습니다. 그래서 JSON, HTML, Markdown처럼 파일 확장자와 syntax highlighting이 중요한 결과에 잘 맞습니다.

import { test } from 'node:test';

function renderReadme() {
  return [
    '# Deploy Guide',
    '',
    'Run `npm run deploy` after tests pass.'
  ].join('\n');
}

test('renders README template', (t) => {
  t.assert.fileSnapshot(renderReadme(), './snapshots/deploy-readme.md');
});

일반 snapshot()은 테스트 파일별 snapshot 묶음을 자동 관리하는 데 편합니다. 반면 fileSnapshot()은 산출물 자체를 독립 파일처럼 보고 싶을 때 좋습니다. 팀이 리뷰하기 쉬운 쪽을 선택하되, 한 프로젝트 안에서는 기준을 일관되게 유지하세요.

H3. serializer로 불안정한 값을 제거한다

snapshot 대상에 시간, 임시 경로, 랜덤 ID가 들어가면 테스트가 매번 흔들립니다. 이럴 때는 serializer로 값의 표현을 안정화할 수 있습니다. serializer는 snapshot에 쓰기 전에 값을 문자열로 바꾸는 함수 배열입니다.

import crypto from 'node:crypto';
import { test } from 'node:test';

function buildJobResult() {
  return {
    id: crypto.randomUUID(),
    status: 'queued',
    createdAt: new Date().toISOString()
  };
}

test('serializes queued job result', (t) => {
  const result = buildJobResult();

  t.assert.snapshot(result, {
    serializers: [
      (value) => ({
        ...value,
        id: '<uuid>',
        createdAt: '<iso-date>'
      }),
      (value) => JSON.stringify(value, null, 2)
    ]
  });
});

serializer는 불안정성을 숨기는 도구가 아니라, 테스트 목적과 무관한 노이즈를 제거하는 도구입니다. 예를 들어 ID 형식 자체가 중요한 테스트라면 <uuid>로 바꾸지 말고 정규식 assertion을 따로 두는 편이 낫습니다. snapshot에는 사람이 검토할 의미 있는 구조만 남기는 것이 핵심입니다.

CI에서 운영하는 기준

H3. CI에서는 update 플래그를 금지한다

CI의 역할은 기준값을 바꾸는 것이 아니라, 현재 코드가 기준값과 일치하는지 확인하는 것입니다. 따라서 CI 명령에는 --test-update-snapshots를 넣지 않습니다. snapshot 갱신은 로컬 브랜치에서 수행하고, 변경된 snapshot 파일을 리뷰 대상으로 올리는 방식이 안전합니다.

{
  "scripts": {
    "test": "node --test",
    "test:update-snapshots": "node --test --test-update-snapshots",
    "test:ci": "node --test"
  }
}

이렇게 분리하면 개발자는 의도적인 변경 때만 update 명령을 실행합니다. CI는 snapshot diff가 생기면 실패하고, 리뷰어는 제품 코드 변경과 기준값 변경이 맞물리는지 확인할 수 있습니다. 자동 갱신을 CI에 넣으면 잘못된 출력도 기준값으로 굳어질 수 있습니다.

H3. snapshot diff는 코드 리뷰의 일부로 본다

snapshot 파일은 생성물처럼 보이지만 테스트 기대값입니다. 따라서 diff가 크다고 무조건 넘기면 안 됩니다. 특히 권한, 금액, URL, 보안 헤더, 사용자에게 보이는 안내문이 바뀌었다면 제품 코드 diff만큼 꼼꼼히 봐야 합니다.

review checklist:
- snapshot 변경이 제품 변경 의도와 일치하는가?
- 현재 시각, 랜덤 값, 로컬 경로 같은 노이즈가 섞이지 않았는가?
- 핵심 계약은 별도 assertion으로 고정되어 있는가?
- snapshot 파일이 너무 커서 리뷰가 사실상 불가능하지 않은가?

snapshot이 커질수록 리뷰 품질은 낮아지기 쉽습니다. 큰 결과를 통째로 저장하기보다 섹션별로 나누거나, 핵심 구조만 정규화해 저장하세요. 테스트가 실패했을 때 “무엇을 확인해야 하는지”가 바로 보여야 좋은 snapshot입니다.

snapshot을 피해야 하는 경우

H3. 단일 값 검증에는 일반 assertion이 더 낫다

상태 코드, boolean 플래그, 배열 길이처럼 작은 값은 snapshot보다 일반 assertion이 읽기 쉽습니다. 테스트 실패 메시지도 더 직접적입니다. snapshot은 기대값이 파일 밖으로 분리되기 때문에, 작은 계약 검증에는 오히려 과합니다.

import assert from 'node:assert/strict';
import { test } from 'node:test';

test('returns created status', () => {
  const response = createPost({ title: 'hello' });

  assert.strictEqual(response.status, 201);
});

이 테스트는 snapshot보다 명시적인 assertion이 더 좋습니다. 독자는 테스트 파일만 보고도 무엇이 중요한지 알 수 있습니다. snapshot은 “큰 출력의 변화”를 다룰 때 가장 가치가 큽니다.

H3. 자주 바뀌는 UI 문구 전체를 고정하면 비용이 커진다

문구가 자주 바뀌는 화면 전체를 snapshot으로 고정하면 작은 수정마다 기준값 갱신이 필요합니다. 그 결과 리뷰어가 snapshot diff를 습관적으로 승인하게 될 수 있습니다. 자주 바뀌는 영역은 핵심 요소만 assertion으로 검증하거나, 안정적인 데이터 구조로 변환해 snapshot을 남기는 편이 좋습니다.

test('renders visible action labels', (t) => {
  const view = renderToolbar();

  t.assert.snapshot({
    actions: view.actions.map((action) => ({
      id: action.id,
      label: action.label
    }))
  });
});

전체 HTML을 그대로 저장하는 대신, 실제로 검토할 action 목록만 남긴 예입니다. 이렇게 줄이면 스타일 클래스나 렌더링 순서의 작은 변화가 테스트를 과하게 흔들지 않습니다. snapshot 대상은 넓게 잡기보다 리뷰 가능한 크기로 자르는 것이 좋습니다.

실무 도입 체크리스트

H3. Node.js test runner snapshot을 적용할 때 확인할 것

  • 큰 출력 전체를 검토해야 하는 테스트인가?
  • 핵심 계약은 assert.strictEqual(), assert.deepStrictEqual(), assert.match()로 별도 고정했는가?
  • snapshot 대상에 랜덤 값, 현재 시각, 로컬 경로가 섞이지 않는가?
  • snapshot 파일을 테스트와 함께 커밋하는가?
  • CI 명령에서 --test-update-snapshots를 제외했는가?
  • diff가 너무 커서 리뷰하기 어려운 snapshot은 아닌가?

snapshot 테스트는 “테스트를 덜 쓰는 방법”이 아니라 “큰 기대값을 사람이 검토 가능한 파일로 관리하는 방법”입니다. 작은 계약은 명시적인 assertion으로 고정하고, 넓은 구조 변화는 snapshot으로 검토하면 두 방식의 장점을 함께 살릴 수 있습니다. Node.js test runner만으로도 이 흐름을 구성할 수 있으므로, CLI 출력이나 코드 생성 결과처럼 변화 감지가 필요한 영역부터 작게 도입해 보세요.

함께 보면 좋은 글