# 테스트 실행 (run-tests)

그누보드7 프로젝트의 테스트를 실행하고 결과를 검증합니다.

## 1단계: 규정 문서 읽기

다음 규정 문서를 읽어 최신 규칙을 확인합니다:

- `docs/testing-guide.md` - 테스트 규칙
- `docs/frontend/layout-testing.md` - 레이아웃 렌더링 테스트 규칙

## 2단계: .env.testing 확인 (백엔드 테스트 시)

```text
⚠️ CRITICAL: 백엔드 테스트 실행 전 .env.testing 존재 여부 확인 필수
```

1. `.env.testing` 미존재 시:
   - `.env.testing.example` 복사: `cp .env.testing.example .env.testing`
   - `APP_KEY` 생성: `php artisan key:generate --env=testing`
   - PO에게 DB 접속 정보 확인 요청

## 3단계: 테스트 타입 결정

$ARGUMENTS 값에 따라 테스트 타입을 결정합니다:

| 인자 | 테스트 타입 | 명령어 |
|------|-------------|--------|
| `backend` 또는 `php` | 백엔드 테스트 | `php artisan test` |
| `frontend` 또는 `npm` | 프론트엔드 테스트 | `powershell -Command "npm run test:run"` |
| `layout` | 레이아웃 렌더링 테스트 | `powershell -Command "npm run test:run -- layouts"` |
| `all` 또는 미지정 | 전체 테스트 | 백엔드 + 프론트엔드 순차 실행 |
| 특정 파일/클래스명 | 필터 테스트 | `php artisan test --filter=$ARGUMENTS` |

```text
⚠️ CRITICAL: 전체 테스트(all) 지양 → 관련 테스트만 실행 (시간 절약)
⚠️ CRITICAL: 동일 테스트를 결과 확인 목적으로 재실행 금지 → 저장된 출력 확인
```

## 4단계: 테스트 실행

### 백엔드 테스트 (PHPUnit)

```bash
# 관련 테스트만 실행 (권장)
php artisan test --filter=TestClassName 2>&1 | tee /tmp/test-result.txt

# 특정 디렉토리
php vendor/bin/phpunit tests/Feature/Api/Admin/ 2>&1 | tee /tmp/test-result.txt

# _bundled 모듈 테스트 (활성 디렉토리 복사 불필요)
php vendor/bin/phpunit modules/_bundled/sirsoft-ecommerce/tests 2>&1 | tee /tmp/test-result.txt
php vendor/bin/phpunit --filter=TestClassName modules/_bundled/sirsoft-ecommerce/tests 2>&1 | tee /tmp/test-result.txt
```

### 프론트엔드 테스트 (Vitest)

```powershell
# 프로젝트 루트에서 (코어 테스트)
powershell -Command "npm run test:run -- template-engine"

# 템플릿 디렉토리에서 (해당 템플릿만)
powershell -Command "cd templates/sirsoft-admin_basic; npm run test:run"
powershell -Command "cd templates/sirsoft-admin_basic; npm run test:run -- DataGrid"

# _bundled 모듈 프론트엔드 테스트
powershell -Command "cd modules/_bundled/sirsoft-ecommerce; npm run test:run"
```

### 레이아웃 렌더링 테스트 (Vitest + createLayoutTest)

```text
⚠️ CRITICAL: 레이아웃 렌더링 테스트는 Vitest + createLayoutTest() 유틸리티 기반
⚠️ CRITICAL: 브라우저 기반 E2E가 아님 — "인프라 부족" 이유로 건너뛰기 절대 금지
```

```powershell
# 코어 레이아웃 테스트
powershell -Command "npm run test:run -- layouts"

# 모듈 레이아웃 테스트
powershell -Command "cd modules/_bundled/sirsoft-ecommerce; npm run test:run -- layouts"

# 템플릿 레이아웃 테스트
powershell -Command "cd templates/_bundled/sirsoft-admin_basic; npm run test:run -- layouts"
```

**기본 패턴**:

```typescript
import { createLayoutTest, screen } from '../utils/layoutTestUtils';

const testUtils = createLayoutTest(layoutJson);
testUtils.mockApi('products', { response: { data: [] } });
await testUtils.render();
expect(screen.getByTestId('element')).toBeInTheDocument();
testUtils.cleanup();
```

```text
⚠️ CRITICAL: 테스트 출력은 반드시 파일로 저장
✅ 패턴: 명령어 2>&1 | tee /tmp/test-result.txt
❌ 실패 후 결과 확인 목적 재실행 금지 → /tmp/test-result.txt 확인
```

## 5단계: 다계층 테스트 확인 (CRITICAL)

기능 구현 시 **모든 관련 계층**의 테스트가 실행되었는지 확인합니다.

| 작업 유형 | 백엔드 (PHPUnit) | 프론트엔드 (Vitest) | 레이아웃 렌더링 (Vitest) |
|----------|-----------------|-------------------|----------------------|
| 새 화면 구현 | API 엔드포인트 테스트 | 컴포넌트 테스트 | 레이아웃 JSON 렌더링 테스트 |
| 기존 화면 수정 | 변경된 API 테스트 | 변경된 컴포넌트 테스트 | 레이아웃 렌더링 회귀 테스트 |
| 데이터 흐름 변경 | Service/Repository 테스트 | 상태 관리 테스트 | 데이터 바인딩 렌더링 테스트 |

```text
❌ 단일 계층 테스트만으로 기능 구현 완료 선언 금지
❌ 백엔드 API만 테스트하고 프론트엔드/레이아웃 테스트 누락
❌ 컴포넌트만 테스트하고 레이아웃 렌더링 테스트 누락
```

## 6단계: 결과 분석 및 보고

테스트 결과를 다음 형식으로 보고합니다:

```
## 테스트 결과

### 실행 환경
- 테스트 타입: [backend/frontend/layout/all]
- 실행 명령어: [실행한 명령어]

### 결과 요약
- 총 테스트: [N]개
- 통과: [N]개 ✅
- 실패: [N]개 ❌
- 스킵: [N]개 ⏭️

### 다계층 테스트 확인
- □ 백엔드 테스트: [실행/미해당]
- □ 프론트엔드 테스트: [실행/미해당]
- □ 레이아웃 렌더링 테스트: [실행/미해당]

### 실패 테스트 상세 (있는 경우)
- ❌ [테스트명]
  - 파일: [파일 경로]
  - 원인: [실패 원인]
  - 수정 방향: [제안]
```

## 중요 원칙

```text
⚠️ CRITICAL:
- Windows 환경에서 프론트엔드 테스트는 반드시 PowerShell 래퍼 사용
- 테스트 작성 ≠ 완료, 테스트 통과 = 완료
- 템플릿 엔진/컴포넌트 수정 시 테스트 필수
- 기능 구현 시 다계층 테스트 필수 (백엔드 + 프론트엔드 + 레이아웃 렌더링)
- 레이아웃 렌더링 테스트는 createLayoutTest() 유틸리티로 실행 (브라우저 불필요)
- "인프라 부족" 이유로 레이아웃 테스트 건너뛰기 절대 금지
- 테스트 출력은 파일로 저장 → 동일 테스트 재실행 금지
- 전체 테스트 실행 지양 → 관련 테스트만 실행
```

## 테스트 파일 위치 매핑

| 수정 대상 | 테스트 파일 위치 | 테스트 유형 |
|----------|-----------------|-------------|
| `app/Models/*.php` | `tests/Unit/Models/*Test.php` | 모델 메서드, 관계, 스코프 |
| `app/Services/*.php` | `tests/Unit/Services/*Test.php` | 비즈니스 로직 |
| `app/Enums/*.php` | `tests/Unit/Enums/*Test.php` | Enum 메서드 |
| `app/Http/Controllers/**/*.php` | `tests/Feature/**/*Test.php` | API 엔드포인트 |
| `database/migrations/*.php` | 해당 모델/서비스 테스트 | 스키마 변경 |
| `templates/**/src/components/**/*.tsx` | `templates/**/__tests__/*.test.tsx` | 컴포넌트 |
| `resources/js/core/**/*.ts` | `resources/js/core/__tests__/*.test.ts` | 템플릿 엔진 |
| `resources/layouts/**/*.json` | `resources/js/core/template-engine/__tests__/layouts/*.test.tsx` | 코어 레이아웃 렌더링 |
| `modules/**/resources/layouts/**/*.json` | `modules/_bundled/{id}/resources/js/__tests__/layouts/*.test.tsx` | 모듈 레이아웃 렌더링 |
| `templates/**/layouts/**/*.json` | `templates/_bundled/{id}/__tests__/layouts/*.test.tsx` | 템플릿 레이아웃 렌더링 |

## 자동 감지

다음 파일이 수정된 경우 관련 테스트를 자동으로 실행합니다:

- `resources/js/core/` 변경 → 템플릿 엔진 테스트
- `resources/js/core/template-engine/` 변경 → 코어 렌더링 테스트
- `app/Http/Controllers/` 변경 → 해당 컨트롤러 테스트
- `app/Services/` 변경 → 해당 서비스 테스트
- `resources/layouts/**/*.json` 변경 → 코어 레이아웃 렌더링 테스트
- `modules/**/resources/layouts/**/*.json` 변경 → 해당 모듈 레이아웃 렌더링 테스트
- `templates/**/layouts/**/*.json` 변경 → 해당 템플릿 레이아웃 렌더링 테스트
- `templates/**/src/components/**/*.tsx` 변경 → 해당 컴포넌트 테스트
- `modules/_bundled/**/src/**` 변경 → 해당 모듈 테스트