agent conventions

Navigation

Testing

테스트를 설계하고 작성, 검토하는 팀을 위한 컨벤션입니다. unit, integration, 앱 E2E의 실행 경계와 smoke, sanity의 선별 목적을 구분합니다. GIVEN, WHEN, THEN으로 조건, 행동, 결과를 드러내고 독립된 기대값과 상태 격리를 정합니다. Kubb 등의 생성 DTO, faker, MSW 위에서 소유 mock과 handler를 조립해 브라우저와 Node가 함께 쓰는 작성 순서를 다룹니다. Story는 실제 화면과 provider로 재현 상태를 구성하고 소비 spec에서 행동과 결과를 검증합니다. Vitest, Playwright, 골든과 시각 비교, 실행 범위의 보고도 포함합니다. 폴더 번호와 케이스 ID, 결과서 형식은 프로젝트에 남깁니다.

함께 보는 규칙

규칙

1. 범위와 배치

검증할 계약에 맞는 가장 작은 실행 범위를 고르고 층별 책임과 소유 위치를 정합니다. 프로젝트의 테스트 추가 정책과 러너 수집 경계를 유지합니다. 섹션 페이지

규칙요지
1.1 신뢰를 얻을 수 있는 가장 작은 범위를 선택합니다검증에 필요한 실제 경계를 유지하면서 실행 비용과 실패 원인을 줄입니다
1.2 상세한 경우의 수와 상위 연결 검증을 나눕니다중복 비용을 줄이면서 함수와 화면 사이의 연결 누락을 검출합니다
1.3 소유 대상을 찾기 쉽게 배치하고 러너 수집 범위를 분리합니다테스트 위치를 예측할 수 있고 다른 러너의 파일이 잘못 실행되지 않습니다
1.4 테스트 층과 smoke, sanity의 선별 목적을 구분합니다실행 경계와 선별 목적을 나눠 필요한 검증을 빠짐없이 선택합니다

2. 시나리오와 기대값

GIVEN, WHEN, THEN으로 조건, 행동, 결과를 드러내고 상태와 경계값을 선택합니다. 기대값은 검증 대상 구현과 독립된 계약에서 정합니다. 섹션 페이지

규칙요지
2.1 조건과 관찰 가능한 결과로 테스트 하나를 설명합니다실패한 제목만으로 깨진 동작과 필요한 사전조건을 찾을 수 있습니다
2.2 계약에 해당하는 상태와 경계값을 선택합니다정상 경로만 통과하는 테스트에서 빠지기 쉬운 회귀를 검출합니다
2.3 기대값은 구현과 독립된 계약에서 정합니다구현과 같은 오류를 기대값에서도 반복해 통과하는 테스트를 막습니다

3. 데이터와 격리

유효한 입력의 핵심 필드를 명시하고 시간과 실행 환경을 통제합니다. 테스트가 바꾼 상태와 자원의 수명을 격리하고 복구합니다. 섹션 페이지

규칙요지
3.1 작고 유효한 타입 기반 입력을 구성합니다필수 필드 누락을 숨기지 않고 검증할 차이를 입력에서 읽을 수 있습니다
3.2 시간과 환경을 명시적인 테스트 입력으로 통제합니다실행 날짜와 실행 위치가 바뀌어도 같은 입력이 같은 결과를 냅니다
3.3 테스트 상태와 자원을 격리하고 수명을 끝냅니다단독 실행과 전체 실행에서 같은 결과를 얻고 상태 누수를 막습니다

4. Vitest 단언과 mock

값, 오류, 비동기 완료를 계약에 맞는 matcher로 확인합니다. 검증 대상은 실제로 실행하고 필요한 의존 경계만 대체합니다. 섹션 페이지

규칙요지
4.1 값과 오류의 계약을 맞는 matcher로 끝까지 확인합니다느슨한 비교와 완료되지 않은 비동기 작업으로 생기는 거짓 통과를 막습니다
4.2 검증 대상의 실제 로직을 실행하고 필요한 의존성만 대체합니다mock 자체의 동작을 검증하며 실제 결함을 놓치는 일을 막습니다

5. Playwright 브라우저 테스트

의미와 범위가 분명한 locator로 준비된 화면을 조작합니다. 조건과 이벤트로 기다리고 fixture와 page object는 실제 반복 경계에 맞춥니다. 섹션 페이지

규칙요지
5.1 의미와 범위가 분명한 locator를 사용합니다DOM 순서와 서드파티 클래스 변경에 흔들리지 않고 의도한 요소를 조작합니다
5.2 관찰 가능한 상태를 기다리고 이벤트 대기는 액션 전에 등록합니다임의의 대기 시간과 이벤트 등록 순서로 생기는 불안정한 실패를 줄입니다
5.3 공통 준비와 반복되는 화면 조작만 추출합니다테스트의 핵심 시나리오를 숨기지 않고 중복되는 준비와 탐색을 줄입니다
5.4 사전조건을 직접 준비하고 검증할 여정은 실제로 수행합니다불필요한 탐색을 줄이면서 라우팅과 상태 전달의 연결을 실제로 검증합니다

6. 네트워크 경계

실제 화면 처리와 provider는 유지하며 응답 경계에서 필요한 상태를 만듭니다. 생성 계약과 소유 mock을 조립해 브라우저와 Node가 함께 쓰고 미처리 요청을 검출합니다. 섹션 페이지

규칙요지
6.1 응답 경계에서 교체하고 화면의 실제 처리를 유지합니다요청 조립과 응답 변환, provider, 화면 상태의 실제 연결을 확인합니다
6.2 mock에서 빠진 API 요청을 검출합니다누락된 mock이 외부 네트워크나 무관한 기본 응답으로 숨지 않습니다
6.3 실제 시스템과 mock의 경계를 명시합니다브라우저 테스트가 보장하는 범위와 별도 서버 검증이 필요한 범위를 구분합니다
6.4 생성 계약 위에 도메인 mock과 endpoint handler를 조립합니다API 재생성에 맞춰 타입과 응답 형식을 유지하고 시나리오 값을 일관되게 만듭니다
6.5 같은 handler를 브라우저와 Node의 단일 응답 경계로 연결합니다실행 환경에 따라 정상 데이터와 handler 우선순위가 달라지는 문제를 막습니다

7. 골든과 시각 비교

의미 있는 차이를 유지하는 작은 기준값을 검토합니다. 시각 비교의 렌더 환경, 안정화 조건, matcher 설정을 맞춥니다. 섹션 페이지

규칙요지
7.1 작고 의미가 남는 기준값을 검토합니다변경의 의미를 확인할 수 있고 정규화로 중요한 차이를 숨기지 않습니다
7.2 시각 비교 환경과 matcher 설정을 맞춥니다렌더 환경 차이를 통제하고 허용치가 실제 비교에 적용되게 합니다

8. 검증과 결과 보고

회귀 테스트가 원래 결함을 검출하는지 확인하고 실행 범위를 기록합니다. 실패, 재시도 통과, 미실행과 커버리지의 측정 경계를 보존합니다. 섹션 페이지

규칙요지
8.1 회귀 테스트가 원래 결함을 검출하는지 확인합니다수정한 구현에서 통과만 하는 테스트와 결함을 검출하는 테스트를 구분합니다
8.2 실행 범위와 실패 상태를 보존해 보고합니다미실행과 재시도 통과를 성공으로 섞거나 오래된 결과서를 새 근거로 쓰지 않습니다

9. Story와 harness

실제 화면과 provider로 재현 가능한 상태를 만들고 story를 테스트에서 소비합니다. 브라우저 경계의 props, 콜백, 정리와 자동 단언의 책임을 구분합니다. 섹션 페이지

규칙요지
9.1 Story는 실제 화면과 provider로 재현할 상태를 구성합니다화면의 실제 처리 흐름을 유지하면서 상태를 작게 재현합니다
9.2 Story를 mount하는 테스트에서 행동과 결과를 검증합니다재현용 표본과 자동 검증을 연결하고 실행되지 않은 상태를 통과로 오인하지 않습니다

참고 자료