테스트 커버리지와 품질 관리

이 절에서는 테스트 커버리지(Test Coverage)의 의미와 이를 활용한 코드 품질 관리 방법을 다룹니다.

테스트 커버리지는 단순히 테스트가 얼마나 많이 작성되었는가를 넘어, 작성된 테스트가 얼마나 많은 코드 경로를 실행하는가를 나타내는 중요한 지표입니다.

커버리지는 아직 실행해 보지 않은 코드를 찾고 변경 위험을 드러내는 데 도움을 줍니다. 다만 높은 수치만으로 결함이 적거나 동작이 정확하다고 결론 내릴 수는 없습니다.

테스트 커버리지란?

테스트 커버리지(Test Coverage)는 소프트웨어 테스트가 소스 코드의 특정 부분을 실행하는 정도를 측정하는 지표입니다.

일반적으로 백분율(%)로 표시되며, 테스트 스위트가 애플리케이션 코드의 얼마나 많은 부분을 실행하는지 보여줍니다.

• 라인 커버리지(Line Coverage): 소스 코드의 전체 실행 가능한 라인 중 몇 라인이 테스트에 의해 실행되었는지 측정합니다. 가장 일반적이고 직관적인 지표입니다.
• 함수/메서드 커버리지(Function/Method Coverage): 전체 함수/메서드 중 몇 개가 테스트에 의해 호출되었는지 측정합니다.
• 브랜치 커버리지(Branch Coverage): if, 조건식, switch 등 계측된 조건의 각 분기 결과가 테스트에 의해 실행되었는지 측정합니다. 각 분기를 실행했다는 사실이 모든 경로 조합과 경계값을 검증했다는 뜻은 아닙니다.
• 문장 커버리지(Statement Coverage): 모든 문장(statement)이 한 번 이상 실행되었는지 측정합니다. 라인 커버리지와 유사하지만, 공백이나 주석은 제외됩니다.

• 누락 경로 발견: 실행하지 않은 실패·예외·경계 경로를 찾아 테스트 후보로 바꿀 수 있습니다.
• 코드 변경의 관찰성: 리팩토링이나 기능 추가 시, 관련 경로를 실행하는 테스트가 있다면 회귀 신호를 더 빨리 얻을 수 있습니다.
• 문서화 역할: 테스트 코드는 실제 코드의 사용 예시를 보여주므로, 일종의 문서화 역할을 합니다.
• 변경 안정성: 코드 변경 후 회귀 여부를 더 쉽게 확인할 수 있습니다.

100% 커버리지는 계측된 항목을 모두 실행했다는 뜻일 뿐, 요구사항과 assertion이 완전하다는 뜻은 아닙니다. 모든 상황에서 달성 비용이 정당한 것도 아닙니다.

• 비용과 효율: 100% 커버리지를 달성하기 위해 비즈니스 가치가 적은 코드까지 테스트하는 것은 시간과 자원의 낭비일 수 있습니다.
• 테스트 품질: 커버리지 숫자가 높다고 해서 테스트의 품질이 높다는 것을 의미하지는 않습니다. 단순히 코드를 실행만 시킬 뿐, 올바른 시나리오나 엣지 케이스를 검증하지 않는 쓸모없는 테스트일 수도 있습니다.
• 환경 경계: 실제 인프라에서만 드러나는 실패는 통합·E2E·sandbox 검증이 필요할 수 있습니다. 정말 도달할 수 없는 코드는 제외로 숨기기보다 삭제를 먼저 검토합니다.

결론: 테스트 커버리지는 코드 품질의 지표 중 하나이지, 그 자체가 목표가 되어서는 안 됩니다.

팀 상황과 프로젝트 중요도에 맞춰 적절한 커버리지 목표를 설정하고, 양적 지표와 함께 테스트의 질적 측면도 함께 고려해야 합니다.

실패 비용과 변경 빈도가 큰 핵심 계약에는 더 강한 기준을 적용하고, 낮은 위험의 단순 코드에는 비용에 맞는 기준을 적용할 수 있습니다. 코드 종류만 보고 일률적으로 낮은 기준을 주지는 않습니다.

NestJS에서 테스트 커버리지 측정

NestJS는 Jest를 기본 테스트 러너로 사용하며, Jest는 자체 커버리지 리포트 기능을 내장하고 있습니다.

NestJS 프로젝트의 package.json 파일을 보면 이미 커버리지 리포트 생성을 위한 스크립트가 정의되어 있습니다.

{
  "scripts": {
    "test": "jest",
    "test:watch": "jest --watch",
    "test:cov": "jest --coverage",
    "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
    "test:e2e": "jest --config ./test/jest-e2e.json"
  }
}

기존 package.json의 scripts 객체에 위 키를 병합하고, 커버리지 측정에는 test:cov를 사용합니다.

커버리지 리포트를 생성하려면 다음 명령어를 실행합니다.

npm run test:cov

명령어를 실행하면 Jest가 모든 테스트를 실행하고, 콘솔에 다음과 같은 요약 표를 출력합니다 (프로젝트에 따라 숫자는 다르게 나타날 수 있습니다):

--------------------|---------|----------|---------|---------|-------------------
File                | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
--------------------|---------|----------|---------|---------|-------------------
All files           |   92.85 |      100 |   83.33 |   92.85 |
 app.controller.ts  |     100 |      100 |     100 |     100 |
 app.service.ts     |     100 |      100 |     100 |     100 |
 main.ts            |     100 |      100 |     100 |     100 |
 users/users.controller.ts |   71.42 |      100 |      50 |   71.42 | 19,20
 users/users.service.ts |   85.71 |      100 |      50 |   85.71 | 22-26
--------------------|---------|----------|---------|---------|-------------------

이 표는 각 파일별로 라인, 브랜치, 함수, 문장 커버리지를 보여주고, 커버되지 않은 라인 번호(Uncovered Line #s)도 알려줍니다.

All files는 파일별 퍼센트를 평균 낸 값이 아니라, 계측된 전체 항목의 covered/total을 합산해 계산한 집계입니다.

또한, 기본적으로 coverage라는 폴더가 프로젝트 루트에 생성되며, 그 안에 상세한 HTML 리포트가 포함됩니다.

coverage/lcov-report/index.html 파일을 웹 브라우저로 열면, 어떤 코드 라인이 테스트되지 않았는지 시각적으로 확인할 수 있어 테스트 개선에 큰 도움이 됩니다.

(위 다이어그램은 Jest 커버리지 리포트를 읽는 순서를 요약한 것입니다.)

리포트가 표시한 미실행 라인과 분기는 아직 실행되지 않은 부분입니다.

이 부분을 집중적으로 테스트 코드를 추가하여 커버리지를 높일 수 있습니다.

커버리지 임계값 설정 및 품질 관리

테스트 커버리지를 품질 관리의 일부로 사용하려면, 특정 커버리지 수준을 강제하는 임계값(Threshold)을 설정할 수 있습니다.

이는 CI/CD 파이프라인에서 커버리지가 특정 기준 미만일 경우 빌드를 실패시키는 방식으로 활용됩니다.

프로젝트의 jest.config.js 또는 package.json의 Jest 설정에서 coverageThreshold를 추가하거나 수정합니다. 별도 E2E 설정은 test:cov 스크립트가 그 설정을 명시적으로 선택할 때만 이 실행에 적용됩니다.

module.exports = {
  moduleFileExtensions: ['js', 'json', 'ts'],
  roots: ['<rootDir>/src'], // 단위 테스트와 소스 탐색 범위
  testRegex: '.*\\.spec\\.ts$', // 단위 테스트 파일만 선택
  transform: {
    '^.+\\.(t|j)s$': 'ts-jest',
  },
  collectCoverageFrom: [
    'src/**/*.ts',
    '!src/**/*.spec.ts',
    '!src/**/*.test.ts',
  ],
  coverageDirectory: 'coverage',
  testEnvironment: 'node',
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: 80,
    },
    './src/users/': {
      lines: 80,
      functions: 50,
    },
    './src/app*.ts': {
      lines: 95,
    },
  },
};

coverageThreshold: {
  global: { branches: 80, lines: 80 },
  './src/users/': { lines: 80 },
  './src/app*.ts': { lines: 95 },
}

• coverageThreshold
  • global: 경로·glob에 매치되지 않은 파일들의 집계에 최소 커버리지 임계값을 적용합니다. 모든 파일이 특정 그룹에 매치되면 전체 계측 파일 집계로 fallback합니다.
  • 디렉터리 경로는 그 아래 파일을 하나의 그룹으로 집계하고, glob은 매치된 각 파일을 개별 판정하며, 파일 경로는 해당 파일만 판정합니다. 지정한 경로·glob이 아무 파일도 찾지 못하면 Jest가 오류를 냅니다.

위 숫자는 설명을 위한 예시이며 팀의 보편적 정답이 아닙니다. 양수는 최소 커버 비율이고 음수는 허용할 최대 미커버 항목 수입니다. collectCoverageFrom glob은 <rootDir>을 기준으로 해석되지만, Jest 30의 상대 coverageThreshold 경로·glob key는 Jest 프로세스의 현재 작업 디렉터리를 기준으로 해석됩니다. 위 예시는 프로젝트 루트에서 Jest를 실행해 현재 작업 디렉터리와 <rootDir>이 같은 경우입니다. global과 경로·glob 기준을 함께 두면 Jest는 지정 대상을 별도로 판정하고 그 파일의 데이터를 나머지 global 집계에서 제외합니다.

이렇게 임계값을 설정한 후 npm run test:cov를 실행했을 때, 만약 설정된 임계값을 충족하지 못하면 Jest는 에러를 발생시키고 종료됩니다.

이는 CI/CD 파이프라인에서 실패로 이어져, 테스트 커버리지가 일정 수준 이하로 떨어지는 것을 방지할 수 있습니다.

테스트 커버리지는 실행된 코드 경로를 확인하는 지표입니다.

NestJS에서는 Jest 커버리지 명령과 임계값 설정을 사용해 측정할 수 있지만, 숫자보다 중요한 것은 실제 기능과 위험 영역을 검증하는 의미 있는 테스트입니다.

이것으로 8장 테스팅 전략을 모두 마칩니다.

단위 테스트, E2E 테스트, 커버리지 측정, CI 연동을 기준으로 테스트가 어느 경로를 검증하고 어떤 실패를 드러내는지 정리했습니다.