테스트가 실패했을 때 가장 먼저 보는 것은 코드가 아니라 출력 로그입니다. 로컬에서는 어떤 테스트가 깨졌는지 눈으로 빠르게 읽고 싶고, CI에서는 실패 이력과 테스트 리포트를 파일로 남겨 이후 분석이나 대시보드에 연결하고 싶습니다. 그런데 테스트 출력이 너무 장황하거나, 반대로 필요한 정보가 남지 않으면 원인 파악 시간이 길어집니다.

Node.js 내장 test runner는 --test-reporter와 --test-reporter-destination 옵션으로 테스트 결과를 여러 형식으로 출력할 수 있습니다. 테스트 러너 기본 사용법은 Node.js test runner 가이드에서 다뤘고, 커버리지 흐름은 Node.js test runner coverage 가이드에서 정리했습니다. 이 글에서는 CI에서 읽기 좋은 테스트 결과를 남기기 위한 reporter 구성 기준을 정리합니다.

Node.js test reporter가 필요한 이유

테스트 실패 로그는 디버깅의 첫 화면이다

CI에서 테스트가 실패하면 개발자는 실패한 job의 로그부터 엽니다. 이때 출력이 raw TAP 형식만 길게 이어지면 사람에게는 읽기 어렵고, 반대로 예쁜 요약만 남기면 자동화 도구가 파싱하기 어렵습니다. 로컬과 CI가 같은 출력을 무조건 공유하면 둘 중 하나의 경험이 나빠질 수 있습니다.

Node.js test runner의 reporter는 이 문제를 분리해 줍니다. 사람이 보는 콘솔에는 spec처럼 읽기 쉬운 출력을 남기고, 도구가 읽는 파일에는 junit 같은 기계 친화적인 형식을 저장할 수 있습니다.

node --test --test-reporter=spec

이 명령은 테스트 결과를 콘솔에서 읽기 좋은 형태로 보여 줍니다. 작은 프로젝트에서는 이것만으로도 충분하지만, GitHub Actions나 다른 CI에서 테스트 리포트를 보존하려면 파일 출력까지 함께 설계하는 편이 좋습니다.

테스트 결과는 운영 품질의 누적 기록이다

테스트 로그는 단순히 통과 여부만 알려 주는 자료가 아닙니다. 어떤 테스트가 자주 실패하는지, 시간이 오래 걸리는 테스트가 무엇인지, flaky test가 어디서 발생하는지 추적하는 기반입니다.

운영 장애 로그를 구조화하는 것처럼 테스트 결과도 구조화해 두면 팀의 품질 신호가 더 선명해집니다. 장애 분석을 함께 다루는 프로젝트라면 Node.js process report 가이드나 Node.js source maps 가이드와 연결해 디버깅 자료의 형식을 통일할 수 있습니다.

기본 reporter 옵션 이해하기

spec reporter는 사람이 읽기 좋다

spec reporter는 테스트 이름과 성공/실패 상태를 계층적으로 보여 줍니다. 로컬 개발자가 터미널에서 실패 지점을 빠르게 찾을 때 적합합니다.

node --test --test-reporter=spec "test/**/*.test.js"

테스트 이름을 구체적으로 작성해 두면 reporter의 가치가 커집니다. works 같은 이름보다 결제 실패 시 재시도하지 않고 에러를 반환한다처럼 조건과 기대 결과가 드러나는 이름이 로그에서 바로 읽힙니다. 외부 의존성 호출 검증은 Node.js test runner mock.fn 가이드처럼 테스트 이름과 mock 기대값을 함께 정리하면 실패 원인이 더 명확해집니다.

tap reporter는 기본 호환성이 좋다

TAP(Test Anything Protocol)은 테스트 결과를 텍스트 프로토콜로 표현하는 형식입니다. Node.js test runner의 기본 출력과 가까워 오래된 도구와도 연결하기 쉽습니다.

node --test --test-reporter=tap

TAP은 사람이 보기에는 다소 건조하지만, 단순한 텍스트라 저장과 전달이 쉽습니다. 별도 리포트 도구가 TAP을 기대한다면 굳이 다른 형식으로 바꾸지 않아도 됩니다. 다만 대부분의 CI 대시보드나 테스트 리포트 집계 도구는 JUnit XML을 더 자연스럽게 지원하는 경우가 많습니다.

junit reporter는 CI 리포트 저장에 유리하다

junit reporter는 테스트 결과를 XML 형식으로 출력합니다. GitHub Actions 자체가 JUnit XML을 자동으로 예쁘게 렌더링해 주는 것은 아니지만, 아티팩트로 보관하거나 별도 액션과 연동하기 좋습니다.

mkdir -p reports
node --test \
  --test-reporter=junit \
  --test-reporter-destination=reports/test-results.xml

이렇게 저장한 파일은 CI 실행이 끝난 뒤 업로드할 수 있습니다. 실패한 테스트 목록과 메시지를 장기적으로 모으려면 콘솔 로그만 남기는 것보다 파일 기반 리포트가 훨씬 안정적입니다.

로컬과 CI 출력 분리하기

package.json script를 역할별로 나눈다

가장 단순한 운영 방식은 로컬용과 CI용 script를 분리하는 것입니다. 개발자는 npm test로 보기 좋은 출력을 사용하고, CI는 npm run test:ci로 리포트 파일을 남기게 합니다.

{
  "scripts": {
    "test": "node --test --test-reporter=spec",
    "test:ci": "mkdir -p reports && node --test --test-reporter=junit --test-reporter-destination=reports/test-results.xml"
  }
}

이 구성은 명확하지만 한 가지 단점이 있습니다. CI 로그에서는 XML만 출력되고 사람이 읽기 어려울 수 있습니다. CI에서도 콘솔은 spec, 파일은 junit으로 동시에 남기고 싶다면 reporter를 여러 개 지정하는 구성을 검토할 수 있습니다.

콘솔과 파일을 동시에 남긴다

Node.js test runner는 reporter와 destination을 함께 지정해 출력 위치를 제어할 수 있습니다. 환경과 Node.js 버전에 따라 지원 범위를 확인해야 하지만, 최근 Node.js에서는 여러 reporter를 지정해 콘솔과 파일을 나누는 패턴을 사용할 수 있습니다.

mkdir -p reports
node --test \
  --test-reporter=spec \
  --test-reporter-destination=stdout \
  --test-reporter=junit \
  --test-reporter-destination=reports/test-results.xml

이 패턴의 장점은 실패 순간에 CI 로그를 바로 읽을 수 있고, 동시에 JUnit XML도 보존된다는 점입니다. 팀에서 사용하는 Node.js 버전이 이 옵션 조합을 지원하는지 먼저 검증한 뒤 공통 script로 올리는 것이 안전합니다. Node.js 버전별 기능 차이는 테스트 환경을 고정하는 이유가 되며, 런타임 옵션 관리 기준은 Node.js Permission Model 가이드처럼 실행 경계를 정하는 글과 함께 볼 수 있습니다.

GitHub Actions에서 리포트 보관하기

테스트 결과 디렉터리를 먼저 만든다

CI에서 가장 흔한 실수는 reporter destination으로 지정한 디렉터리가 없어 테스트 실행 전에 실패하는 것입니다. 리포트 파일을 저장하기 전 mkdir -p reports를 명시적으로 실행합니다.

name: test

on:
  pull_request:
  push:
    branches: [main]

jobs:
  node-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: mkdir -p reports
      - run: |
          node --test \
            --test-reporter=spec \
            --test-reporter-destination=stdout \
            --test-reporter=junit \
            --test-reporter-destination=reports/test-results.xml

YAML에서는 줄바꿈과 백슬래시 위치가 중요합니다. 옵션이 잘못 이어지면 reporter가 적용되지 않거나 destination이 예상과 다르게 해석될 수 있습니다. 처음에는 로컬에서 같은 명령을 복사해 실행하고, 결과 파일이 실제로 만들어지는지 확인한 뒤 CI에 넣는 것이 좋습니다.

실패해도 리포트 아티팩트를 업로드한다

테스트가 실패하면 그 다음 step이 실행되지 않아 리포트를 잃는 경우가 있습니다. GitHub Actions에서는 if: always()를 사용해 테스트 실패 여부와 관계없이 결과 파일을 업로드할 수 있습니다.

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: node-test-results
          path: reports/test-results.xml
          if-no-files-found: warn

if-no-files-found: warn은 테스트 실행 자체가 시작되기 전에 실패한 경우에도 job을 더 혼란스럽게 만들지 않습니다. 다만 리포트가 항상 있어야 하는 정책이라면 error로 바꿔도 됩니다. 중요한 것은 실패했을 때 필요한 자료가 사라지지 않도록 업로드 step을 테스트 step과 분리하는 것입니다.

테스트 이름과 로그 품질 높이기

실패 메시지는 원인을 바로 설명해야 한다

Reporter가 아무리 좋아도 테스트 이름과 assertion 메시지가 부실하면 로그 품질은 낮습니다. 테스트 이름은 조건, 행동, 기대 결과를 담는 편이 좋습니다.

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

function calculateDiscount({ grade, total }) {
  if (grade === 'vip' && total >= 100_000) {
    return 10_000;
  }

  return 0;
}

test('VIP 고객이 10만 원 이상 구매하면 1만 원 할인을 적용한다', () => {
  const discount = calculateDiscount({ grade: 'vip', total: 120_000 });

  assert.equal(discount, 10_000);
});

테스트 이름이 구체적이면 CI 로그만 보고도 실패 조건을 파악할 수 있습니다. 복잡한 객체 일부만 검증하는 테스트에서는 전체 객체 비교보다 필요한 필드를 부분 비교하는 편이 실패 메시지가 선명합니다. 이 흐름은 Node.js assert.partialDeepStrictEqual 가이드와 잘 맞습니다.

비동기 테스트는 타임아웃과 취소 기준을 둔다

CI에서 가장 답답한 실패는 테스트가 끝나지 않고 오래 멈춰 있는 상황입니다. 비동기 테스트는 외부 호출을 직접 기다리지 말고 mock으로 격리하거나, 명확한 timeout과 AbortSignal을 사용해야 합니다.

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

async function fetchWithDeadline(fetcher, signal) {
  const response = await fetcher('https://example.test/api', { signal });
  return response.ok;
}

test('요청 취소 신호를 fetcher에 전달한다', async () => {
  const signal = AbortSignal.timeout(100);
  const calls = [];

  const ok = await fetchWithDeadline(async (url, options) => {
    calls.push({ url, signal: options.signal });
    return { ok: true };
  }, signal);

  assert.equal(ok, true);
  assert.equal(calls[0].signal, signal);
});

취소 가능한 테스트는 실패하더라도 CI 자원을 오래 붙잡지 않습니다. HTTP 요청 timeout과 재시도 흐름은 Node.js fetch AbortSignal timeout 가이드를 참고하면 더 안정적으로 설계할 수 있습니다.

reporter 구성에서 자주 하는 실수

XML 파일만 남기고 콘솔 가독성을 버린다

CI 시스템은 기계가 실행하지만 실패를 읽는 사람은 개발자입니다. JUnit XML만 저장하고 콘솔에는 읽기 어려운 출력만 남기면 실패 직후의 대응 속도가 느려집니다. 가능하면 콘솔에는 사람이 읽기 좋은 reporter를 남기고, XML은 별도 파일로 저장합니다.

리포트 파일을 git에 커밋한다

reports/test-results.xml은 실행 결과입니다. 소스 코드와 함께 커밋할 대상이 아닙니다. 프로젝트의 .gitignore에 리포트 디렉터리를 추가해 실수로 커밋되지 않게 합니다.

reports/
coverage/

커버리지 결과도 같은 원칙을 적용합니다. 요약 수치나 배지는 별도로 관리하더라도, 매번 바뀌는 원시 실행 결과는 보통 저장소에 넣지 않는 편이 낫습니다.

Node.js 버전 차이를 확인하지 않는다

내장 test runner는 Node.js 버전에 따라 기능과 reporter 동작이 달라질 수 있습니다. 로컬은 최신 버전인데 CI는 오래된 LTS를 쓰면 옵션이 다르게 동작하거나 실패할 수 있습니다. actions/setup-node와 .nvmrc, package.json의 engines 기준을 맞춰 두면 이런 차이를 줄일 수 있습니다.

{
  "engines": {
    "node": ">=22"
  }
}

정확한 최소 버전은 프로젝트에서 사용하는 reporter 조합을 실제로 검증한 뒤 정하는 것이 좋습니다. 단순히 문서상 지원 여부만 보는 것보다 CI에서 같은 명령을 실행해 보는 쪽이 안전합니다.

실무 적용 체크리스트

처음 도입할 때 확인할 것

  • 로컬 기본 명령은 사람이 읽기 좋은 spec reporter를 사용하는가?
  • CI 명령은 JUnit XML 같은 파일 리포트를 남기는가?
  • 테스트 실패 후에도 리포트 아티팩트가 업로드되는가?
  • 리포트 디렉터리가 .gitignore에 포함되어 있는가?
  • Node.js 로컬 버전과 CI 버전이 같은 기준으로 고정되어 있는가?

테스트 품질과 함께 관리할 것

  • 테스트 이름이 조건과 기대 결과를 설명하는가?
  • assertion 실패 메시지만 보고도 원인을 좁힐 수 있는가?
  • 외부 의존성은 mock이나 fake로 격리되어 있는가?
  • 오래 걸리는 테스트는 timeout, 취소, 분리 실행 기준이 있는가?
  • coverage와 reporter 결과가 서로 충돌하지 않고 별도 산출물로 보관되는가?

FAQ

Node.js test runner에서 무조건 junit reporter를 써야 하나요?

아닙니다. 작은 프로젝트나 개인 프로젝트에서는 spec reporter만으로도 충분할 수 있습니다. 다만 CI 이력을 장기적으로 보관하거나 테스트 리포트 도구와 연동하려면 junit 파일을 함께 남기는 편이 좋습니다.

TAP과 JUnit 중 무엇을 선택해야 하나요?

사람이 직접 읽거나 단순 텍스트 파이프라인에 연결한다면 TAP도 괜찮습니다. CI 리포트 집계, 아티팩트 저장, 외부 테스트 대시보드 연동을 생각한다면 JUnit XML이 더 범용적입니다. 팀의 도구가 어떤 형식을 잘 지원하는지 먼저 확인하세요.

reporter 설정만으로 flaky test를 해결할 수 있나요?

Reporter는 flaky test를 고쳐 주지는 않습니다. 대신 어떤 테스트가 얼마나 자주 실패하는지 추적할 수 있는 자료를 남깁니다. 불안정한 테스트 자체는 시간 의존성, 외부 의존성, 공유 상태를 줄이는 방향으로 고쳐야 하며, 시간 제어는 Node.js mock timers 가이드를 함께 보면 좋습니다.

마무리

Node.js test runner의 reporter 설정은 테스트 실행을 꾸미는 옵션이 아니라 실패를 빠르게 읽고 기록을 남기기 위한 운영 장치입니다. 로컬에서는 spec처럼 사람이 읽기 좋은 출력을 쓰고, CI에서는 junit 파일을 아티팩트로 보존하면 당장의 디버깅과 장기적인 품질 추적을 동시에 챙길 수 있습니다.

핵심은 출력 형식을 하나로 고정하지 않는 것입니다. 사람이 읽는 콘솔과 도구가 읽는 파일의 목적을 나누고, 테스트 이름과 assertion 품질까지 함께 관리해야 reporter의 효과가 살아납니다. 작게 시작한다면 npm test는 spec, npm run test:ci는 junit 저장으로 나눈 뒤, 실패 로그를 실제로 읽어 보며 팀에 맞는 형식으로 다듬어 보세요.