타입스크립트 디버깅 기법

이전 절들에서는 Jest를 사용한 단위 테스트와 Cypress를 사용한 E2E 테스트를 통해 코드의 정확성을 검증하는 방법을 알아보았습니다.

하지만 아무리 철저하게 테스트를 작성하더라도, 애플리케이션 개발 과정에서는 예상치 못한 버그나 로직 오류가 발생하기 마련입니다.

이때 필요한 것이 바로 디버깅(Debugging)입니다.

디버깅은 소프트웨어의 오류(버그)를 찾아내고 수정하는 과정입니다.

타입스크립트는 컴파일 시점에 강력한 타입 검사를 제공하여 많은 오류를 미리 잡아주지만, 런타임에 발생하는 논리적 오류나 외부 시스템과의 연동 문제는 여전히 디버깅을 통해 해결해야 합니다.

이 절에서는 타입스크립트 프로젝트에서 효과적으로 디버깅을 수행하기 위한 다양한 기법과 도구들을 소개합니다.

타입 검사부터 소스맵 기반 중단점 디버깅, 실행 제어와 상태 관찰까지 이어지는 핵심 루프를 먼저 한 장으로 정리합니다.

브라우저 개발자 도구를 이용한 디버깅

프론트엔드 애플리케이션을 개발할 때는 웹 브라우저가 제공하는 개발자 도구가 가장 강력한 디버깅 도구입니다.

크롬, 파이어폭스, 엣지 등 대부분의 최신 브라우저는 유사한 기능을 제공합니다.

Sources 탭 활용

Sources 탭은 자바스크립트(타입스크립트) 코드를 실행 중에 디버깅하는 핵심 공간입니다.

• 원본 소스 코드 매핑 (Source Maps): 타입스크립트 코드는 브라우저에서 실행될 때 자바스크립트로 변환됩니다. 디버깅을 원활하게 하려면, 컴파일된 자바스크립트 코드와 원본 타입스크립트 코드를 연결해주는 소스 맵(Source Map)이 필수적입니다.
  • tsconfig.json 파일에서 sourceMap 옵션을 true로 설정해야 합니다.

    {
      "compilerOptions": {
        // ...
        "sourceMap": true, // 이 옵션을 true로 설정
        // ...
      }
    }

  • 대부분의 프론트엔드 빌드 도구(Webpack, Vite 등)는 기본적으로 소스 맵을 생성하도록 설정되어 있습니다.
• 중단점 (Breakpoints): 코드의 특정 라인에서 실행을 일시 중지시키는 지점입니다. 중단점이 활성화되면, 해당 라인에서 실행이 멈추고 현재 스코프의 변수 값, 호출 스택 등을 검사할 수 있습니다.
  • Sources 탭에서 코드 라인 번호를 클릭하여 설정/해제할 수 있습니다.
  • 조건부 중단점 (Conditional Breakpoints): 특정 조건이 만족할 때만 실행이 중지되도록 설정할 수 있습니다. (우클릭 -> Add conditional breakpoint)
  • 로그 포인트 (Logpoints): 실행을 멈추지 않고 특정 라인의 변수 값이나 메시지를 콘솔에 출력합니다. console.log를 코드를 수정하지 않고 사용할 때 유용합니다. (우클릭 -> Add logpoint)
• 실행 제어
  • Continue (F8): 다음 중단점까지 실행을 계속합니다.
  • Step Over (F10): 현재 라인을 실행하고 다음 라인으로 이동합니다. 함수 호출이 있으면 함수 내부로 들어가지 않고 함수 전체를 실행합니다.
  • Step Into (F11): 현재 라인을 실행하고 다음 라인으로 이동합니다. 함수 호출이 있으면 함수 내부로 들어갑니다.
  • Step Out (Shift + F11): 현재 함수 실행을 완료하고, 해당 함수를 호출했던 위치의 다음 라인으로 이동합니다.
• 스코프(Scope) 및 변수 검사: 중단점에서 멈췄을 때, Scope 패널에서 현재 스코프 내의 모든 변수와 그 값을 확인할 수 있습니다. Watch 패널에 특정 변수를 추가하여 지속적으로 감시할 수도 있습니다.
• 콘솔(Console) 활용
  • 디버깅 중 콘솔에서 현재 스코프의 변수 값을 직접 변경하거나, 함수를 실행해볼 수 있습니다.
  • console.log(), console.warn(), console.error(), console.table() 등을 활용하여 코드 실행 흐름과 변수 값을 출력할 수 있습니다.

VS Code를 이용한 디버깅 (Node.js/React)

VS Code는 Node.js 애플리케이션 및 React 애플리케이션을 위한 강력한 디버깅 환경을 내장하고 있습니다.

타입스크립트 코드도 직접 디버깅할 수 있어 매우 효율적입니다.

Node.js 애플리케이션 디버깅

launch.json 파일을 설정하여 Node.js 애플리케이션을 디버깅할 수 있습니다.

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program (TypeScript)",
      "skipFiles": ["<node_internals>/**"],
      "runtimeArgs": ["-r", "ts-node/register"], // ts-node를 사용하여 TypeScript 파일 직접 실행
      "args": ["${workspaceFolder}/src/index.ts"], // 실행할 엔트리 포인트 파일
      "cwd": "${workspaceFolder}", // 작업 디렉토리
      "console": "integratedTerminal", // 디버그 콘솔
      "sourceMaps": true // 소스 맵 사용
    }
  ]
}

React (Vite) 애플리케이션 디버깅

Vite로 생성된 프로젝트는 기본적으로 소스 맵을 포함하며, VS Code와 잘 통합됩니다.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch Chrome against localhost",
      "type": "pwa-chrome", // 또는 pwa-msedge
      "request": "launch",
      "url": "http://localhost:3000", // React 앱이 실행되는 URL
      "webRoot": "${workspaceFolder}/src",
      "sourceMapPathOverrides": {
        "webpack:///./src/*": "${webRoot}/*" // 번들러 소스 맵 경로 오버라이드 (필요 시)
      }
    }
  ]
}

로깅(Logging)을 이용한 디버깅

가장 기본적인 디버깅 기법은 console.log()와 같은 로깅 명령어를 사용하여 프로그램의 상태나 변수 값을 출력해보는 것입니다.

• 간단하고 빠름: 즉시 적용하여 결과를 볼 수 있습니다.
• 비침습적: 실행 흐름을 멈추지 않고 정보를 얻을 수 있습니다.

• console.log가 너무 많아지면 코드의 가독성을 해치고, 프로덕션 환경에 배포될 경우 성능 저하나 보안 문제를 야기할 수 있습니다.
• 복잡한 객체를 출력할 때는 console.dir()이나 console.table()을 사용하여 더 구조화된 출력을 얻을 수 있습니다.

function processData(data: string[]): number {
  console.log('--- Debugging processData ---'); // 함수 진입 시 로깅
  let sum = 0;
  for (const item of data) {
    const num = parseInt(item, 10);
    console.log(`Processing item: ${item}, parsed as: ${num}`); // 각 항목 처리 로깅
    if (isNaN(num)) {
      console.warn(`Warning: Invalid number encountered: ${item}`); // 경고 로깅
      continue;
    }
    sum += num;
  }
  console.log('Final sum:', sum); // 최종 결과 로깅
  console.log('--- End of processData ---');
  return sum;
}

타입스크립트 컴파일러 에러 활용

타입스크립트의 가장 큰 장점은 강력한 정적 타입 검사입니다.

컴파일 시점에 발생하는 에러 메시지를 이해하고 해결하는 것이 가장 효율적인 디버깅의 시작입니다.

• 명확한 에러 메시지: 타입스크립트 컴파일러(tsc)는 타입 불일치, 오타, 누락된 속성 등에 대해 매우 상세한 에러 메시지를 제공합니다.
• IDE의 실시간 피드백: VS Code와 같은 IDE는 타입스크립트 컴파일러와 통합되어 코드를 작성하는 즉시 에러를 표시하고 수정 가이드를 제공합니다.
• strict 모드 활용: tsconfig.json에서 strict: true를 설정하면 더 엄격한 타입 검사를 통해 잠재적인 런타임 오류를 미리 방지할 수 있습니다. (예: null 또는 undefined에 대한 엄격한 검사)

// 예시: 타입 오류를 통한 디버깅
interface Product {
  id: number;
  name: string;
  price: number;
}

function getProductName(product: Product): string {
  // return product.Name; // Error: Property 'Name' does not exist on type 'Product'. Did you mean 'name'?
  return product.name;
}

const myProduct = { id: 1, name: 'Laptop', cost: 1200 };
// getProductName(myProduct); // Error: Argument of type '{ id: number; name: string; cost: number; }' is not assignable to parameter of type 'Product'.
                            // Object literal may only specify known properties, and 'cost' does not exist in type 'Product'.

이러한 에러 메시지는 런타임에 발생할 수 있는 undefined 접근 오류나 논리적 실수를 사전에 방지해줍니다.

고급 디버깅 기법

• 조건부 로깅/디버깅: 특정 조건에서만 로깅을 활성화하거나 디버거를 실행하도록 설정합니다. (예: if (DEBUG_MODE) { console.log(...) })
• 네트워크 탭 (브라우저 개발자 도구): API 요청/응답의 상태 코드, 페이로드, 시간 등을 확인하여 백엔드 통신 문제를 디버깅합니다.
• 성능 탭 (브라우저 개발자 도구): 애플리케이션의 렌더링 성능, 자바스크립트 실행 시간 등을 프로파일링하여 성능 병목 현상을 찾습니다.
• Source Maps in Production: 프로덕션 환경에서도 소스 맵을 사용하여 사용자가 겪는 오류를 추적하고 디버깅할 수 있습니다. 다만, 보안상의 이유로 일반 사용자에게는 노출되지 않도록 설정하는 것이 중요합니다. (예: 특정 서버에서만 소스 맵 제공)

디버깅 요약

디버깅은 개발 과정에서 피할 수 없는 부분이며, 효율적인 디버깅 능력은 개발자의 생산성에 큰 영향을 미칩니다.

타입스크립트는 정적 타입 검사를 통해 많은 오류를 사전에 방지하지만, 런타임 버그는 여전히 발생할 수 있습니다.

브라우저 개발자 도구의 Sources 탭, VS Code의 통합 디버거, 그리고 전략적인 로깅은 타입스크립트 애플리케이션을 디버깅하는 데 가장 강력한 도구들입니다.

이러한 도구들을 능숙하게 활용하고, 타입스크립트 컴파일러의 경고와 에러 메시지를 적극적으로 활용하여 코드의 견고성을 높이는 것이 중요합니다.

디버깅은 버그 수정뿐 아니라 코드의 실행 흐름과 잠재적인 문제를 확인하는 과정입니다.

재현 조건, 관찰 지표, 수정 결과를 함께 기록해야 효과를 확인할 수 있습니다.

아래 다이어그램은 오류가 발생했을 때 타입 검사, 소스맵, 중단점, 네트워크/성능 탭 중 어떤 단서를 먼저 볼지 정리한 진단표입니다.

아래 다이어그램은 재현 조건을 고정한 뒤 타입 오류, 소스맵, 런타임 상태 중 어떤 증거를 먼저 확인할지 정리한 선택표입니다.

아래 다이어그램은 타입스크립트 디버깅 기법에서 브라우저 개발자 도구를 이용한 디버깅과 Sources 탭 활용을 검증 신호와 재현 절차 기준으로 연결합니다.

타입스크립트 디버깅은 타입 오류, 소스맵, 중단점, 네트워크 로그를 한 번에 열어두는 일이 아니라 재현 조건에 맞는 증거를 좁히는 과정입니다.

수정 뒤에는 같은 조건에서 실패가 사라졌는지 기록해 회귀 확인 기준으로 남깁니다.