솔직히 말하면, 저희 팀에도 API 자동 테스트는 있었습니다. 하지만 "있긴 한데 쓰기 불편한" 상태였죠.
테스트 시나리오는 어디에 있는지, 무엇을 실행해야 하는지, 명령어는 어떻게 작성하는지, 환경 전환은 어떻게 하는지, 실행 후 리포트는 어떻게 보는지? 이런 사소한 단계들이 쌓여서 리그레션 테스트는 "가볍게 할 수 있는 일"에서 "따로 시간을 내야만 할 수 있는 일"로 바뀌어 버렸습니다.
이 글에서는 제가 실제로 로컬 환경에서 운용하고 있는 워크플로우를 소개합니다. Apidog의 자동 테스트 자산(시나리오/테스트 스위트)과 Claude의 터미널 기능을 결합하여, "API 자동 테스트 실행"을 자연어 한 마디로 끝내는 방법입니다:
"Run regression testing for 01_e2e_happy_path in the dev environment. Once completed, summarize the results with these 4 points: pass rate, failed test cases, estimated cause of failure, and suggested fix procedures."
Claude Code가 자동으로 Claude Skills와 매칭하여, 해당 테스트를 특정하고 Apidog CLI를 실행합니다. 마지막으로 결과를 읽기 쉬운 결론으로 요약해 줍니다. 이 조합은 특히 API 자동 테스트, 리그레션 테스트, 그리고 테스트를 일상적인 개발 흐름에 통합하는 데 적합합니다.
왜 API 자동 테스트를 "자연어화"해야 할까요?
많은 팀에서 자동 테스트는 "실행 능력"은 충분하지만, "사용 편의성"이 부족합니다:
- 신입 개발자는 어떤 테스트가 가능한지, 무엇을 실행해야 하는지 모릅니다.
- CLI 명령어가 너무 길어서 환경 변수 등을 실수하기 쉽습니다.
- 테스트 실패 후 로그를 확인하거나 리포트를 보는 데 커뮤니케이션 비용이 듭니다.
- 커밋이나 병합(Merge) 전에 리그레션 테스트를 가볍게 실행하기 어렵습니다.
자연어로 트리거할 수 있다는 것의 가치는, "테스트 실행"의 장벽을 말 한 마디 하는 수준으로 낮추면서도, 전문 도구(Apidog)의 테스트 체계와 리포트 기능은 그대로 활용할 수 있다는 점에 있습니다.
전체 그림: Apidog × Claude 3가지 구성 요소의 역할 분담
이 워크플로우는 3가지 컴포넌트로 구성되어 있습니다:
- Apidog CLI: Apidog의 테스트 시나리오/테스트 스위트를 실행하고 CLI/HTML 리포트를 출력합니다.
- Claude Code: 터미널 내의 AI 어시스턴트로, 명령어 실행, 파일 조작, 스크립트 실행이 가능합니다.
- Claude Skills (Agent Skills): Claude에게 "실행 가능한 흐름"을 부여하여, 테스트 선택, 환경 전환, CLI 실행, 결과 요약 방법을 가르칩니다.
한 마디로 요약하면:
자연어 → Claude가 Skill과 매칭 → 스크립트를 호출하여 Apidog CLI 실행 → 출력 분석 → 결론 요약
준비 작업
Apidog CLI와 Claude Code를 실행하려면 먼저 Node 환경을 준비하고 설치를 완료해야 합니다.
1) 환경 요구 사항: Node.js
Node 18+ 또는 20+를 권장합니다. 터미널에서 확인하세요:
node -v
npm -v2) Apidog CLI 설치
npm install -g apidog-cli
apidog --version버전 번호가 표시되면 설치 성공입니다.
3) Claude Code 설치
npm install -g @anthropic-ai/claude-code
claude --version
claude # 첫 실행 시 프롬프트에 따라 로그인테스트 자산 정리: AI 생성 데모 앱을 예시로
이번에는 검증용으로 AI를 사용하여 간단한 EC 사이트 데모(로컬 환경 http://127.0.0.1:3001)를 만들었습니다. 이 데모 앱에 대해 "신뢰성"과 "안정적인 재현성"을 확인하기 위해 다음 2가지 테스트를 준비했습니다:
-
01_e2e_happy_path (E2E Happy Path)
메인 정상 흐름(로그인 → 상품 목록 → 주문 → 결제)입니다. 로컬 환경이 정상적으로 동작하고 있다면, 사용자가 쇼핑을 하는 일련의 흐름이 올바르게 기능함을 보증합니다. -
02_payment_should_fail (실패계 경계값 테스트)
특정 조건(예: 6000엔 이상의 주문에서 결제 에러가 되는 설정)에서의 실패 시나리오입니다. AI가 "테스트 실패"를 감지했을 때, 로그에서 원인을 올바르게 분석할 수 있는지 데모하기 위해 사용합니다.
왜 파일 이름이 중요할까요?
파일 이름에 "의미(컨텍스트)"를 포함시킴으로써, Claude는 모호한 자연어 지시에서도 적절한 테스트를 추론할 수 있게 됩니다.
예를 들어 02_payment_should_fail이라고 이름을 지어두면, 굳이 파일 이름을 정확하게 말하지 않아도 "결제 실패 패턴 확인해줘"나 "결제 쪽 리그레션 부탁해"라고 말하는 것만으로 Claude가 "아, 이거군요"하고 의도를 파악해 줍니다. 이것이 "대화로 테스트 실행"을 실현하는 요령입니다.
Claude Skills 구현: "테스트 실행 방법"을 리포지토리에 남기기
Claude Skills의 장점은 실행 흐름을 버전 관리 가능하고 리뷰 가능한 프로젝트 자산으로 바꿀 수 있다는 점입니다. 구전으로 흩어지지 않습니다.
최소한으로 사용할 수 있는 Skill 디렉터리는 대략 이런 느낌입니다:
.claude/skills/apidog-tests/SKILL.md: 트리거 조건 + 실행 흐름 (핵심)env/: 다른 환경의 token/envId (비밀 정보는 Git에 커밋하지 않음)tests/: 각 테스트마다 Markdown 파일 (CLI 명령어 저장)scripts/: CLI를 조립해서 실행 (컨텍스트와 수동 명령어 조립 비용 절감)
이 정리 방법이 가져오는 이점:
- Apidog는 테스트 시나리오/스위트의 유지보수를 계속합니다.
- Skill은 "선택 로직 + 환경 관리 + 실행 규범 + 출력 요약"을 담당합니다.
- 팀원들은 명령어를 외울 필요가 없고, 요건을 말할 수 있기만 하면 됩니다.
Apidog CLI: 실행 엔진, Skills는 "래핑과 자동화"만 담당
Apidog의 테스트 시나리오/스위트 페이지에서 CLI 명령어를 직접 복사할 수 있습니다(CI/CD 또는 CLI 영역).
전형적인 형식은 이런 느낌입니다:
apidog run --access-token <TOKEN> -t <SCENARIO_ID> -e <ENV_ID> -n 1 -r html,cli추천하는 방법은 명령어를 tests/*.md에 붙여넣고, 기밀 파라미터는 환경 변수로 관리하는 것입니다(유출을 피하고 환경 전환도 편리함).
한 마디로 API 자동 테스트 트리거: 템플릿으로 바로 사용
프로젝트 디렉터리에 들어가서 Claude Code를 실행합니다:
claude한 마디로 테스트를 돌릴 수 있습니다:
"Run regression testing for 01_e2e_happy_path in the dev environment. Once completed, summarize the results with these 4 points: pass rate, failed test cases, estimated cause of failure, and suggested fix procedures."
Claude가 해주는 일:
- 실행하고 싶은 테스트 시나리오/스위트(
01_e2e_happy_path)를 식별 - 환경(
dev)을 확인하고 대응하는 환경 변수를 로드 - 스크립트를 호출하여 Apidog CLI를 실행
- 출력을 지정된 4가지 관점에서 요약하여 구조화된 결론을 제시
출력이 더 "인간답게": 자동 요약은 로그를 보는 것보다 훨씬 빠르다
기존의 CLI 출력은 기계에게는 친절하지만, 인간에게는 친절하지 않습니다.
Claude Skills는 출력을 개발/테스트 협업에 적합한 요약으로 정리해 줍니다. 구체적으로는:
- 통과율: 전체 성공률을 한눈에 파악
- 실패한 테스트 케이스: 어떤 테스트가 떨어졌는지 명확하게
- 추정되는 실패 원인: 인증 에러, 환경 변수 문제, 어설션(Assertion) 실패, Mock 데이터 불일치 등
- 수정 절차 제안: 환경을 바꿔서 비교, 특정 모듈만 실행, 어설션 추가 등
이 단계가 "효율 향상"의 열쇠입니다. 동료가 몇 번이고 "지금 어떻게 됐어? 어디가 실패했어?"라고 물어볼 필요가 없습니다.
Claude의 요약을 채팅에 붙여넣기만 하면 다음 단계로 넘어갈 수 있습니다.
이 워크플로우의 핵심 장점
API 자동 테스트를 정말로 일상적인 개발에 통합하고 싶다면, 이 조합의 장점은 명확합니다:
- 장벽을 낮춤: 신입은 명령어를 외우거나 시나리오 ID를 찾을 필요 없이, 그냥 말하면 됩니다.
- 표준화 가능: 테스트 정의, 환경 변수, 실행 스크립트를 버전 관리하여 리포지토리에 축적합니다.
- 문제 확인이 빠름: 실패는 단순히 "빨간색"일 뿐만 아니라, 원인 설명과 수정 제안도 함께 따라옵니다.
- 흐름에 통합하기 쉬움: 커밋 전/병합 전 자동 리그레션으로 자연스럽게 확장할 수 있습니다.
자주 있는 확장 방향
- 복수 환경 비교 (dev vs test): 같은 테스트를 다른 환경에서 실행하여 차이점을 자동 비교
- Git 변경에 따른 테스트 필터링: 영향을 받는 모듈 관련 테스트만 실행하여 전체 리그레션 시간을 단축
- 커밋 전/병합 전 자동 리그레션: commit/PR 단계에서 중요한 테스트를 자동 실행하여 문제를 사전에 포착
요약
Apidog는 전문적인 API 자동 테스트 기능을 제공하고, Claude Skills는 자연어 구동과 실행 오케스트레이션 기능을 제공합니다. 둘을 결합한 가치는, "테스트 실행"을 전문적인 조작이 필요한 단계에서, 가볍게 할 수 있는 동작으로 바꾸는 것입니다.
API 자동 테스트의 사용 빈도를 높여서, 리그레션을 일상 개발의 일부로 만들고 싶다면, 이 Apidog × Claude 워크플로우는 시도해 볼 가치가 있습니다.
저 자신도 이 조합을 사용하기 시작한 후로, 테스트를 실행하는 심리적 장벽이 꽤 낮아졌습니다. "나중에 몰아서 하자"가 "지금 바로 확인하자"로 바뀌었죠. 이것이 AI 도구의 진짜 가치라고 생각합니다.
이 글이 도움이 되셨다면 꼭 공유해 주세요. 여러분의 팀에서도 비슷한 과제가 있다면 댓글로 알려주세요. 함께 해결책을 고민해 봅시다!
