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

앞의 두 글에서 단위 테스트와 E2E 테스트를 작성했습니다. 이 글에서는 테스트 커버리지(test coverage)가 무엇을 뜻하는지, 그리고 이를 코드 품질 관리에 어떻게 활용하는지 다룹니다.

테스트 커버리지는 테스트를 몇 개 작성했는지가 아니라, 작성한 테스트가 코드 경로를 얼마나 많이 실행하는지를 나타내는 지표입니다. 커버리지는 아직 실행해 보지 않은 코드를 찾고 변경의 위험을 드러내는 데 도움을 줍니다. 다만 수치가 높다는 사실만으로 결함이 적거나 동작이 정확하다고 결론 내릴 수는 없습니다.

테스트 커버리지란

테스트 커버리지는 테스트가 소스 코드의 어느 부분을 실행했는지 측정하는 지표입니다. 보통 백분율로 나타내며, 테스트 스위트가 애플리케이션 코드의 얼마만큼을 실행하는지 보여 줍니다. Jest는 다음 네 가지 지표를 보여 줍니다.

• 라인 커버리지(line coverage): 실행할 수 있는 소스 줄 가운데 테스트가 실행한 줄의 비율입니다. 가장 흔하고 직관적인 지표입니다.
• 함수 커버리지(function coverage): 전체 함수와 메서드 가운데 테스트가 호출한 것의 비율입니다.
• 분기 커버리지(branch coverage): if, 조건식, switch 같은 조건의 각 분기 결과를 테스트가 실행했는지 측정합니다. 각 분기를 한 번씩 실행했다고 해서 모든 경로의 조합과 경곗값을 확인했다는 뜻은 아닙니다.
• 문장 커버리지(statement coverage): 모든 문장(statement)이 한 번 이상 실행되었는지 측정합니다. 라인 커버리지와 비슷하지만, 한 줄에 문장이 여러 개 있으면 따로 셉니다.

커버리지를 높게 유지하면 다음과 같은 이점이 있습니다.

• 빠진 경로 발견: 실행해 보지 않은 실패·예외·경곗값 경로를 찾아 테스트 후보로 삼을 수 있습니다.
• 변경 확인: 리팩터링이나 기능 추가 때 관련 경로를 실행하는 테스트가 있으면 회귀를 더 빨리 알아챌 수 있습니다.
• 문서 역할: 테스트 코드는 실제 코드의 사용 예시를 보여 주므로 일종의 문서가 됩니다.

커버리지 100%가 항상 좋은 것은 아닙니다

100% 커버리지는 계측된 항목을 모두 실행했다는 뜻일 뿐, 요구사항과 단언(assertion)이 완전하다는 뜻은 아닙니다. 모든 상황에서 그만한 비용을 들일 가치가 있는 것도 아닙니다.

• 비용과 효율: 100%를 채우려고 비즈니스 가치가 적은 코드까지 테스트하면 시간과 자원을 낭비할 수 있습니다.
• 테스트 품질: 커버리지 숫자가 높다고 테스트 품질이 높은 것은 아닙니다. 코드를 실행만 하고 올바른 시나리오나 경곗값 사례를 확인하지 않는 테스트일 수도 있습니다.
• 환경 문제: 실제 인프라에서만 드러나는 실패는 통합 테스트, E2E 테스트, sandbox 확인이 필요할 수 있습니다. 정말 도달할 수 없는 코드라면 커버리지에서 제외해 숨기기보다 지우는 것을 먼저 검토합니다.

테스트 커버리지는 코드 품질을 보여 주는 지표 가운데 하나일 뿐, 그 자체가 목표가 되어서는 안 됩니다. 팀 상황과 프로젝트의 중요도에 맞춰 커버리지 목표를 정하고, 숫자와 테스트의 질을 함께 봐야 합니다. 실패했을 때 비용이 크고 자주 바뀌는 핵심 기능에는 더 엄격한 기준을, 위험이 낮은 단순한 코드에는 비용에 맞는 기준을 적용할 수 있습니다. 다만 코드의 종류만 보고 일률적으로 낮은 기준을 주지는 않습니다.

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

Jest는 커버리지 리포트 기능을 자체적으로 제공합니다. 1장에서 CommonJS로 만든 NestJS 12 프로젝트의 package.json에는 이미 다음 테스트 스크립트가 들어 있습니다.

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

모든 스크립트가 같은 Node.js 옵션으로 Jest를 실행하며, 커버리지 측정에는 --coverage를 붙인 test:cov를 씁니다. test:cov는 --config를 지정하지 않으므로 루트의 jest.config.ts를 읽고, 그 설정의 testRegex가 고르는 단위 테스트만 실행합니다. E2E 테스트의 커버리지가 필요하다면 test:e2e에 --coverage를 붙인 별도 스크립트를 만듭니다.

커버리지 리포트를 만들려면 다음 명령을 실행합니다.

npm run test:cov

Jest가 테스트를 실행한 뒤 콘솔에 다음과 같은 요약 표를 출력합니다. 아래 표는 출력 형식을 보여 주기 위한 예시이며, 실제 숫자와 파일 목록은 프로젝트마다 다릅니다.

---------------------------|---------|----------|---------|---------|-------------------
File                       | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
---------------------------|---------|----------|---------|---------|-------------------
All files                  |   88.88 |      100 |   77.77 |   88.88 |
 app.controller.ts         |     100 |      100 |     100 |     100 |
 app.service.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는 파일별 백분율을 평균 낸 값이 아니라, 계측된 전체 항목의 실행 수와 전체 수를 합쳐 계산한 값입니다. 라인만 예로 들어 보겠습니다. 작은 파일 A는 실행할 수 있는 1줄 가운데 1줄을, 파일 B는 9줄 가운데 1줄을 실행했습니다. A는 100%, B는 약 11.11%이지만 전체는 (1 + 1) ÷ (1 + 9) × 100 = 20%입니다. 두 비율의 단순 평균인 약 55.56%를 전체 값으로 쓰면 큰 파일에서 실행되지 않은 줄을 과소평가하게 됩니다.

명령을 실행하면 jest.config.ts의 coverageDirectory에 지정된 coverage 폴더가 프로젝트 루트에 생기고, 그 안에 자세한 HTML 리포트가 들어 있습니다. coverage/lcov-report/index.html을 브라우저로 열면 어떤 줄이 테스트되지 않았는지 색으로 확인할 수 있어 테스트를 보강하는 데 도움이 됩니다.

위 그림의 위쪽 표는 네 가지 지표가 각각 무엇을 측정하고, 그 자체로는 무엇을 증명하지 못하는지 정리합니다. 예를 들어 분기 커버리지는 각 조건의 결과를 실행했는지는 알려 주지만, 모든 경로 조합과 경곗값을 확인했는지는 알려 주지 않습니다. 아래쪽 흐름은 리포트를 읽는 순서입니다. 같은 설정으로 측정한 뒤 실행되지 않은 줄과 분기를 찾고, 그것이 실패·빈 값·권한 같은 어떤 업무 위험인지 해석해 입력과 기대 결과를 가진 테스트를 추가한 다음, 다시 실행해 숫자뿐 아니라 의도한 오류를 단언이 잡아내는지 확인합니다.

커버리지 임계값과 품질 관리

커버리지를 품질 관리에 쓰려면 특정 수준을 강제하는 임계값(threshold)을 정할 수 있습니다. CI/CD 파이프라인에서 커버리지가 기준에 못 미치면 빌드를 실패시키는 방식으로 활용합니다.

test:cov가 실제로 읽는 jest.config.ts에 coverageThreshold를 추가합니다. 아래 코드는 NestJS 12 템플릿이 만든 설정에 임계값만 더한 것입니다. 별도의 E2E 설정은 test:cov가 그 파일을 지정할 때만 이 실행에 적용됩니다.

import type { Config } from 'jest';
import { pathsToModuleNameMapper } from 'ts-jest';
import ts from 'typescript';

// 경로 별칭은 tsconfig.json에서 읽어 옵니다.
const { config: tsconfig } = ts.readConfigFile(
  './tsconfig.json',
  ts.sys.readFile,
);
const paths = tsconfig?.compilerOptions?.paths ?? {};

const config: Config = {
  moduleFileExtensions: ['js', 'json', 'ts'],
  rootDir: '.',
  testRegex: '.*\\.spec\\.ts$', // 단위 테스트 파일만 선택
  transform: {
    '^.+\\.(t|j)s$': 'ts-jest',
  },
  moduleNameMapper: pathsToModuleNameMapper(paths, { prefix: '<rootDir>/' }),
  collectCoverageFrom: [
    'src/**/*.(t|j)s',
    'libs/**/*.(t|j)s',
    'apps/**/*.(t|j)s',
  ],
  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,
    },
  },
};

export default config;

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

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

위 그림은 임계값을 CI의 품질 점검으로 운영하는 방법을 보여 줍니다. 위쪽은 global, 디렉터리, glob 기준이 각각 어떤 범위를 묶어 판정하는지와, 양수와 음수 값의 뜻을 설명합니다. 아래쪽 흐름에서 같은 설정으로 측정한 결과가 기준에 못 미치면 변경을 멈추고 빠진 테스트를 보강하며, 통과하더라도 최소선만 넘었을 뿐이므로 업무 위험을 계속 검토합니다. 임계값을 통과했다는 사실을 모든 요구사항을 확인했다는 뜻으로 바꾸어 읽지 않는 것이 핵심입니다.

coverageThreshold의 각 기준은 다음과 같이 동작합니다.

• global: 경로나 glob 기준에 해당하지 않는 나머지 파일들을 하나로 합쳐 최소 임계값을 적용합니다. Jest 30.4.0부터는 모든 파일이 특정 기준에 해당해 남은 파일이 없으면 전체 계측 파일을 합친 값으로 판정합니다. Jest 30.3 이하에는 이 동작이 없으므로 설치한 버전을 확인합니다.
• 디렉터리 경로는 그 아래 파일들을 하나로 합쳐 판정하고, glob은 해당하는 각 파일을 하나씩 판정하며, 파일 경로는 그 파일만 판정합니다. 지정한 경로나 glob이 아무 파일도 찾지 못하면 Jest가 오류를 냅니다.
• 양수는 최소 커버 비율이고, 음수는 허용하는 최대 미실행 항목 수입니다.
• global과 경로·glob 기준을 함께 두면 Jest는 지정한 대상을 따로 판정하고, 그 파일들은 나머지 global 집계에서 뺍니다.

위 숫자는 설명을 위한 예시일 뿐 모든 팀에 맞는 정답이 아닙니다. 또 collectCoverageFrom의 glob은 <rootDir>을 기준으로 해석되지만, Jest 30에서 상대 경로로 적은 coverageThreshold 키는 Jest 프로세스의 현재 작업 디렉터리를 기준으로 해석됩니다. 위 예시는 프로젝트 루트에서 Jest를 실행해 현재 작업 디렉터리와 <rootDir>이 같은 경우입니다. 이 동작은 Jest의 coverageThreshold 문서와 설치한 버전의 CoverageReporter 구현을 함께 보며 확인합니다.

임계값을 설정한 뒤 npm run test:cov를 실행했을 때 기준을 채우지 못하면 Jest는 오류를 내고 0이 아닌 종료 코드로 끝납니다. CI 파이프라인은 이를 실패로 처리하므로, 커버리지가 합의한 수준 아래로 떨어지는 것을 막을 수 있습니다.

커버리지는 다음과 같이 품질 관리에 활용합니다.

• 초기 목표 설정: 프로젝트 초기에 팀과 합의해, 위험과 현재 수준에 맞는 최소선을 정합니다. 숫자는 프로젝트 사정에 따라 정하고, 보편적인 권장값처럼 쓰지 않습니다.
• CI/CD 연동: 모든 푸시나 풀 리퀘스트에서 파이프라인이 자동으로 커버리지를 측정하고 임계값을 검사하게 합니다. 기준에 못 미치면 빌드를 실패시켜 커버리지가 조용히 떨어지는 것을 막습니다. 다만 이 검사만으로 테스트 품질 전체가 보장되지는 않습니다.
• 정기적인 확인: 리포트를 주기적으로 보고 커버리지가 낮은 부분을 찾아 개선합니다.
• 코드 리뷰: 리뷰할 때 리포트를 참고해, 중요한 업무 로직이나 복잡한 부분에 테스트가 충분한지 확인합니다.
• 테스트 문화: 개발자가 테스트 작성을 습관으로 삼고, 커버리지를 품질을 보여 주는 지표 가운데 하나로 받아들이게 합니다.

정리

• 커버리지는 테스트가 실행한 코드의 비율이며, Jest는 문장·분기·함수·라인 네 가지 지표를 보여 줍니다.
• All files는 파일별 백분율의 평균이 아니라 전체 항목의 실행 수와 전체 수를 합쳐 계산합니다.
• NestJS 12의 CommonJS 프로젝트에서는 npm run test:cov가 jest.config.ts를 읽어 커버리지를 측정하고, coverage 폴더에 HTML 리포트를 만듭니다.
• coverageThreshold에서 디렉터리 기준은 파일을 합쳐서, glob 기준은 파일마다 판정하며, 양수는 최소 비율, 음수는 최대 미실행 항목 수입니다.
• 임계값은 커버리지가 떨어지는 것을 막는 최소선일 뿐이며, 빠진 경로가 어떤 업무 위험인지와 단언이 결과를 확인하는지는 따로 검토합니다.

연습 문제

1. 디렉터리 기준과 glob 기준

라인 임계값만 본다고 가정합니다. 한 디렉터리 안의 파일 A는 10줄 가운데 9줄을, 파일 B는 1줄 가운데 0줄을 실행했습니다. 디렉터리 기준의 최소선을 80%로 두면 통과할까요? 같은 두 파일을 glob으로 각각 80% 이상 요구하면 결과가 같을까요? 나머지 global 대상은 5줄 가운데 4줄을 실행했고, 다른 지표와 기준은 모두 충족한다고 가정합니다.

2. 음수 임계값

global에 branches: -10을 설정했습니다. 측정해 보니 계측된 분기 50개 가운데 38개가 실행되었습니다. 이 설정은 통과할까요? 같은 결과에서 branches: 75로 바꾸면 어떻게 될까요?

3. 단언 없는 100%

AppService 테스트를 다음처럼 바꾸었습니다. it('sum', () => { service.sum(1, 2); }); 커버리지 리포트에서 app.service.ts의 라인 커버리지는 어떻게 될까요? 누군가 sum()을 실수로 a - b로 바꾸면 이 테스트는 어떻게 될까요?

다음 글 지속적 통합(CI)에 테스트 통합에서는 지금까지 작성한 테스트와 커버리지 검사를 GitHub Actions 같은 CI 파이프라인에 연결합니다.