Gnuboard7/docs/ai-tools/skills/run-tests.md

테스트 실행 (run-tests)

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

1단계: 규정 문서 읽기

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

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

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

⚠️ 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

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

4단계: 테스트 실행

백엔드 테스트 (PHPUnit)

# 관련 테스트만 실행 (권장)
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 -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)

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

# 코어 레이아웃 테스트
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"

기본 패턴:

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();

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

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

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

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

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

6단계: 결과 분석 및 보고

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

## 테스트 결과

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

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

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

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

중요 원칙

⚠️ 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/** 변경 → 해당 모듈 테스트