새솔CRM은 8개월 동안 커밋 516개, 코드 3.3만 줄 규모로 자라났다. 기능이 하나씩 늘어날수록 마음 한구석엔 늘 같은 불안이 있었다 — “이번에 고친 게, 저 멀리 있는 다른 기능을 조용히 망가뜨리진 않았을까?” 실제로 로그인 화면을 손보다가 사이드바 메뉴가 통째로 사라진 사고를 겪은 뒤, 이 불안을 사람의 기억력이 아니라 기계의 반복 작업에 맡기기로 했다. 그렇게 만든 것이 자동 회귀 테스트, 그중에서도 가벼운 버전인 스모크 테스트다. 지금은 서버 API를 찌르는 검사와, 실제 크롬 화면으로 클릭해보는 검사까지 두 겹으로 갖춰진 상태다.

1. “회귀”라는 사고는 왜 일어나는가

개발에서 회귀(regression)란, 새 기능을 추가하거나 기존 코드를 수정했을 때 그 여파로 예전엔 멀쩡하던 다른 기능이 조용히 망가지는 현상을 말한다. 문제는 이게 늘 예상 밖의 곳에서 터진다는 점이다.

문제는 이런 연결고리를 사람이 매번 머릿속으로 추적하는 게 사실상 불가능하다는 것이다. 그래서 발상을 바꿨다. “수정 후에도 반드시 정상 작동해야 할 핵심 기능 목록”을 미리 정해두고, 그 목록을 사람이 아니라 컴퓨터가 코드를 고칠 때마다 자동으로 검사하게 만들면 된다.

2. 공장 검수 라인에 비유하면

이 구조는 사실 새로운 개념이 아니다. 공장의 출고 전 검수 과정과 뼈대가 완전히 같다.

비유가 특히 잘 들어맞는 지점이 하나 더 있다. 불량이 자주 나오던 공정에 검수 항목을 추가하는 것처럼, 실제 사고(버그)가 한 번 터지면 그 지점을 새로운 검사 항목으로 추가한다는 점이다. 그래서 체크리스트는 한 번 만들고 끝나는 게 아니라, 시간이 지날수록 점점 촘촘해지는 살아있는 문서가 된다.

“스모크 테스트”라는 이름 자체는 하드웨어 업계에서 유래했다고 알려져 있다. 전자기기의 전원을 처음 넣었을 때 “일단 연기(smoke)가 나지 않으면 합격”이라고 하던 관행에서 따온 이름이다. 전체를 샅샅이 검사하는 게 아니라, 핵심 몇 가지가 배포 후에도 여전히 살아있는지를 몇 초 만에 빠르게 확인하는 가벼운 검사라는 뜻이다.

3. 왜 지금 필요했나

새솔CRM은 업체관리·일정·할일 같은 CRM 기본기 위에, 홈택스/위택스 자동 수집, 알림톡·이메일 발송, 양도·증여세 계산 의견서, 상담 녹음·전사·AI 의견서, 전자서명 계약, 블로그 자동화까지 얹힌 시스템이다. 기능이 이만큼 쌓인 상태에서 기존 방식은 한계가 뚜렷했다.

4. 실제로 어떻게 만들었나

새솔CRM에 구축한 스모크 테스트는 크게 세 부분으로 이루어진다.

① tests/smoke-api.js — API 검사 11건 (약 2초)

전부 읽기 전용으로, 운영 데이터를 건드리지 않는다.

검사 기법은 크게 두 가지가 쓰였다.

② tests/smoke-browser.js — 브라우저 검사 8건 (약 1~2분)

(a)가 “서버가 정상 응답하는가”를 본다면, 이건 한 단계 더 들어가 “실제 화면이 사람 눈에 정상적으로 보이는가”를 검사한다. 헤드리스 크롬으로 로그인부터 화면 렌더까지 전 과정을 자동으로 따라가는 E2E(End-to-End) 방식이다.

③ scripts/smoke-test.bat — 더블클릭 한 번

비개발자도 사용할 수 있도록, 더블클릭만 하면 서버에 접속해서 검사를 실행하고 결과를 보여주는 실행 파일이다. 코딩 지식이 없어도 “지금 앱 상태 괜찮나?” 싶을 때 바로 확인할 수 있다. 지금은 [1/2] API 검사 → [2/2] 브라우저 검사 순으로 두 종류를 한 번에 실행하도록 연동되어 있다.

④ 운영 규칙 문서화

프로젝트 인프라 문서(CLAUDE.md)에 “배포 후·커밋 전 스모크 테스트 필수 실행” 규칙을 명문화했고, 여기에 “프론트엔드 수정 작업 후에는 브라우저 테스트도 추가 실행”이라는 규칙도 더해졌다. 규칙으로 박아두면 이후 어떤 작업 세션이든 자동으로 이 절차를 따르게 된다. 메뉴가 추가되거나 세법 개정으로 계산 정답이 바뀌는 경우, 테스트 코드 자체도 함께 갱신해야 한다는 안내도 같이 넣어두었다.

5. 언제, 누가, 어디서 실행하는가

저장 위치는 프로젝트 코드와 동일하게 git으로 관리된다. tests/, scripts/ 폴더에 위치하며, 커밋·푸시하면 사무실 PC든 집 PC든 어느 작업 환경에서나 동기화되어 동일한 위치에 존재한다.

배포 워크플로우 안에서의 위치는 다음과 같다.

왜 하필 이 순서인가 — “배포”가 뭘 의미하는지에 따라 갈린다

사실 이 순서를 두고 한 차례 헷갈린 적이 있다. Claude Code가 처음 제안한 순서는 “스모크 테스트 → SCP 배포”였는데, 앞서 정리한 워크플로우는 “서버 배포(재시작) → 스모크 테스트”로 정반대였기 때문이다. 정리해보니 둘 다 틀린 게 아니라, 코드 원본이 어디에 있느냐에 따라 자연스럽게 달라지는 거였다.

6. 스모크 테스트가 커버하지 못하는 것

자동 테스트가 만능은 아니다. “숫자가 맞는지, 요소가 존재하는지, 에러 없이 응답이 오는지”처럼 기계적으로 판별 가능한 것만 검증할 수 있다. 결과 화면이 시각적으로 예쁘게 보이는지, 사용성이 자연스러운지 같은 감각적 판단은 여전히 사람이 눈으로 확인해야 한다.

그래서 자동화 이후에도 사람이 완전히 손을 떼는 게 아니라, 반복적이고 기계적인 확인은 자동화하고 최종적인 눈으로 보는 확인만 가볍게 하는 구조로 역할이 나뉜다.

7. 실제 적용 결과 — (a)+(b) 완전체

새솔CRM에 이 체계를 처음 도입했을 때는 (a) API 검사 11건이 전체 통과(✅)로 확인되며 시작됐다. 이후 (b) 브라우저 검사 8건이 추가로 구축되면서, 서버 응답만 보던 검사가 실제 화면 렌더링과 자바스크립트 에러까지 보는 검사로 한 단계 깊어졌다. 이 역시 첫 실행에 8건 전체가 통과했고, 마침 그날 진행 중이던 리팩토링 2건이 실제 브라우저에서 정상 동작하는지를 곧바로 검증하는 데 쓰였다.

두 검사는 역할이 다르다. (a)는 코딩 작업 후 매번 필수로 돌리는 빠른 1차 관문이고, (b)는 프론트엔드를 수정했을 때 추가로 돌리는 정밀 검사다. scripts/smoke-test.bat 하나로 둘 다 순서대로 실행되도록 연동되어 있고, CLAUDE.md에 규칙으로 명문화되어 있어 앞으로 어떤 작업 세션이든 자동으로 이 절차를 따르게 된다. 이제 이 시스템은 어떤 코드 수정이 있더라도, 배포 직후 자동으로 최대 19건의 검사를 거친 뒤에만 최종 커밋되는 구조로 운영된다.

컴퓨터공학 배경 없이 vibe coding으로 시작한 프로젝트가, 어느새 스스로를 검증하는 이중 안전망까지 갖추게 된 셈이다. 다음에 사이드바 메뉴가 사라지거나 화면이 하얗게 뜨는 사고가 다시 일어난다면, 이번엔 사람이 클릭해서 발견하기 전에 몇 초에서 몇 분짜리 스크립트가 먼저 알아챌 것이다.

※ 이 글은 새솔CRM 개발 과정에서 실제로 구축한 자동 회귀 테스트(스모크 테스트) 체계를 정리한 기록입니다.