본문으로 건너뛰기

인수조건을 계층별 테스트로 — test-layering-harness

홍승아20분

인수조건을 계층별 테스트로 나누고, 하나씩 승인받으며 추가하기

test-layering-harness는 제 Claude Code 플러그인 마켓플레이스(seungah-claude-plugins)에 올려 둔 단일 스킬 플러그인입니다. 인수조건(Acceptance Criteria, Given-When-Then)을 받아 어떤 테스트를, 어느 계층에, 어느 CI 단계에 둘지 계획하고, 계획 → 개별 → 최종의 세 번의 승인을 거쳐 테스트를 하나씩 만들어 넣습니다. 현재 버전은 0.8.0입니다.

제품 스펙 하네스가 기획 단계에서 인수조건까지 만들어 준다면, 이 하네스는 그 인수조건을 받아 실제로 돌아가는 테스트 스위트로 바꾸는 다음 단계를 맡습니다. 다른 플러그인에 의존하지 않으므로 인수조건만 있으면 혼자서도 동작합니다.

✍️ 한 줄 요약

AI가 테스트를 대신 써 주는 시대에 위험은 '작성 속도'가 아니라 '무엇을, 어느 층에서, 무엇을 정답으로 삼아 검증하느냐'로 옮겨 갑니다. 이 하네스는 인수조건을 방법론 × 계층 두 축으로 나눠 계획하고, 사람이 단계마다 승인하며, 만든 테스트를 실제로 돌려 결과를 확인합니다.

왜 만들었나

테스트를 '많이' 만드는 건 이미 쉽다

에이전트에게 "테스트 짜줘"라고 하면 테스트는 금방 나옵니다. 문제는 그다음입니다. 제가 겪은 실패는 대체로 세 가지였습니다.

  • 모든 인수조건이 E2E로 간다. 인수조건은 사용자 관점의 문장이라 그대로 옮기면 브라우저를 띄우는 테스트가 됩니다. 느리고, 잘 흔들리고, 실패했을 때 원인을 찾기 어려운 테스트가 위쪽에 쌓이는 '아이스크림 콘' 모양이 됩니다.
  • 스위트가 이름으로만 존재한다. 계획서에는 "smoke 3개, regression 10개"라고 적혀 있는데 코드에는 아무 표시가 없어서 smoke만 골라 돌릴 방법이 없습니다. 하네스에서는 이를 유령 스위트(phantom suite)라고 부릅니다.
  • 테스트가 버그를 정답으로 굳힌다. 셋 중 가장 위험한 실패입니다.

가장 큰 위험은 오라클 강도

테스트에서 '무엇이 성공인가'를 판정하는 기준을 오라클(oracle)이라고 합니다. 2025년 이후 연구들이 LLM 테스트 생성의 최대 위험으로 반복해서 지목하는 것이 바로 이 오라클이 약하거나 틀리는 문제입니다.

LLM은 명세(기대 동작)가 아니라 현재 구현이 실제로 내놓는 값을 보고 어서션을 적는 경향이 있습니다. 코드에 버그가 있으면 그 버그를 정답으로 박제한 테스트가 만들어지고, 그 테스트는 초록불을 켠 채로 버그를 숨깁니다. 게다가 LLM은 자기가 만든 오라클이 맞는지 가려내는 능력이 만들어 내는 능력보다 떨어집니다.

그래서 이 하네스가 하는 일은 세 가지로 요약됩니다. 테스트를 계층 택소노미로 분해하고, 매 적용을 사람이 승인하며, 오라클을 인수조건 기준으로 다시 검증하고 실제로 실행합니다.

두 개의 축: 방법론 × 계층

방법론 4가지

  • Smoke — 넓고 얕게. 배포 직후 "이 빌드가 더 테스트할 가치가 있나"를 판단하는 관문입니다.
  • Sanity — 좁고 깊게. 이 하네스에서는 변경과 관련된 페이지·컴포넌트를 PR 전에 돌리는 용도로 씁니다.
  • Regression — 넓고 깊게. 기존 기능이 깨지지 않았는지 확인합니다.
  • Nightly — 정해진 시각에 전부 돌리는 실행. 선택 실행이 놓친 부분을 메우는 안전망입니다.

여기서 하네스는 두 가지를 굳이 밝혀 둡니다.

첫째, ISTQB 공식 용어집에서 smoke와 sanity는 동의어입니다. "smoke는 넓고 얕게, sanity는 좁고 깊게"라는 구분은 현장의 관습일 뿐 표준이 아닙니다.

둘째, nightly는 테스트 유형이 아니라 '언제 돌리느냐'의 축입니다. ISTQB나 ISO 어디에도 nightly라는 테스트 유형은 없습니다.

하네스는 관습적인 이름을 그대로 쓰되, 이 사실을 계획서에 항상 함께 적습니다.

계층 3가지

  • Unit — "이 함수·판정 로직이 맞나?" 빠르고 싸며 원인을 정확히 짚지만, 여러 부분이 함께 동작한다는 확신은 주지 못합니다.
  • Integration — "모듈·컴포넌트·API가 함께 동작하나?" 속도와 확신 사이의 균형점입니다.
  • E2E — "사용자 여정 전체가 되나?" 확신은 가장 높지만 느리고 비싸고 잘 흔들리며, 실패했을 때 원인을 좁히기 어렵습니다. 그래서 핵심 여정 몇 개로 절제합니다.

12칸 표 대신 7장의 카드

방법론 4개와 계층 3개를 곱하면 12칸입니다. 초기 버전(0.2.0)에서는 실제로 12칸마다 기준 문서를 따로 만들었습니다.

그런데 두 축은 서로 독립(직교)입니다. ISO/IEC/IEEE 29119-1:2022는 regression을 "테스트 레벨이 아니라 설계·실행상의 선택"으로 규정합니다. 계층은 테스트 하나가 가진 고정된 성질이고, 방법론은 그 위에 붙는 '어떤 묶음으로 골라 돌리느냐'의 선택이라서 한 테스트가 여러 방법론에 동시에 속할 수 있습니다. 12칸은 서로 배타적인 칸이 아니라 두 축이 만나는 교차점일 뿐입니다.

그래서 0.3.0부터는 방법론 카드 4장과 계층 카드 3장, 총 7장의 축 카드로 바꿨습니다. 12칸을 미리 채워 두지 않고, 인수조건을 배정하는 시점에 필요한 카드 두 장을 조합합니다. 카드마다 "어떤 인수조건을 포함하고 어떤 것을 제외하는가", "오라클은 어느 강도여야 하는가", "실제 코드에서 어떻게 분리하는가"가 적혀 있습니다.

모든 조합이 쓸모 있지는 않으므로 조합의 강도도 정직하게 매겨 둡니다.

계층 \ 방법론SmokeSanityRegressionNightly
Unit약함퇴화강함(오라클 위험 최고)빈 칸
Integration강함퇴화강함강한 편
E2E조건부 강함(실제 API 전용)만들지 않음강함근거상 최강이지만 만들지 않음

약하거나 퇴화한 조합은 억지로 채우지 않고 비워 둡니다. 예를 들어 unit은 PR 단계에서 어차피 전부 돌기 때문에 nightly 전용 unit은 의미가 없습니다. Regression × Unit은 가장 강한 조합이면서 동시에 '버그를 정답으로 굳히는' 위험이 가장 큰 조합이라, 오라클 검사를 특히 엄격하게 합니다. E2E nightly는 근거로는 가장 잘 맞는 조합이지만 제 운영 결정으로 만들지 않습니다. 이유는 뒤에서 설명합니다.

저장소에 맞춘 세 가지 프리셋

하네스는 저장소를 읽고 세 프리셋 중 하나를 근거와 함께 추천합니다.

  • Trophy-lean — 프론트엔드·컴포넌트 중심. integration을 두껍게 두고, unit은 판정 로직에만, E2E는 필수 여정에만 씁니다. React·Vue·Svelte와 Testing Library가 보이면 추천합니다.
  • Google-pipeline — 대규모·모노레포. PR 전에는 unit 위주로 빠르게, 머지 뒤에는 넓게 돌립니다. 워크스페이스 구성이나 영향받은 테스트만 고르는 설정이 보이면 추천합니다.
  • Contract-honeycomb — 분산 서비스. 서비스 간 계약 테스트와 integration이 중심이고, E2E는 거의 두지 않습니다. OpenAPI·proto·계약 테스트 도구가 보이면 추천합니다.

어느 프리셋도 "unit 70%, integration 20%, E2E 10%" 같은 비율을 정하지 않습니다. 이 숫자는 테스트 피라미드를 널리 알린 Fowler 본인도 "숫자 자체는 중요하지 않다"고 한 통설이고, Testing Trophy나 Honeycomb 역시 전문가의 경험칙이지 실험으로 증명된 최적 비율이 아니기 때문입니다. 프리셋은 무게중심만 제안합니다.

진행 흐름: 5단계와 3개의 승인 게이트

단계하는 일게이트
Phase 0 초기 문의인수조건을 어디서 받을지 묻고, 테스트 러너·mock 도구·test id 관습 등을 감지—
Phase 1 구성프리셋을 추천하고 방법론·계층을 체크박스로 고르게 함스코프 확정
Phase 2 계획인수조건을 카드 조합으로 배정해 계층별 계획표와 CI 배치표 작성A: 계획 승인
Phase 3 개별 적용테스트를 하나씩 초안 → 검사 → 승인 → 파일 작성 → 실행B: 개별 승인
Phase 4 재확인전체 요약과 전체 실행 후 최종 확정C: 최종 반영

세 게이트는 건너뛸 수 없습니다. 계획 승인 없이 개별 적용 없고, 개별 승인 없이 파일 쓰기 없고, 최종 승인 없이 확정 없습니다. 스킬의 기본 도구 권한도 읽기와 검색만 열어 두었기 때문에, 파일 쓰기나 러너 실행은 매번 평소처럼 권한 확인을 거칩니다.

Phase 0: 인수조건의 출처를 반드시 묻는다

첫 라이브 실행은 바로 이 블로그 저장소에서 했습니다. 그때 드러난 가장 흔한 실수는 에이전트가 사용자에게 묻지도 않고 저장소를 뒤져 인수조건 후보를 지어내는 것이었습니다. 사용자에게 이미 정식 인수조건 문서가 있을 수 있는데도요.

그래서 0단계는 세 갈래를 반드시 보여 주고 답을 기다립니다. (a) 대화에 붙여넣기, (b) 파일·링크 경로, (c) 없음. (c)를 고른 경우에만 저장소의 PRD·스토리·기존 테스트 제목에서 후보를 찾아 제안하고, 그 후보로 진행할지 다시 확인받습니다. 처음 요청에 인수조건이 이미 들어 있으면 다시 묻지 않습니다.

같은 자리에서 저장소도 읽습니다. 어떤 러너가 있고 어떤 러너가 없는지, 네트워크 요청을 가로채는 mock 도구가 있는지, 기존 테스트가 실제 외부 API를 부르고 있지는 않은지, 팀이 쓰는 test id 속성 이름이 무엇인지, E2E를 돌릴 대상 환경 후보가 있는지를 확인합니다. 환경 변수는 키 이름만 보고하고 값은 읽어서 출력하지 않습니다.

Phase 1: 고른 것 안에서만 만든다 (스코프 가드)

방법론과 계층을 각각 체크박스로 고르게 하고, 추천 프리셋을 기준으로 기본 체크를 해 둡니다. 러너가 없는 계층에는 "러너 추가 필요"라고 표시합니다.

여기서 고른 (방법론 × 계층)이 이후 모든 단계의 울타리가 됩니다. 이것을 스코프 가드라고 부르고, 세 게이트와 같은 급의 규칙으로 둡니다. 어떤 인수조건이 자연스럽게는 E2E에 어울리는데 사용자가 E2E를 고르지 않았다면, 하네스는 integration으로 내려서 처리하거나 "스코프 밖 — 추가 안 함"으로 표시하고 범위를 넓힐지 묻습니다. 임의로 추가하지 않습니다.

Phase 2: 인수조건 하나 = 여러 계층

인수조건 하나를 테스트 하나와 같다고 보지 않습니다. 인수조건을 조각으로 나눈 뒤 계산·판정 로직은 unit으로, 모듈·API의 협업은 integration으로, 핵심 사용자 여정만 E2E로 보냅니다. "모든 E2E는 인수 테스트가 될 수 있지만, 모든 인수 테스트가 E2E일 필요는 없다"는 원칙입니다. Given-When-Then은 어느 계층에서든 준비(Arrange)·실행(Act)·검증(Assert)으로 그대로 옮길 수 있으니, 계층은 "무엇을 격리하고 무엇을 진짜로 쓰느냐"로 정합니다.

다음으로 각 조각에 방법론을 붙입니다. 대부분은 regression이고, 결정론적이며 치명적인 정상 경로는 smoke이고, 느리거나 비싸거나 흔들리는 것은 nightly로 미룹니다.

계획표의 한 행에는 인수조건 ID, 계층, 방법론과 그 묶음을 골라 돌리는 실행 명령, 조합 강도, API 경계(mock인지 실제인지, 가짜 응답을 어디서 구하는지), 화면 요소를 찾는 방법, 오라클, 테스트 파일 예정 경로, Given-When-Then 요약, 근거 카드가 들어갑니다. 여기에 CI 단계별 배치표와 추가될 실행 스크립트 목록까지 붙여 한 번에 승인받습니다. 승인 전에는 어떤 파일도 만들지 않습니다.

Phase 3: 한 번에 한 테스트

승인된 계획을 병렬로 처리하지 않고 한 행씩 진행합니다. 각 테스트마다 이 순서를 지킵니다.

  1. 오라클 선검사 — 어서션이 현재 구현이 내놓는 값을 베낀 것인지, 인수조건이 요구하는 기대를 검증하는지 구분합니다. 구현을 베낀 것이면 인수조건에서 기대를 다시 끌어내고, 애매하면 "이 기대가 맞습니까?"라고 묻습니다. 첫 테스트를 만들기 전에는 그 영역의 기존 flaky 테스트도 먼저 살핍니다. 흔들리는 테스트를 맥락으로 주면 새로 만든 테스트에도 흔들림이 옮아가기 때문입니다.
  2. 초안 작성과 자체 검사 — 파일 위치, 실제 API 호출 흔적, 화면 요소 탐색 순서, 태그와 인수조건 ID가 규칙대로인지 확인합니다. 값을 그대로 다시 읽기만 하는 어서션처럼 틀려도 실패하지 않는 어서션은 넣지 않습니다.
  3. 게이트 B — "적용 / 수정 후 적용 / 이 테스트만 건너뜀 / 여기서 중단" 중에서 고르게 합니다. 승인할 때만 파일을 씁니다.
  4. 실행 — 적용한 테스트를 실제로 돌리고, 결과를 스스로 하는 보고가 아니라 실행 출력으로 보여 줍니다. 실패하면 테스트가 틀린 것인지, 코드가 인수조건을 어긴 것인지 구분해 다음 조치를 묻습니다. 정상 코드에서도 통과하는지(헛경보가 아닌지), 방금 붙인 태그로 실제로 그 묶음에 뽑히고 다른 묶음에는 뽑히지 않는지도 실행해서 확인합니다.

사용자가 중간에 멈추면 그때까지 적용된 것만 남기고 마지막 단계로 넘어갑니다.

Phase 4: 다시 확인하고 확정

적용·건너뜀·실패 목록, 계층·묶음별 분포, 코드 결함으로 의심되는 항목, 아직 검증하지 못한 항목을 정리해 보여 준 뒤 마지막으로 확정 여부를 묻습니다. 특정 테스트를 되돌려 달라고 하면 그 파일 변경만 원래대로 돌립니다.

지키는 규칙들

unit·integration은 실제 API를 부르지 않는다

unit과 integration은 예외 없이 mock입니다. 실제 네트워크로 나가는 순간 그 테스트는 더 이상 unit도 integration도 아니라고 보기 때문입니다. 네트워크 요청을 경계에서 가로채는 도구(MSW, nock 같은)를 우선 쓰고, 없으면 모듈 자체를 대역으로 바꾸되 "그래서 요청 조립이나 에러 변환은 검증하지 못한다"를 계획에 적습니다.

mock에 넣을 가짜 응답(fixture)은 세 단계로 구합니다. 저장소에 이미 있는 것을 재사용하고, 없으면 사용자에게 실제 응답 샘플을 받고, 그것도 없으면 스키마나 타입에서 만들어 내되 "실측 캡처 아님"이라고 표시합니다. 하네스가 fixture를 만들겠다고 실제 API를 부르는 일은 없습니다. fixture 값을 그대로 기대값으로 복사하는 것도 금지합니다. fixture는 전제(Given)이지 정답이 아닙니다.

작성한 뒤에는 외부 주소나 mock되지 않은 HTTP 호출이 남았는지 정적으로 검사합니다. 다만 이 검사를 통과했다고 "네트워크로 나가지 않는다"가 증명되지는 않는다는 한계도 함께 적습니다.

mock 통과는 연동 정상이 아닙니다. fixture는 캡처한 순간의 스냅샷이라 실제 API가 바뀌어도 테스트는 계속 초록입니다. 연동을 확인하는 장치는 실제 API로 돌리는 E2E뿐이라는 사실을 산출물에 항상 함께 적습니다.

E2E는 smoke와 regression만, smoke는 regression 안에

E2E는 smoke와 regression 두 가지로만 만듭니다. nightly나 sanity 전용 E2E는 만들지 않습니다. 대가도 적어 둡니다. 크로스 브라우저나 대규모 E2E를 nightly로 미룰 곳이 없어지므로, regression E2E 자체를 핵심 여정으로 좁혀야 합니다.

그리고 smoke는 regression의 부분집합입니다. smoke 테스트는 smoke 태그와 regression 태그를 함께 지닙니다. 같은 시나리오를 mock용 파일과 실제 API용 파일로 복제하지 않고, 실행 모드는 기존 테스트에 태그로만 붙입니다. E2E는 기본적으로 mock 모드 태그를 달고 CI에서 매번 같은 결과로 돌며, 사용자가 지목한 시나리오에만 실제 API 모드 태그를 더해 수동으로 돌립니다.

E2E smoke는 실제 API 전용 — 그리고 그 대가

이 하네스에서 가장 의견이 강한 부분입니다. E2E smoke는 따로 요청하지 않아도 실제 API로만 돕니다. mock 데이터로 smoke를 통과시키면 "배포된 것이 정말 살아 있나"라는 smoke 본래의 질문에 답하지 못한다고 봤기 때문입니다. 대신 CI의 어느 고정 단계(PR, 배포 후, nightly)에도 넣지 않고 수동 실행 레시피로만 둡니다.

이것은 "배포를 막는 관문은 결정론적이어야 하고 외부 의존이 없어야 한다"는 통상의 권고(MinimumCD, Fowler)와 정면으로 충돌하는 운영 결정입니다. 그래서 하네스는 이를 근거로 포장하지 않고 산출물에 그대로 적습니다. E2E smoke는 자동 배포 게이트가 아니라, 승격 전에 사람이 돌리는 수동 체크포인트입니다. 실제 API로 통과했다는 것도 "언제, 어느 환경에서 통과했다"는 관측일 뿐 연동을 영구히 보증하지 않습니다.

0.5.0에서는 정반대로 "E2E smoke에는 실제 API 모드를 두지 않는다"가 규칙이었습니다. 0.6.0에서 이를 뒤집으면서, 규칙은 바꾸되 근거와 충돌한다는 사실은 숨기지 않는 방식을 택했습니다.

실제 API를 부르는 유일한 예외와 그 조건

하네스가 직접 실제 API를 부르는 경우는 E2E smoke 실행 하나뿐입니다. 그마저도 세 가지가 모두 갖춰져야 합니다. 대상 환경 주소, 테스트 계정·시드 데이터(또는 "필요 없음" 확인), 그리고 그 자리에서 받은 실행 승인입니다. 계획을 승인했다고 실행까지 승인한 것으로 보지 않습니다.

  • 대상이 프로덕션이면 한 번 더 확인합니다.
  • 결제·발송·삭제·과금처럼 부작용이 있는 여정은 하나씩 따로 묻습니다.
  • 비밀 값은 대화로 받지 않고, 환경 변수나 시크릿의 키 이름만 다룹니다.
  • 테스트가 만든 데이터를 하네스가 임의로 지우지 않고, 남아 있다고 보고합니다.
  • 실패는 테스트 결함, 코드 결함, 환경·외부 요인(미배포, 인증 만료, 요청 제한, 외부 장애)의 셋으로 나눕니다. 환경 문제를 코드 결함으로 몰지 않기 위해서입니다.
  • 조건이 갖춰지지 않아 돌리지 못했으면 UNVERIFIED(미검증) 로 남깁니다. "실행 레시피를 만들었다"를 "검증했다"로 바꿔 말하지 않습니다.

Sanity는 새 테스트를 만드는 축이 아니라 고르는 레인

앞의 조합 강도표에서 sanity가 전부 '퇴화'인 것은 "sanity 전용 테스트를 새로 만들지 않는다"는 뜻이지 sanity를 운영하지 않는다는 뜻이 아닙니다. 이 하네스에서 sanity는 이미 있는 테스트를 변경 범위로 골라 PR 전에 돌리는 선택 레인입니다.

대상은 세 단계로 넓혀 갑니다. 변경된 파일, 그 파일을 가져다 쓰는 상위 페이지·컴포넌트, 그리고 (E2E를 골랐다면) 관련 페이지의 mock E2E입니다. 매핑이 불확실하면 범위를 좁히지 않고 전체로 넓힙니다. PR 작업에서 unit·integration은 실패하면 막고, mock E2E는 막지 않고 보고만 합니다.

코드에 sanity 태그를 심지는 않습니다. 변경 관련 대상에 테스트가 아예 없을 때만 새로 만들고, CI 설정 파일은 직접 고치지 않고 추가할 내용을 제안만 합니다. 이 배치와 차단 정책 역시 표준이 아니라 운영 결정이라고 함께 적습니다.

화면 요소는 사용자가 찾는 방식으로 찾는다

화면을 조회하는 테스트는 정해진 사다리를 위에서부터 시도합니다.

  1. 보이는 요소와 상호작용 — 역할(버튼·링크 같은 role)과 이름 → 레이블 → placeholder → 보이는 텍스트 → 입력된 값
  2. HTML·ARIA 속성 — 이미지 대체 텍스트 → title 속성
  3. 테스트 ID — 위 방법으로 찾을 수 없을 때만
  4. 최후 수단 — 임의의 CSS 셀렉터

한 단계 내려갈 때마다 왜 위 단계로는 찾을 수 없는지 사유를 적어야 합니다. "쓰기 편해서"는 사유가 아닙니다. 몇 가지 세부 규칙이 더 있습니다.

  • 러너마다 이름이 다릅니다. Testing Library와 Playwright는 같은 개념을 다른 이름으로 부르고, Playwright에는 입력된 값으로 찾는 쿼리가 아예 없습니다. 없는 API를 부르지 않고, 값으로 특정해야 하면 더 위 순위로 찾은 뒤 값은 어서션으로 확인합니다.
  • test id 속성 이름은 팀이 정할 일입니다. 하네스가 임의로 정하지 않고 저장소에서 감지하며, 없거나 여러 개가 섞여 있으면 묻습니다. 제품 코드에 test id를 새로 넣는 것은 테스트 파일 밖의 변경이라 따로 승인받습니다.
  • 최후 수단도 쓸 수 있지만 결합 비용을 적습니다. 애널리틱스용 속성으로 찾으면 다른 목적으로 만든 약속에 묶이고, CSS 모듈 클래스 이름의 일부로 찾으면 빌드 해시라는 구현 세부에 묶입니다. 그 주인이 바꾸면 테스트가 깨집니다. 위험은 알리되 쓸지 말지는 사용자가 정합니다.

이 사다리는 Testing Library 공식 가이드의 설계 의도이지, 실험으로 우월성이 증명된 것이 아닙니다. 그래서 준수율을 점수로 매기거나 "role로 찾으면 flaky가 몇 % 줄어든다" 같은 수치를 쓰지 않습니다. 셀렉터를 잘 골랐다고 오라클이 강해지지도 않습니다. 둘은 별개의 검사입니다.

파일 위치는 무조건 대상 옆의 __test__ 폴더

unit·integration 테스트는 테스트 대상 파일이 있는 바로 그 폴더에 __test__ 폴더를 만들고 그 안에 둡니다. 저장소에 다른 관습(복수형 폴더, 별도의 test 폴더, 소스 옆에 바로 두기)이 있어도 예외 없이 이 규칙을 따릅니다.

처음에는 "기존 관습이 있으면 그 관습을 따른다"는 예외가 있었습니다. 그런데 실제로 써 보니 그 예외가 빠져나갈 구멍이 되어, 가끔 폴더 없이 소스 옆에 테스트가 생기는 편차가 나왔습니다. 0.4.1에서 예외를 없애고 작성 전·작성할 때·작성 후 세 번 경로를 확인하도록 바꿨습니다. E2E는 별도 러너와 폴더 관습이 있으므로 계층을 고를 때 경로를 따로 묻습니다.

테스트 제목에 인수조건 ID

smoke·regression 테스트는 모두 제목 맨 앞에 인수조건 ID를 붙입니다. 어떤 테스트가 어떤 인수조건을 검증하는지 코드에서 바로 보이게 하려는 것입니다.

smoke와 regression에는 인수조건에 근거한 테스트만 만듭니다. 성능·fuzz처럼 인수조건 밖에서 필요한 테스트는 nightly나 sanity에만 ID 없이 둘 수 있고, 이때도 계획표에 사유를 적어 따로 승인받습니다. 입력한 인수조건에 ID가 없으면 하네스가 번호를 매긴 매핑표를 먼저 승인받으며, 입력에 없는 ID를 지어내지 않습니다. smoke에 넣고 싶은 테스트가 있는데 대응하는 인수조건이 없다면 테스트를 지어내지 않고, 인수조건을 추가할지(기획의 결정) 묻습니다.

스위트는 코드로 존재해야 한다

계획표에 "smoke"라고 적는 것만으로는 아무 일도 일어나지 않습니다. 하네스는 러너가 기본 제공하는 기능으로 태그를 코드에 실제로 붙이고(Playwright·Vitest의 태그 기능, 태그 기능이 없는 Jest는 제목 규칙이나 프로젝트 분리), 묶음별 실행 스크립트를 추가한 다음, 그 명령으로 이 테스트가 실제로 뽑히고 다른 테스트는 뽑히지 않는지 돌려 봅니다. 계획에는 있는데 코드에 태그가 없는 테스트는 거부합니다. 러너가 태그를 지원하지 않으면 분리되는 척하지 않고 "라벨일 뿐 실행 분리는 아님"으로 낮춰 적습니다.

E2E가 있으면 격리 조건 여섯 가지를 실행 출력으로 확인합니다. 요약하면 "CI에서 도는 smoke·regression 목록에 실제 API 테스트가 하나도 섞이지 않는다", "smoke E2E에는 mock 태그가 없고 regression 태그는 있다", "nightly에 E2E가 없다", "같은 시나리오가 모드만 다른 파일로 복제되어 있지 않다" 같은 조건들입니다.

정직성 원칙

이 하네스에서 가장 손이 많이 간 부분은 기능보다 '말하지 않을 것'의 목록이었습니다.

  • 70/20/10 같은 계층 비율을 정하지 않습니다.
  • smoke와 sanity가 표준상 동의어라는 사실을 숨기지 않습니다.
  • "smoke로 치명적 버그 80% 조기 포착", "mock 전환으로 flaky N% 감소" 같은 근거 없는 효과 수치를 인용하지 않습니다.
  • 실행 순서를 바꾸는 우선순위 정렬로 CI 비용이 줄어든다고 말하지 않습니다. 순서만 바뀔 뿐 총 실행량은 그대로입니다. 비용을 줄이는 것은 선택 실행·묶음 실행·병렬화입니다.
  • mock 통과를 연동 검증으로, 실행하지 않은 것을 통과로 보고하지 않습니다.
  • sanity의 PR 배치, E2E smoke의 실제 API 전용 규칙, 셀렉터 사다리처럼 근거가 아니라 운영 결정이거나 설계 의도인 것은 그렇다고 적습니다.
  • 모든 결론에 신뢰도(높음·중간·낮음)와 출처를 붙입니다.

사용 방법

설치

# 한 번에 설치 (Claude Code 2.1.275+)
/plugin install test-layering-harness --marketplace seungahhong/seungah-claude-plugins
 
# 또는 마켓플레이스 등록 후 설치
/plugin marketplace add seungahhong/seungah-claude-plugins
/plugin install test-layering-harness@seungah-claude-plugins

부르기

슬래시 명령으로 부르거나, 자연어로 요청하면 스킬이 발동합니다.

/test-layering-harness:test-layering-harness
이 인수조건으로 계층별 테스트 계획 세우고 하나씩 승인받으며 추가해줘

이 밖에도 "이 AC를 unit/통합/E2E로 나눠서", "스모크/회귀 테스트 계획 세워줘", "CI 단계별로 어떤 테스트를 어디에 둘지"처럼 테스트 계층 전략이나 CI 배치를 이야기하면 발동합니다.

1. 인수조건과 경로 알려 주기

인수조건을 붙여넣을지, 파일 경로를 줄지, 없으니 저장소에서 찾아 달라고 할지 고릅니다. 붙여넣는다면 이런 형태면 충분합니다.

AC-1.1
Given 로그인한 사용자가 상품 상세 페이지에 있을 때
When 찜하기 버튼을 누르면
Then 버튼이 '찜 해제'로 바뀌고 찜 목록 개수가 1 늘어난다
 
AC-1.2
Given 로그인하지 않은 사용자가 상품 상세 페이지에 있을 때
When 찜하기 버튼을 누르면
Then 로그인 페이지로 이동한다

ID가 없으면 하네스가 AC-1.1, AC-1.2처럼 번호를 매긴 매핑표를 만들어 승인받습니다. 테스트를 반영할 경로는 건너뛰어도 되며, 그러면 현재 프로젝트 경로를 기준으로 러너와 관습을 감지합니다.

2. 방법론·계층 고르기

추천 프리셋과 함께 체크박스가 뜹니다. 기본 체크를 그대로 두거나 가감합니다.

방법론  [x] Smoke   [ ] Sanity        [x] Regression   [ ] Nightly
계층    [x] Unit    [x] Integration   [x] E2E

E2E를 고르면 E2E 테스트를 둘 경로를 묻습니다. Smoke와 E2E를 함께 고르면 E2E smoke가 실제 API 전용이라는 점을 알려 주고 대상 환경 주소, 테스트 계정을 담은 환경 변수 이름, 부작용 있는 여정 포함 여부를 묻습니다. 지금 답하지 않아도 계획은 그대로 세우고, 실행만 UNVERIFIED로 남깁니다.

3. 계획 승인 (게이트 A)

계획표가 나옵니다. 위 인수조건이라면 대략 이런 모양입니다.

#AC-ID계층방법론API 경계화면 요소오라클
1AC-1.1Integrationsmoke, regressionmock · 네트워크 가로채기 · fixture 재사용역할(버튼)과 이름 '찜하기'클릭 후 버튼 이름이 '찜 해제', 개수 +1
2AC-1.2Unitregressionmock · 모듈 대역해당 없음(비-DOM)비로그인이면 로그인 경로를 돌려줌
3AC-1.1E2Esmoke, regression실제 API 전용 · 수동 실행역할(버튼)과 이름 '찜하기'상세 → 찜 → 찜 목록에 노출

그 아래에 CI 단계별 배치표와 추가될 실행 스크립트가 붙습니다. 전체 승인, 특정 행 수정·제외, 프리셋 재조정 중에서 고릅니다.

4. 하나씩 승인 (게이트 B)

테스트마다 초안을 보여 주고 묻습니다.

이 테스트를 적용할까요? (적용 / 수정 후 적용 / 이 테스트만 건너뜀 / 여기서 중단)

승인하면 파일을 쓰고 바로 실행해 결과를 보여 줍니다. 만들어지는 테스트는 제목 맨 앞에 인수조건 ID가, 옵션에 묶음 태그가 붙습니다. 위 3번 행이라면 다음과 같습니다.

test(
  '[AC-1.1] 로그인 사용자가 찜하기를 누르면 찜 목록에 상품이 추가된다',
  { tag: ['@smoke', '@regression', '@e2e-live'] },
  async ({ page }) => {
    // ...
  },
);

묶음의 첫 테스트를 적용할 때 실행 스크립트도 함께 추가합니다. 이름과 명령은 저장소 관습에 맞춰지며, 예를 들면 이런 식입니다.

pnpm test:smoke            # E2E를 뺀 smoke — 배포 후 CI
pnpm test:regression       # regression 전체 — E2E는 mock 모드만
pnpm test:e2e:smoke:live   # E2E smoke, 실제 API — 수동 전용, CI에 넣지 않음

5. 최종 확정 (게이트 C)

적용 요약과 전체 실행 결과(실제 API 테스트는 제외)를 보고 확정하거나 특정 테스트를 되돌립니다. 원하면 계획표와 적용 요약을 파일로 남길 수 있습니다.

<대상 경로>/.claude/_docs/test-layering/<슬러그>/
  test-plan.md        # 계획표
  applied-summary.md  # 적용 요약

버전으로 본 변화

버전날짜바뀐 것
0.1.02026-07-05신설. 인수조건 → 방법론×계층 계획, 3개 승인 게이트, 오라클 재검증과 실행 확인, 3개 프리셋
0.2.02026-07-06방법론×계층 12칸마다 기준 문서를 만들고 2025년 이후 표준·논문으로 근거화
0.3.02026-07-0612칸을 7장의 축 카드로 바꾸고 스코프 가드 도입
0.4.x2026-07-07, 07-14테스트 배치·mock 규칙, E2E 경로 초기 문의, __test__ 폴더 무조건 강제
0.5.02026-08-01API 경계 축(mock/실제), E2E 모드 태그, sanity를 변경 범위 선택 레인으로
0.6.02026-08-17E2E smoke는 실제 API 전용으로 반전, 실행 조건과 실패 3분류
0.7.x2026-08-23, 10-18화면 요소 탐색 사다리 신설, 스킬 설명 축약과 도구 권한 축소
0.8.02026-10-18E2E는 smoke·regression만, smoke ⊆ regression, 테스트 제목에 인수조건 ID

돌아보면 대부분의 변경은 "실제로 써 보니 이렇게 빠져나가더라"에서 나왔습니다. 인수조건을 묻지 않고 지어내는 편차, 예외 조항을 타고 폴더 규칙이 무너지는 편차, 계획에만 있고 코드에는 없는 스위트. 규칙을 하나 더할 때마다 그 규칙이 무엇을 포기하게 만드는지도 같이 적으려고 했습니다.

마무리

테스트 생성은 이미 에이전트가 잘하는 일입니다. 사람에게 남은 일은 "이 테스트가 무엇을 정답으로 삼는가", "이 테스트는 어느 층에서 어느 시점에 돌아야 하는가"를 판단하는 것이고, 이 하네스는 그 판단을 매번 사람 앞에 꺼내 놓도록 설계했습니다. 세 번의 승인이 번거롭게 느껴질 수 있지만, 버그를 정답으로 굳힌 테스트를 나중에 찾아내는 비용에 비하면 싼 편이라고 생각합니다.

참고