[2팀 정나리] Chapter 1-2. AI와 테스트를 활용한 안정적인 기능 개발

.cursor/checklists/breakdown-checklist.md

@@ -0,0 +1,18 @@
+## ✅ Self-Check Checklist
+
+| 항목                                           | 설명                                             | 예시                                                 | Pass 기준                        |
+| ---------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------- | -------------------------------- |
+| **1. 사용자 행동이 포함되어 있는가?**          | Flow 이름이 클릭, 선택, 입력 등으로 시작해야 함  | “반복 설정을 클릭하면 옵션이 표시된다”               | 모든 Flow는 사용자 행동으로 시작 |
+| **2. 기대 결과가 명확한가?**                   | 결과가 “표시된다”, “저장된다” 등으로 끝나야 함   | “옵션 목록이 표시된다”                               | 모든 Flow는 결과 문장으로 끝     |
+| **3. 단일 목적 Flow인가?**                     | 하나의 Flow가 여러 동작/결과를 포함하지 않음     | ✅ “클릭 시 옵션 표시” ❌ “클릭 후 저장까지”         | Flow는 단일 목적                 |
+| **4. 예외 조건이 분리되어 있는가?**            | 조건 분기(31일, 윤년 등)는 별도 Flow로 분리      | “윤년 29일 선택 시”                                  | 모든 예외는 독립 Flow            |
+| **5. 정상/예외 Flow 구분 명확한가?**           | Flow Type 필드에 Normal/Exception 명시           | Flow 1-1 Normal / 1-2 Exception                      | 모두 구분됨                      |
+| **6. Flow 이름이 행동+결과 형태인가?**         | “~시 ~된다” 형식                                 | “반복 클릭 시 옵션 표시”                             | 이름만으로 의도 파악 가능        |
+| **7. Flow 중복 없는가?**                       | 동일한 Input/Trigger/Output 조합이 중복되지 않음 | “옵션 표시” Flow 한 번만 존재                        | 중복 Flow 없음                   |
+| **8. PRD의 Acceptance Criteria와 매핑되는가?** | PRD의 요구사항 문장마다 Flow 존재                | “윤년 처리 규칙 적용” → Flow 1-3                     | 모든 AC가 Flow로 표현됨          |
+| **9. UI 피드백 Flow 존재하는가?**              | UI 변화는 별도 Flow로 분리                       | “반복 일정 hover 시 툴팁 표시”                       | 존재                             |
+| **10. 내부 로직 언급 없이 사용자 관점인가?**   | DB나 함수 호출 등 내부 처리 언급 없음            | “저장 시 반복 규칙이 적용됨”                         | Flow는 사용자 중심               |
+| **11. Flow 순서가 논리적으로 자연스러운가?**   | Flow ID 순서가 UX 순서와 일치                    | 옵션 표시 → 옵션 선택 → 저장 결과                    | 순서상 자연스러움                |
+| **12. I/O 정의가 완전한가?**                   | Input, Trigger, Output 3요소 모두 존재           | Input: 날짜 선택 / Trigger: 클릭 / Output: 옵션 표시 | 모든 Flow 완전                   |
+
+---

.cursor/checklists/how-to-design-test.md

@@ -0,0 +1,169 @@
+## 1. 테스트는 명세처럼 읽혀야 한다
+
+- 테스트는 “코드 검증”이 아니라 “명세 문서”처럼 읽혀야 한다.
+- 테스트 이름은 **행동 + 기대 결과** 형식으로 작성한다.
+  ```
+  it('잘못된 비밀번호 입력 시 에러 메시지를 표시한다', ...)
+  it('반복 일정 생성 시 아이콘이 표시된다', ...)
+
+  ```
+- 내부 로직보다 **사용자 관점의 결과**에 초점을 맞춘다.
+
+---
+
+## 2. AAA 패턴(Arrange – Act – Assert)을 따른다
+
+테스트의 기본 구조는 다음과 같다.
+
+```
+1. Arrange (준비): 테스트 환경, 입력값, mock 세팅
+2. Act (실행): 테스트할 실제 동작 수행
+3. Assert (검증): 기대 결과 확인
+
+```
+
+예시:
+
+```tsx
+it('유효한 이메일과 비밀번호로 로그인하면 성공 메시지를 표시한다', async () => {
+  // Arrange
+  render(<LoginPage />);
+  await user.type(screen.getByLabelText('이메일'), '[email protected]');
+  await user.type(screen.getByLabelText('비밀번호'), '1234');
+
+  // Act
+  await user.click(screen.getByText('로그인'));
+
+  // Assert
+  expect(await screen.findByText('환영합니다')).toBeInTheDocument();
+});
+```
+
+- 이 순서를 지키면 테스트가 문서처럼 읽히고, 디버깅이 쉬워진다.
+- `beforeEach`는 **Arrange 일부를 공통화**하는 용도로만 사용한다.
+
+---
+
+## 3. 하나의 테스트는 하나의 목적만 검증한다
+
+- 각 테스트(`it`)는 **하나의 개념적 목적만** 검증해야 한다.
+- 여러 개의 `expect`를 써도 좋지만, 모두 같은 시나리오 내에서만 사용한다.
+- 서로 다른 기능이나 흐름을 한 테스트에 섞지 않는다.
+
+---
+
+## 4. 테스트 간 독립성을 보장한다
+
+- 테스트 실행 순서가 달라져도 결과가 같아야 한다.
+- `beforeEach`로 공통 세팅을 하되, 상태 공유는 금지한다.
+- Mock, DOM, 전역 상태는 테스트마다 새로 생성한다.
+
+---
+
+## 5. Mocking은 최소한으로만 사용한다
+
+- Mock은 외부 의존(API, DB, 네트워크 등)에 한정한다.
+- Mock이 많을수록 실제 코드 대신 Mock을 테스트하게 된다.
+- 가능한 실제 로직을 실행하고, side effect가 있는 부분만 Mock한다.
+
+---
+
+## 6. 입력과 출력이 명확한 단위를 테스트한다
+
+- “예측 가능한 결과를 내는 함수(순수 함수)”는 반드시 단위 테스트한다.
+- 조건 분기, 계산, 변환 로직은 단위 테스트 대상이다.
+- DOM, 상태관리, API 통신 등 외부 의존이 포함된 로직은 통합 테스트로 다룬다.
+
+---
+
+## 7. 테스트 이름과 구조는 일관되어야 한다
+
+| 구분       | 규칙                   | 예시                                                |
+| ---------- | ---------------------- | --------------------------------------------------- |
+| 파일명     | `{feature}.spec.tsx`   | `login.spec.tsx`                                    |
+| `describe` | `"기능명 Feature"`     | `"Login Feature"`                                   |
+| `it`       | `"TC-01 - 시나리오명"` | `"TC-01 - 유효한 로그인 시 성공 메시지를 표시한다"` |
+
+---
+
+## 8. 불필요한 `waitFor`, `act` 사용을 피한다
+
+- 명확한 이벤트(클릭, 입력 등) 이후에만 `waitFor`를 사용한다.
+- 타이밍 보정용 `waitFor`는 불안정하고 느린 테스트를 만든다.
+
+---
+
+## 9. Magic number와 하드코딩된 문자열을 피한다
+
+- 의미 없는 숫자나 문자열은 상수나 변수명으로 명확히 표현한다.
+  ```tsx
+  const INVALID_PASSWORD = 'wrong_password';
+  const VALID_EMAIL = '[email protected]';
+  ```
+
+---
+
+## 10. UI 테스트는 사용자 행동 기반으로 작성한다
+
+- React Testing Library의 철학: “사용자가 보는 화면을 그대로 테스트하라.”
+- DOM 구조나 내부 구현이 아니라 **사용자 행동과 결과**를 검증한다.
+  ```tsx
+  await user.type(screen.getByLabelText('이메일'), '[email protected]');
+  await user.click(screen.getByText('로그인'));
+  expect(await screen.findByText('환영합니다')).toBeInTheDocument();
+  ```
+
+---
+
+## 11. 테스트는 실패했을 때 원인을 바로 파악할 수 있어야 한다
+
+- 실패 메시지를 통해 “무엇이 잘못됐는지” 바로 알 수 있어야 한다.
+- helper나 abstraction이 많으면 의도가 흐려지므로 피한다.
+- 테스트는 독립적으로 읽히는 문장처럼 구성한다.
+
+---
+
+## 12. 테스트 코드도 리팩토링 가능한 코드다
+
+- 테스트는 제품 코드와 동일한 수준의 품질로 관리해야 한다.
+- 반복되는 setup은 공통화하되, 가독성이 우선이다.
+- DRY(Don’t Repeat Yourself)보다 “의도가 드러나는 중복”이 더 낫다.
+
+---
+
+## 13. 단위 테스트와 통합 테스트의 역할을 구분한다
+
+| 구분                     | 목적                  | 특징           | 예시                   |
+| ------------------------ | --------------------- | -------------- | ---------------------- |
+| 단위(Unit) 테스트        | 순수 로직 검증        | 빠르고 독립적  | 날짜 계산, 유효성 검사 |
+| 통합(Integration) 테스트 | 로직 간 상호작용 검증 | 실제 흐름 중심 | 컴포넌트 + API 호출    |
+
+---
+
+## 14. 좋은 테스트의 3대 원칙
+
+| 원칙     | 설명                          | 목표               |
+| -------- | ----------------------------- | ------------------ |
+| Fast     | 빠르게 실행되어야 한다        | 테스트 피드백 속도 |
+| Isolated | 다른 테스트에 영향받지 않는다 | 순서 의존 제거     |
+| Readable | 누구나 의도를 이해할 수 있다  | 문서처럼 읽힘      |
+
+---
+
+## 15. Kent Beck의 테스트 철학을 따른다
+
+- 테스트는 명확하고 간결해야 한다.
+- 한 테스트는 하나의 의도만 가져야 한다.
+- 실행 순서나 내부 구현에 의존하지 않는다.
+- 불필요한 Mock, setup, 중복을 제거한다.
+- 테스트는 “설계 품질의 피드백 루프”다.
+
+---
+
+## 16. 테스트는 제품 품질의 일부다
+
+- 테스트는 버그를 찾기 위한 도구가 아니라 **설계를 검증하는 문서**다.
+- TDD로 작성된 테스트는 더 나은 설계를 이끌어낸다.
+- 좋은 테스트는 유지보수 속도와 신뢰도를 높인다.
+
+---

.cursor/checklists/how-to-test.md

@@ -0,0 +1,78 @@
+Always follow the instructions in plan.md. When I say "go", find the next unmarked test in plan.md, implement the test, then implement only enough code to make that test pass.
+
+# ROLE AND EXPERTISE
+
+You are a senior software engineer who follows Kent Beck's Test-Driven Development (TDD) and Tidy First principles. Your purpose is to guide development following these methodologies precisely.
+
+# CORE DEVELOPMENT PRINCIPLES
+
+- Always follow the TDD cycle: Red → Green → Refactor
+- Write the simplest failing test first
+- Implement the minimum code needed to make tests pass
+- Refactor only after tests are passing
+- Follow Beck's "Tidy First" approach by separating structural changes from behavioral changes
+- Maintain high code quality throughout development
+
+# TDD METHODOLOGY GUIDANCE
+
+- Start by writing a failing test that defines a small increment of functionality
+- Use meaningful test names that describe behavior (e.g., "shouldSumTwoPositiveNumbers")
+- Make test failures clear and informative
+- Write just enough code to make the test pass - no more
+- Once tests pass, consider if refactoring is needed
+- Repeat the cycle for new functionality
+
+# TIDY FIRST APPROACH
+
+- Separate all changes into two distinct types:
+  1. STRUCTURAL CHANGES: Rearranging code without changing behavior (renaming, extracting methods, moving code)
+  2. BEHAVIORAL CHANGES: Adding or modifying actual functionality
+- Never mix structural and behavioral changes in the same commit
+- Always make structural changes first when both are needed
+- Validate structural changes do not alter behavior by running tests before and after
+
+# COMMIT DISCIPLINE
+
+- Only commit when:
+  1. ALL tests are passing
+  2. ALL compiler/linter warnings have been resolved
+  3. The change represents a single logical unit of work
+  4. Commit messages clearly state whether the commit contains structural or behavioral changes
+- Use small, frequent commits rather than large, infrequent ones
+
+# CODE QUALITY STANDARDS
+
+- Eliminate duplication ruthlessly
+- Express intent clearly through naming and structure
+- Make dependencies explicit
+- Keep methods small and focused on a single responsibility
+- Minimize state and side effects
+- Use the simplest solution that could possibly work
+
+# REFACTORING GUIDELINES
+
+- Refactor only when tests are passing (in the "Green" phase)
+- Use established refactoring patterns with their proper names
+- Make one refactoring change at a time
+- Run tests after each refactoring step
+- Prioritize refactorings that remove duplication or improve clarity
+
+# EXAMPLE WORKFLOW
+
+When approaching a new feature:
+
+1. Write a simple failing test for a small part of the feature
+2. Implement the bare minimum to make it pass
+3. Run tests to confirm they pass (Green)
+4. Make any necessary structural changes (Tidy First), running tests after each change
+5. Commit structural changes separately
+6. Add another test for the next small increment of functionality
+7. Repeat until the feature is complete, committing behavioral changes separately from structural ones
+
+Follow this process precisely, always prioritizing clean, well-tested code over quick implementation.
+
+Always write one test at a time, make it run, then improve structure. Always run all the tests (except long-running tests) each time.
+
+# TYPESCRIPT-SPECIFIC
+
+Update the rules to fit TypeScript.

.cursor/checklists/integration-test-quality.md

@@ -0,0 +1,101 @@
+# ✅ Integration Test Quality Checklist
+
+**목적:**  
+AI 또는 사람이 작성한 통합 테스트 코드가  
+명세 기반·사용자 중심·유지보수 가능한 수준으로 작성되었는지 평가하기 위한 품질 기준입니다.
+
+---
+
+## 🧭 1. 테스트 의도와 시나리오 일치성
+
+| 항목                       | 설명                                                            | Pass 기준                            | 상태 |
+| -------------------------- | --------------------------------------------------------------- | ------------------------------------ | ---- |
+| **1.1 Flow 매핑 정확성**   | 각 `it()` 테스트가 입력 문서의 Flow ID/Name과 정확히 대응하는가 | `it('2-1-1 - ...')` 형식으로 ID 일치 |      |
+| **1.2 시나리오 재현성**    | 테스트가 Input → Trigger → Output 순서를 따르는가               | 주석/코드로 순서 명시                |      |
+| **1.3 비즈니스 의도 일치** | 단순 DOM 확인이 아니라 사용자 행동 결과를 검증하는가            | 클릭 → 렌더링 결과 확인              |      |
+
+---
+
+## 🧩 2. 테스트 구조 및 가독성
+
+| 항목                       | 설명                                                        | Pass 기준                                | 상태 |
+| -------------------------- | ----------------------------------------------------------- | ---------------------------------------- | ---- |
+| **2.1 구조 계층화**        | Epic → Story → Flow 구조가 `describe` 계층으로 구현되었는가 | `describe('Story') → it('Flow')`         |      |
+| **2.2 테스트 이름 명확성** | `it()` 이름이 동작 중심 문장 형태로 되어 있는가             | 예: “반복 일정이 아이콘과 함께 표시된다” |      |
+| **2.3 AAA 패턴 분리**      | Arrange / Act / Assert 단계가 구분되어 있는가               | 빈 줄 또는 주석으로 분리                 |      |
+| **2.4 중복 제거**          | setup, mock, render 코드가 공통화되어 있는가                | `beforeEach`로 처리                      |      |
+| **2.5 주석 품질**          | “무엇을 하는가”보다 “왜 하는가”를 설명하는 주석인가         | 의도 중심 주석만 존재                    |      |
+
+---
+
+## 🧪 3. 테스트 행위(Behavior) 품질
+
+| 항목                            | 설명                                                               | Pass 기준               | 상태 |
+| ------------------------------- | ------------------------------------------------------------------ | ----------------------- | ---- |
+| **3.1 사용자 이벤트 기반 검증** | `userEvent`로 클릭·입력 등 사용자 행위를 재현했는가                | 직접 DOM 조작 금지      |      |
+| **3.2 비동기 안정성 확보**      | `await screen.findBy...` 또는 `waitFor` 사용으로 타이밍 제어했는가 | 즉시 `getBy` 검증 없음  |      |
+| **3.3 접근성 선택자 사용**      | `aria-label`, `role`, `alt`, `labelText`로 요소 탐색했는가         | `getByText`만 사용 금지 |      |
+| **3.4 상태 변화 검증**          | 내부 state가 아니라 UI 결과를 검증했는가                           | state 직접 참조 없음    |      |
+| **3.5 예외/부재 검증 포함**     | 조건부 UI(예: “아이콘 없음”)을 `queryBy`로 검증했는가              | 정상/예외 모두 커버     |      |
+
+---
+
+## 🧱 4. 코드 품질 및 안정성
+
+| 항목                  | 설명                                      | Pass 기준                      | 상태 |
+| --------------------- | ----------------------------------------- | ------------------------------ | ---- |
+| **4.1 비결정성 제거** | 랜덤값·시간 의존 로직이 없는가            | `Math.random`, `Date.now` 없음 |      |
+| **4.2 Mock 일관성**   | mock/stub이 일관된 형태로 정의되어 있는가 | `vi.fn()` 혹은 axios mock 통일 |      |
+| **4.3 테스트 독립성** | 테스트 간 전역 상태 공유 없이 동작하는가  | `beforeEach`로 상태 초기화     |      |
+| **4.4 Flaky 방지**    | `waitFor` 타임아웃, queryBy로 안정성 확보 | rerun 시 동일 결과             |      |
+
+---
+
+## 🧠 5. 테스트의 명세적 역할 (Kent Beck 기준)
+
+| 항목                   | 설명                                           | Pass 기준                  | 상태 |
+| ---------------------- | ---------------------------------------------- | -------------------------- | ---- |
+| **5.1 의도 명확성**    | 테스트가 “무엇을 증명하는가” 명확히 드러나는가 | 문서처럼 읽힘              |      |
+| **5.2 최소 검증 원칙** | 하나의 테스트가 하나의 결과만 검증하는가       | 독립된 `expect`만 존재     |      |
+| **5.3 리팩터링 내성**  | UI 구조 변경에도 검증 의미 유지되는가          | 라벨 기반 검증 사용        |      |
+| **5.4 유지보수성**     | 새 Flow 추가 시 구조 확장 용이한가             | Story별 describe 구조 유지 |      |
+
+---
+
+## 🧾 6. 메타 품질 (자동화 평가용)
+
+| 항목                   | 설명                                        | Pass 기준                        | 상태 |
+| ---------------------- | ------------------------------------------- | -------------------------------- | ---- |
+| **6.1 Flow 커버리지**  | 문서의 모든 Flow가 테스트로 작성되었는가    | 누락된 ID 없음                   |      |
+| **6.2 코드 길이 균형** | 각 테스트가 과도하게 길거나 복잡하지 않은가 | 20~40줄 내외                     |      |
+| **6.3 실행 안정성**    | 3회 이상 반복 실행 시 동일 결과인가         | flaky rate 0                     |      |
+| **6.4 네이밍 일관성**  | 파일명, describe명, it명 패턴 일관성 유지   | `{feature}-integration.spec.tsx` |      |
+
+---
+
+## 📊 평가 요약
+
+| 카테고리            | 가중치 | 평가 포인트                     |
+| ------------------- | ------ | ------------------------------- |
+| **시나리오 일치성** | 25%    | Flow 재현, 목적 명확            |
+| **구조/가독성**     | 20%    | AAA 구조, 네이밍 일관           |
+| **행위 품질**       | 25%    | 사용자 이벤트 중심, 접근성 검증 |
+| **코드 안정성**     | 15%    | mock 일관성, flaky 방지         |
+| **명세로서의 품질** | 15%    | 문서처럼 읽힘, 유지보수성       |
+
+> **총점 100점 중 80점 이상: Good Integration Test  
+> 90점 이상: Excellent Integration Test**
+
+---
+
+## 💬 사용 예시
+
+```bash
+[✅] Flow ID가 모두 매칭된다 (1.1)
+[✅] UI 렌더링 후 findBy로 검증 (3.2)
+[✅] 반복 일정 아이콘 aria-label로 검증 (3.3)
+[⚠️] queryByText 부재 검증 누락 (3.5)
+[✅] beforeEach로 render 공통화 (2.4)
+[❌] waitFor 누락 (3.2)
+총점: 88점 → Excellent 👍
+```