테스트란 무엇이며 왜 필요할까요

Claude Code가 코드를 수정한 뒤 "테스트가 통과했습니다"라고 말했습니다. 이 짧은 문장 뒤에는 확인 코드가 담긴 파일, 실행 명령, 구체적인 결과가 있습니다. 먼저 테스트의 종류와 직접 확인할 수 있는 내용을 살펴본 뒤, 자동 테스트가 무엇이고 결과가 의미하는 바를 알아보겠습니다.

점수 적립을 다루는 작은 예제면 충분합니다. 테스트 라이브러리를 미리 알 필요는 없습니다. 먼저 시나리오를 직접 따라가고, 그다음 자동 테스트의 기대값을 정리하고 실행 결과를 읽어 보겠습니다.

테스트의 종류

테스트는 프로그램이 어떻게 동작하는지, 요구사항을 충족하는지, 어디에서 문제가 생기는지 확인하는 데 도움이 됩니다. 예를 들어 점수가 제대로 적립되는지, 빈칸이 있는 신청서를 제출할 수 있는지, 오류 메시지가 이해하기 쉬운지 살펴볼 수 있습니다. 확인할 조건을 정하고, 동작을 수행한 다음 결과를 살펴봅니다.

테스트는 여러 기준으로 나눌 수 있습니다. 먼저 누가 동작을 수행하고 결과를 확인하는지부터 보겠습니다.

• 수동 테스트 - 사람이 직접 절차를 진행하고 결과를 평가합니다.
• 자동화 테스트 - 일부 확인 작업을 프로그램에 맡깁니다. 프로그램이 정해진 동작을 수행하고 결과를 비교합니다. 이런 검사를 보통 자동 테스트라고 부릅니다.

이 구분은 수행 방법에 따른 것입니다. 또 다른 질문도 있습니다. 정확히 무엇을 확인하는가입니다. 기능 테스트는 동작을 확인합니다. 예를 들어 정해진 점수가 적립되었는지 살펴보죠. 비기능 테스트는 애플리케이션의 특성을 확인합니다. 응답 속도나 사용 편의성이 예입니다. 두 기준은 서로 독립적입니다. 같은 기능을 수동으로도, 자동으로도 테스트할 수 있습니다.

자동화한다고 해서 사람의 역할이 사라지는 것은 아닙니다. 여전히 유용한 시나리오를 고르고, 기대 결과를 정하고, 발견된 차이가 무엇을 뜻하는지 살펴봐야 합니다. 반복되는 작업을 프로그램이 대신할 뿐입니다.

수동 테스트란 무엇인가요

수동 테스트에서는 직접 동작을 수행하고 결과가 기대와 맞는지 확인합니다. 테스트 코드를 작성할 필요는 없습니다. 명확한 조건과 답을 알고 싶은 질문이 있으면 됩니다.

예를 들어 학습용 포털에서 일치 항목 하나마다 10점을 준다고 합시다. 세 항목이 일치하면 30점입니다. 직접 확인하려면 이렇게 하면 됩니다.

1. 포털의 알맞은 버전을 열고, 보상 적립 이력이 없는 잔액 0점 사용자를 준비합니다.
2. 세 항목이 일치하는 신청서를 만들고 한 번 제출합니다.
3. 제출 후 잔액을 확인합니다. 기대값은 30점입니다.
4. 실제 결과를 기록합니다. 다른 값이 나왔다면 재현 절차와 필요한 경우 스크린샷도 남깁니다.

처음 잔액이 중요한 이유가 여기 있습니다. 이미 20점이 있었다면 적립 후 기대하는 값은 30점이 아니라 50점입니다. 시작 조건이 없으면 올바른 결과를 오류로 착각하거나 그 반대가 될 수 있습니다.

확인 결과는 짧게 적어 두면 편합니다. "제출 전 잔액 0점, 일치 항목 세 개, 한 번 제출, 기대값 30점, 실제값 3점." 이렇게 적으면 다른 사람이나 Claude Code도 무엇을 재현해야 할지 알 수 있습니다. "점수가 이상하게 동작한다"는 말만으로는 설명이 부족하죠.

수동 테스트는 탐색형으로 진행할 수도 있습니다. 애플리케이션을 살펴보면서 새로운 확인 방법을 떠올리는 방식입니다. 예를 들어 제출한 뒤에도 버튼이 활성화된 것을 보고 다시 눌러 보기로 할 수 있습니다. 모든 단계가 미리 정해져 있지는 않지만, 동작을 이해하고 발견한 문제를 기록한다는 목표는 있습니다. 그냥 여기저기 눌러 보는 것과는 다릅니다.

도구를 써도 괜찮습니다. 브라우저 콘솔을 열고 서버 응답을 확인하거나, 스크린샷을 찍거나, 확인 항목을 목록으로 관리할 수 있습니다. "수동"이라는 말은 사람이 테스트를 진행하고 결과를 평가한다는 뜻이지, 도구 없이 해야 한다는 뜻은 아닙니다.

새로운 동작을 탐색하거나 인터페이스가 이해하기 쉬운지 평가할 때는 수동 확인이 편합니다. 이미 정리된 동작과 비교를 여러 번 반복해야 한다면 자동화가 유용합니다. "인터페이스는 수동으로만, 계산은 코드로만"처럼 딱 잘라 나눌 수는 없습니다. 브라우저 동작도 자동화할 수 있고, 계산은 직접 확인할 수도 있습니다.

자동 테스트 실행 버튼을 누르면 그 뒤의 확인 작업은 프로그램이 수행하므로 수동 테스트가 아닙니다. 반대로 Claude Code가 단계 목록을 작성하고, 직접 포털에서 따라 해 결과를 평가했다면 수동 테스트입니다. 에이전트는 준비를 도운 셈이죠.

자동 테스트란 무엇인가요

계산기를 확인한다고 생각해 보세요. 2 + 2를 입력하기 전에 답이 4라고 예상하고, 화면에 나온 숫자와 비교합니다. 5가 나오면 이 예제의 결과가 틀렸다는 것을 알 수 있습니다. 계산기에 무엇이 표시되든 정답은 이미 알고 있으니까요.

자동 테스트는 비슷한 일을 프로그램으로 수행합니다. 시작 조건을 설정하고, 동작을 실행하고, 결과를 확인하는 작은 프로그램입니다. 사람이 하던 비교를 코드가 대신합니다. 앞으로는 이런 자동 테스트를 간단히 테스트라고 부르겠습니다.

보상 포털로 돌아가 보죠. 일치 항목 하나에 10점이므로 세 개가 일치하면 30점입니다. 확인 절차를 말로 적으면 다음과 같습니다.

1. 일치 항목 수를 3으로 설정합니다.
2. 보상 점수를 계산합니다.
3. 보상 점수가 30인지 확인합니다.

이것이 테스트 하나가 됩니다. 미리 답을 알고 있는 예제와 기대값이 들어 있죠. "일치 항목 하나당 10점"이라는 규칙은 이 학습용 포털에 해당합니다. 다른 애플리케이션에서는 다를 수 있습니다.

테스트가 사용자에게 몇 점을 줘야 하는지 스스로 정하지는 않습니다. 누군가 요구사항에서 규칙을 가져와 기대값으로 적어야 합니다. 개발자가 할 수도 있고 Claude Code에 요청할 수도 있지만, 기대값이 작업 내용과 맞는지 확인하는 일은 여전히 필요합니다.

왜 확인을 반복할까요

점수 적립을 한 번 수동으로 확인하는 것은 어렵지 않습니다. 문제는 나중에 생깁니다. 새 보상 종류를 추가하거나 신청서 처리를 바꾸거나, 에이전트에게 함수를 단순화해 달라고 요청할 수 있습니다. 이런 변경을 할 때마다 같은 질문이 생깁니다. 일치 항목이 세 개면 여전히 30점이 나오나요?

매번 신청서를 새로 만들고 동작을 수행한 뒤 결과를 볼 수도 있습니다. 또는 확인 절차를 코드로 적어 두고 다시 실행할 수 있습니다. 준비 조건이 같으면 테스트가 정해 둔 동작과 비교를 반복합니다. 어디를 눌러야 하고 무엇이 정답인지 매번 설명할 필요가 없습니다.

프로젝트가 커지면 규칙도 늘어납니다. 일치 항목이 없는 신청서는 점수를 더하면 안 되고, 같은 신청서를 두 번 계산하면 안 되며, 보상 목록은 정해진 순서여야 합니다. 테스트를 함께 실행하면 변경 후 어떤 기대값이 더 이상 충족되지 않는지 볼 수 있습니다.

자동화의 장점은 이미 설명한 동작을 다시 확인할 때 수작업이 줄어든다는 점입니다. 테스트 작성에도 시간이 들고 요구사항이 바뀌면 수정해야 합니다. 그래도 자주 되짚는 규칙이라면 반복 실행을 통해 그 수고를 만회할 수 있습니다.

테스트 파일은 어디에 있을까요

테스트는 프로젝트의 일반 파일로 저장됩니다. 작은 JavaScript 프로젝트라면 확인 코드를 그것이 호출하는 코드 옆에 두면 편합니다.

reward-example/
├── package.json
└── src/
    ├── reward-flow.js
    └── reward-flow.test.js

reward-flow.js에는 보상 점수 계산이 들어 있습니다. reward-flow.test.js에는 계산 함수를 호출하고 결과를 확인하는 코드가 있습니다. package.json은 테스트 명령을 포함해 프로젝트 설정과 명령을 설명합니다.

파일 이름에 있는 .test.js를 보면 테스트 파일이라는 점을 알 수 있습니다. JavaScript 언어의 규칙이 아니라 테스트 도구에서 지원하는 관례입니다. 다른 프로젝트에서는 이름이 다르거나 tests/라는 별도 폴더를 쓰기도 합니다. 파일 하나에 테스트 여러 개를 넣을 수도 있으므로, 소스 파일마다 테스트 파일을 하나씩 둘 필요는 없습니다.

Claude Code가 처음 보는 프로젝트에서 작업한다면, 먼저 기존 점수 적립 테스트를 찾아 경로를 알려 달라고 요청해 보세요. 모든 폴더 구조를 아직 파악하지 못했더라도 테스트와 확인하려는 동작을 연결할 수 있습니다.

의도를 확인 절차로 바꾸기

"점수 적립을 고치고 테스트로 확인해 주세요"라는 요청만으로는 에이전트가 두 가지를 알기 어렵습니다. 올바른 계산이 무엇인지, 결과를 무엇으로 확인해야 하는지죠. 먼저 원하는 동작부터 설명해 보세요. 예를 들면 "일치 항목 하나당 10점입니다. 세 항목이 일치하면 보상은 30점이어야 합니다."라고 할 수 있습니다.

코드를 한 줄도 쓰지 않고도 이 의도를 확인 절차로 바꿀 수 있습니다. 세 가지를 정리하면 됩니다.

한 문장으로 읽으면 이렇습니다. "세 항목이 일치하면 보상 계산 결과는 30점이어야 합니다." 테스트의 의미를 논의하기에 충분한 정보입니다. 이 프로젝트에서 확인 코드를 어떻게 작성할지는 에이전트가 알아볼 수 있습니다.

무엇을 확인하려는지 정확히 고르는 것이 중요합니다. "보상 점수가 30으로 계산된다"와 "사용자 잔액이 30점이 된다"는 서로 다른 기대입니다. 두 번째를 확인하려면 위의 수동 테스트처럼 처음 잔액과 적립 동작도 필요합니다. 그러니 "점수를 확인해 주세요" 대신 관찰할 결과를 분명히 적어 주세요.

이제 주변 상황도 생각해 보세요. 이 규칙이라면 작은 표부터 시작해도 충분합니다.

처음부터 수십 가지 경우를 생각해 낼 필요는 없습니다. 문제가 된 시나리오와 변경으로 영향을 받을 수 있는 주변 사례 몇 개부터 확인하세요. 예를 들어 신청서를 다시 제출했을 때 어떻게 되어야 하는지 불분명하다면 먼저 규칙부터 명확히 하세요. 에이전트가 방안을 제안할 수는 있지만, 그것만으로 기대값이 합의된 것은 아닙니다.

Claude Code에 테스트 맡기기

기대하는 동작을 정했다면 그에 맞춰 작업을 진행할 수 있습니다. 먼저 에이전트가 프로젝트에 이미 있는 테스트를 확인하고, 여러분의 시나리오와 비교하게 하세요. 필요한 테스트가 이미 있을 수도 있습니다. 그런 경우에는 실제로 실행하고 결과를 읽어야 합니다. 없다면 에이전트가 테스트를 추가해야 합니다.

첫 요청은 다음처럼 작성할 수 있습니다.

보상 점수 계산을 수정해 주세요.
규칙: 일치 항목 하나당 10점입니다.
확인할 사례: 일치 3개는 30점,
0개는 0점, 5개는 50점입니다.

수정하기 전에 이 사례를 확인하는 기존 테스트를 찾아 주세요.
이미 확인되는 내용과 빠진 부분,
추가하거나 수정할 테스트를 간단히 설명해 주세요.
요구사항이 불명확하면 알려 주세요.
아직 파일은 수정하지 마세요.

답변은 앞으로 만들 결과에 대한 설명으로 읽어 보세요. 모든 숫자가 여러분의 규칙에서 나온 것인가요? 보상 점수 자체를 확인하나요, 아니면 다른 것을 확인하나요? 현재 동작에 맞추려고 규칙까지 바꾸자는 제안은 없나요? 이 단계에서는 요구사항을 구체화하면 되므로 테스트 구현 코드를 읽지 않아도 됩니다.

시나리오를 정한 다음에는 실제 작업을 맡깁니다.

논의한 규칙에 따라 보상 계산을 수정해 주세요.
합의한 사례 중 빠진 테스트를 추가하고,
프로젝트에서 사용하는 도구를 따라 주세요.
테스트 실행을 통과시키려고 기존 기대값을 바꾸지 마세요.
기대값이 틀렸다고 생각한다면 먼저 이유를 설명해 주세요.

프로젝트 지침에 따라 필요한 테스트를 실행해 주세요.
명령어, 작업 폴더, 실제 출력을 보여 주세요.
세 사례 각각 어떤 테스트가 확인했는지,
그리고 결과가 어땠는지 적어 주세요.
건너뛰었거나 실행하지 못한 테스트는 따로 나열해 주세요.

에이전트는 프로젝트 문서와 설정에서 실행 명령을 찾습니다. JavaScript 프로젝트에서는 npm test를 자주 씁니다. npm은 package.json 파일의 scripts.test 필드에 지정된 명령을 실행합니다. 이 명령이 실제로 어떤 테스트를 실행하는지는 프로젝트마다 다를 수 있습니다. 여러분이 할 일은 필요한 시나리오가 실행에 포함되었는지 확인하는 것입니다.

테스트를 작성하는 것과 실행하는 것은 서로 다른 단계입니다. "테스트 세 개를 추가했습니다"라는 말은 파일이 바뀌었다는 뜻일 뿐입니다. 결과를 판단하려면 실제로 실행해야 합니다. 예를 들어 의존성이 없어 실행할 수 없다면, 에이전트가 원인과 실행하지 못한 테스트를 알려야 합니다.

답변에서 "우리 시나리오 → 구체적인 테스트 → 결과"가 연결되는지 확인하세요. 논의한 세 사례 중 하나만 실행했다면 확인된 것도 하나뿐입니다. 마지막 줄이 초록색이어도 마찬가지입니다.

결과 읽기

아래는 Node.js 20.18.0과 npm 10.8.2에서 학습용 테스트 하나를 실제 실행한 결과입니다. 앞서 제안한 시나리오 전체가 아니라, 세 항목이 일치할 때의 보상 계산만 확인합니다. 읽기 쉽도록 시간과 보고서의 부가 출력은 뺐습니다.

> reward-example@1.0.0 test
> node --test --test-reporter=tap

# Subtest: three matches give 30 points
ok 1 - three matches give 30 points

# tests 1
# suites 0
# pass 1
# fail 0
# cancelled 0
# skipped 0
# todo 0

처음 두 줄은 패키지와 실행한 명령을 보여 줍니다. 그 아래에는 테스트 이름이 나옵니다. ok 1은 1번 테스트가 통과했다는 뜻이고, 실패한 테스트는 not ok로 시작합니다. pass 1과 fail 0은 테스트 하나가 통과했고 실패한 테스트는 없다는 의미입니다. 터미널에서 색을 표시하지 않아도 이런 결과를 "초록색"이라고 부릅니다.

오류가 있는 경우에는 규칙상 30점이어야 하는데 세 항목의 보상으로 3점이 나옵니다. 같은 테스트에서 다음과 같은 일부 출력이 표시됩니다. 여기서는 경로, 호출 스택, 시간, 일부 부가 출력은 생략했습니다.

not ok 1 - three matches give 30 points
  error: |-
    Expected values to be strictly equal:

    3 !== 30

  code: 'ERR_ASSERTION'
  name: 'AssertionError'
  expected: 30
  actual: 3
  operator: 'strictEqual'

# tests 1
# pass 0
# fail 1
# cancelled 0
# skipped 0
# todo 0

먼저 테스트 이름을 찾고 expected와 actual을 비교하세요. 각각 "기대값"과 "실제값"입니다. 여기서는 30점을 기대했지만 3점이 나왔습니다. fail 1은 테스트 하나가 실패했다는 최종 결과입니다.

이 실패는 실제 결과가 기록된 기대값과 일치하지 않았다는 뜻입니다. 다음으로 원인을 찾아야 합니다. 계산 오류인지, 시작 데이터가 잘못됐는지, 테스트의 기대값이 틀렸는지 확인하세요. 보고서를 통과시키려고 테스트의 숫자만 바꾸면 안 됩니다. 먼저 작업의 규칙과 대조해야 합니다.

다른 이유로 실패할 수도 있습니다. 예를 들어 테스트가 함수 파일을 불러오지 못하면 점수를 비교하는 단계까지 도달하지 않습니다. 이 경우 보고서에 해당 테스트 이름이 없고 파일 전체가 실패로 표시될 수도 있습니다. 따라서 fail 1 한 줄만 보고 "계산이 틀렸다"고 결론 내릴 수는 없습니다. 요약 위에 있는 메시지도 확인하세요.

건너뛴 테스트

테스트에는 또 다른 중요한 상태가 있습니다. 확인 작업을 건너뛰도록 표시할 수 있습니다. Node.js에서는 예를 들어 test.skip을 사용합니다. 이 테스트는 실행되지 않습니다. 보고서에 이름이 있다고 해서 시나리오를 확인한 것은 아닙니다.

예제를 별도로 실행했을 때 건너뛴 테스트는 다음 줄과 요약으로 표시됩니다.

ok 1 - three matches give 30 points # SKIP

# tests 1
# pass 0
# fail 0
# cancelled 0
# skipped 1
# todo 0

여기서 눈여겨볼 점이 있습니다. 줄이 ok로 시작하지만 끝에는 # SKIP이 붙어 있습니다. 이 형식은 이렇게 건너뛴 테스트를 표시합니다. 첫 단어만 보고 판단하면 안 됩니다. 요약의 pass 0은 통과한 테스트가 없다는 뜻입니다.

같은 시나리오를 세 가지 상태로 실행한 결과를 정리해 보겠습니다.

규모가 큰 보고서에는 다른 항목도 있습니다. 여기서 실행한 결과에서는 cancelled와 todo가 0입니다. 0이 아닌 값이 보이면 어떤 테스트가 취소되었거나 미완료로 표시되었는지 확인하고, 성공적으로 확인된 항목에 포함하지 마세요. suites는 테스트 그룹을 가리킵니다. 이 예제에는 그룹이 없습니다.

사소한 점이 하나 더 있습니다. 보고서에 테스트가 0개라고 표시되면 실패가 없더라도 점수 적립이 확인된 것은 아닙니다. 필요한 테스트가 실행 대상에 포함되지 않았을 수 있습니다. 터미널 색에 대한 전반적인 인상보다 시나리오 이름과 실행된 테스트 수가 더 중요합니다.

초록색 결과가 의미하는 것

이 보고서의 테스트가 답한 질문은 좁습니다. "세 항목이 일치할 때 보상 점수가 올바르게 계산되나요?" 일치 항목이 0개인 경우, 신청서 재제출, 페이지에 표시되는 점수는 확인하지 않았습니다. 요청에 언급했다는 이유만으로 그 사례까지 테스트된 것은 아닙니다.

일치 항목이 없는 경우를 확인하려면 기대값 0인 시나리오가 하나 더 필요합니다. 신청서 재제출을 확인하려면 실제로 다시 제출하는 동작과 그 결과를 설명해야 합니다. 테스트는 주변 코드만 보고 이런 규칙을 알아내지 못합니다. 테스트에 기록된 내용만 확인합니다.

테스트가 없는 것과 테스트를 건너뛴 것은 다릅니다. 건너뛴 테스트는 보고서의 skipped에서 확인할 수 있습니다. 반면 테스트 자체를 작성하지 않은 시나리오는 보통 보고서에 나오지 않습니다. 확인되지 않은 동작에 오류가 있어도 기존 테스트는 모두 통과할 수 있습니다.

마지막으로 비교가 성공했다고 해서 기대값 자체가 올바른 것은 아닙니다. 우리 규칙에 맞지 않게 30 대신 3을 기대값으로 적고 계산 결과가 3이면 테스트는 통과합니다. 그러므로 테스트를 논의할 때는 어떤 동작을 확인하는지, 기대 결과는 어디서 가져왔는지 두 가지를 살펴보세요.

"테스트가 통과했습니다"라는 말은 그 한계를 이해하고 있을 때 유용합니다. 특정 실행에서 특정 테스트가 성공했다는 뜻입니다. "애플리케이션에 오류가 더는 없다"고 보장하는 말은 아닙니다.