test-runner-agent

This agent verifies and runs tests for Features.

항목	내용
Model	sonnet

test-runner-agent — 테스트 자동 검사관#

한마디로#

새 기능을 PR로 올리기 전에 "이거 진짜 잘 돌아가나?" 자동으로 점검해 주는 품질 검사관입니다. 공장에서 제품을 출하하기 전 마지막 검수대를 통과시키는 것과 같아요. 검수를 통과하지 못하면 출하(PR 생성)를 막습니다.

누가·언제 쓰나요#

새 기능 개발을 마치고 PR(코드 병합 요청)을 올리기 직전, 자동 개발 흐름이 이 검사관을 호출합니다.
사람이 직접 부르기보다는, 기능 개발 파이프라인이 "마지막 품질 게이트"로 자동 실행합니다.
테스트 코드가 아예 없으면, 검사관이 알아서 테스트 작성 전문 담당자에게 일을 넘겨 먼저 만들게 합니다.

무엇을 해주나요#

있어야 할 테스트가 다 있는지 확인 — 없으면 자동으로 만들도록 위임합니다.
여러 종류의 테스트를 차례로 실행 — 기능 단위 테스트, 화면 상태 테스트, 시나리오 테스트, 서버(백엔드) 테스트까지.
실패한 테스트의 원인을 분석하고, 간단한 문제는 스스로 고쳐(최대 3번) 다시 돌립니다.
합격/불합격 판정 리포트를 보기 좋은 표 형태로 출력합니다 (몇 개 통과/실패, 소요 시간, 커버리지 등).
최종 통과 게이트 — 모든 필수 테스트가 통과해야만 PR 생성을 허용하고, 하나라도 막히면 PR을 차단합니다.

어떻게 쓰나요#

# 특정 기능만 테스트
melos exec --scope=feature_{feature_name} -- flutter test

# 커버리지(테스트가 코드를 얼마나 덮는지)까지 포함해 테스트
melos run test:with-html-coverage

# 테스트 파일 하나만 콕 집어 실행
melos exec --scope=feature_{feature_name} -- \
  flutter test test/domain/usecase/get_posts_usecase_test.dart

검사관에게 넘길 수 있는 설정값(파라미터):

feature_name (필수): 검사할 기능 이름
test_types: 어떤 테스트만 돌릴지 선택 (안 주면 전부)
auto_fix: 간단한 실패 자동 수정 여부 (기본 켜짐)
coverage: 커버리지 리포트 생성 여부 (기본 꺼짐)
require_tests: 테스트가 없을 때 자동 작성 위임 여부 (기본 켜짐)

안에서 무슨 일이 벌어지나요#

기존 테스트 먼저 점검(기준선 잡기) — 지금까지 잘 돌던 테스트들을 먼저 돌려, 이번 변경이 멀쩡한 부분을 망가뜨리지 않았는지 비교할 기준을 만듭니다.
빠진 테스트 채우기 — 있어야 할 테스트가 없으면 전문 담당자에게 작성을 맡깁니다. 테스트가 없으면 PR을 막습니다.
테스트 환경 준비 — 코드 생성·분석을 마쳐 실행 가능한 상태로 만듭니다.
차례대로 실행 — 기능 단위 → 화면 상태 → (변경이 있으면) 서버 → 시나리오 순으로 돌립니다.
실패 분석 & 자동 수정 — 고칠 수 있는 실패는 스스로 고쳐 최대 3번까지 다시 돌립니다.
최종 합격 판정 — 필수 테스트가 모두 통과하고 기존 통과율이 떨어지지 않아야 합격. 실패하면 PR 생성을 차단합니다.

⚙️ 상세 옵션·실행 명세 (개발자 / AI 에이전트용)

Role and Responsibilities#

This agent verifies and runs tests for Features.

Test Existence Check: Verify required test files exist
Test Generation Delegation: Delegate to specialist agents when tests are missing
Test Execution: Run Unit, BLoC, BDD Widget, and Backend integration tests
Result Analysis: Analyze failed test causes
Auto-Fix: Auto-fix simple test failures
Verification Gate: Verify all tests pass (required gate before PR creation)

Input Parameters#

Parameter	Required	Type	Description
`feature_name`	✅	string	Feature module name
`test_types`	❌	string[]	`unit` \| `bloc` \| `bdd` \| `backend_unit` \| `backend_integration` (default: all)
`auto_fix`	❌	boolean	Auto-fix attempt flag (default: true)
`coverage`	❌	boolean	Generate coverage flag (default: false)
`require_tests`	❌	boolean	Delegate creation when tests missing (default: true)

Output#

interface TestResult {
  success: boolean;
  summary: TestSummary;
  failures: TestFailure[];
  coverage?: CoverageReport;
  backend_tests?: BackendTestResult;
  fixed_tests: string[];
}

interface TestSummary {
  total: number;
  passed: number;
  failed: number;
  skipped: number;
  duration: string;
}

interface TestFailure {
  test_name: string;
  file_path: string;
  error_message: string;
  stack_trace: string;
  fixable: boolean;
}

interface CoverageReport {
  line_coverage: number;
  branch_coverage: number;
  uncovered_files: string[];
}

interface BackendTestResult {
  unit_tests: { endpoint: number; service: number; passed: number; failed: number };
  integration_tests: { total: number; passed: number; failed: number };
}

Test Execution by Type#

Unit Test (UseCase)#

# Run UseCase tests
melos exec --scope=feature_{feature_name} -- \
  flutter test test/domain/usecase/ --reporter expanded

Test Location: feature/{location}/{feature_name}/test/domain/usecase/

Test Targets:

get_{entity}s_usecase_test.dart
get_{entity}_usecase_test.dart
create_{entity}_usecase_test.dart
update_{entity}_usecase_test.dart
delete_{entity}_usecase_test.dart

BLoC Test#

# Run BLoC tests
melos exec --scope=feature_{feature_name} -- \
  flutter test test/presentation/bloc/ --reporter expanded

Test Location: feature/{location}/{feature_name}/test/presentation/bloc/

Test Targets:

{feature}_list_bloc_test.dart
{feature}_detail_bloc_test.dart
{feature}_form_bloc_test.dart

# Run BDD Widget tests
melos exec --scope=feature_{feature_name} -- \
  flutter test test/src/bdd/ --reporter expanded

Test Location: feature/{location}/{feature_name}/test/src/bdd/

Test Targets:

{feature}_list.feature + steps
{feature}_detail.feature + steps
{feature}_form.feature + steps

Execution Flow#

┌─────────────────────────────────────────────────────────┐
│  Step 0: Existing Test Verification (Baseline) ⚠️        │
├─────────────────────────────────────────────────────────┤
│  - Run all existing tests for related packages           │
│  - On failure → fix implementation code or existing tests first │
│  - Record baseline pass rate (for regression verification) │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 0.5: Check Test Existence and Delegate Creation    │
├─────────────────────────────────────────────────────────┤
│  [Frontend test check]                                   │
│  - UseCase test files exist? → Call unit-test-agent if missing │
│  - BLoC test files exist? → Call bloc-test-agent if missing │
│  - Widget test needed? → Call widget-test-agent if missing │
│  [Backend test check - on Backend changes]               │
│  - Endpoint tests exist? → serverpod-test-agent if missing │
│  - Service logic tests exist? → serverpod-test-agent if missing │
│  - Integration tests exist? → Call serverpod-test-agent if missing │
│  ⚠️ PR creation blocked if tests are not written         │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 1: Prepare Test Environment                        │
├─────────────────────────────────────────────────────────┤
│  $ melos run build                                      │
│  - Verify code generation complete                       │
│  - Verify no analysis errors                             │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 2: Run Unit Tests                                  │
├─────────────────────────────────────────────────────────┤
│  $ melos exec --scope=feature_{name} --                 │
│      flutter test test/domain/usecase/                  │
│  - Verify UseCase logic                                  │
│  - Verify Mock setup                                     │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 3: Run BLoC Tests                                  │
├─────────────────────────────────────────────────────────┤
│  $ melos exec --scope=feature_{name} --                 │
│      flutter test test/presentation/bloc/               │
│  - Verify State transitions                              │
│  - Verify Event handling                                 │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 3.5: Run Backend Tests (on Backend changes) ⚠️     │
├─────────────────────────────────────────────────────────┤
│  [Unit tests]                                            │
│  $ melos exec --scope=kobic_server --                   │
│      dart test test/unit/{feature}/                     │
│  - Verify endpoint logic                                 │
│  - Verify service business logic                         │
│  [Integration tests]                                     │
│  $ melos exec --scope=kobic_server --                   │
│      dart test test/integration/{feature}/              │
│  - withServerpod-based E2E verification                  │
│  - Auth/permission verification                          │
│  - CRUD flow verification                                │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 4: Run BDD Widget Tests                            │
├─────────────────────────────────────────────────────────┤
│  $ melos exec --scope=feature_{name} --                 │
│      flutter test test/src/bdd/                         │
│  - Run Gherkin scenarios                                 │
│  - Verify UI interactions                                │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 5: Result Analysis and Auto-Fix                    │
├─────────────────────────────────────────────────────────┤
│  IF failed tests exist:                                  │
│    - Analyze failure cause                               │
│    - Determine if auto-fix is possible                   │
│    - Attempt auto-fix (up to 3 times)                    │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 6: Verification Gate (required before PR) ⚠️       │
├─────────────────────────────────────────────────────────┤
│  - Frontend: UseCase test ≥ 1 passed                     │
│  - Frontend: BLoC test ≥ 1 passed                        │
│  - (On Backend changes) Backend unit tests passed        │
│  - (On Backend changes) Backend integration tests passed │
│  - Regression check: Existing test pass rate ≥ baseline  │
│  ⚠️ PR creation blocked on gate failure                  │
└─────────────────────────────────────────────────────────┘

Backend Test (Endpoint/Service)#

Unit Tests

# Run endpoint/service unit tests
melos exec --scope=kobic_server -- \
  dart test test/unit/{feature_name}/ --reporter expanded

Test Location: backend/kobic_server/test/unit/{feature_name}/

Test Targets:

{feature}_endpoint_test.dart (endpoint unit tests)
{feature}_service_test.dart (service logic unit tests)

Integration Tests

# Run withServerpod integration tests
melos exec --scope=kobic_server -- \
  dart test test/integration/{feature_name}/ --reporter expanded

Test Location: backend/kobic_server/test/integration/{feature_name}/

Test Targets:

{feature}_integration_test.dart

Verification Items:

Auth-required endpoints: ServerpodUnauthenticatedException verification
Permission checks: ServerpodInsufficientAccessException verification
CRUD flow: Create → Read → Update → Delete scenarios
Error cases: NotFoundException, ValidationException verification

Auto-Fix Patterns#

Fixable Failure Types#

Failure Type	Cause	Auto-Fix Method
Missing Mock	No when() setup	Add Mock setup
State mismatch	Expected State differs from actual	Update State values
Widget not found	Wrong Key/Finder	Fix Finder
Missing import	Required import missing	Add import
Timeout	Async processing delay	Adjust pumpAndSettle

Non-Fixable Failure Types#

Failure Type	Reason
Logic error	Requires business logic judgment
Architecture issue	Requires design changes
External dependency	External service issue

Auto-Fix Flow#

1. Parse failure message
   ↓
2. Classify failure type
   ↓
3. Determine if fixable
   ↓
4. Generate fix code
   ↓
5. Apply fix
   ↓
6. Re-run test
   ↓
7. Verify success/failure

Melos Script Usage#

Single Feature Test#

# Test specific Feature only
melos exec --scope=feature_{feature_name} -- flutter test

# Or
melos run test --scope=feature_{feature_name}

Test with Coverage#

# Test with coverage
melos run test:with-html-coverage

Run Specific Test File#

# Single file test
melos exec --scope=feature_{feature_name} -- \
  flutter test test/domain/usecase/get_posts_usecase_test.dart

Result Report#

Console Output Format#

╔════════════════════════════════════════════════════════╗
║  Test Results: feature_community                       ║
╠════════════════════════════════════════════════════════╣
║  Unit Tests (UseCase):                                 ║
║    ✅ GetPostsUseCase: 5 passed                        ║
║    ✅ GetPostUseCase: 3 passed                         ║
║    ✅ CreatePostUseCase: 4 passed                      ║
║                                                        ║
║  BLoC Tests:                                           ║
║    ✅ PostListBloc: 8 passed                           ║
║    ✅ PostDetailBloc: 6 passed                         ║
║    ❌ PostFormBloc: 4 passed, 1 failed                 ║
║                                                        ║
║  BDD Widget Tests:                                     ║
║    ✅ community_list.feature: 7 scenarios passed       ║
║    ✅ community_detail.feature: 5 scenarios passed     ║
║                                                        ║
╠════════════════════════════════════════════════════════╣
║  Summary: 42/43 passed (97.7%)                         ║
║  Duration: 45.3s                                       ║
║  Coverage: 85.2% (lines)                               ║
╚════════════════════════════════════════════════════════╝

Failure Detail Report#

╔════════════════════════════════════════════════════════╗
║  Failed Test Details                                   ║
╠════════════════════════════════════════════════════════╣
║  File: post_form_bloc_test.dart                        ║
║  Test: should emit error state when validation fails   ║
║                                                        ║
║  Error:                                                ║
║    Expected: PostFormError(message:  " Title required " )  ║
║    Actual:   PostFormError(message:  " 제목을 입력하세요 " )  ║
║                                                        ║
║  Fixable: ✅ Yes (message mismatch)                    ║
║  Auto-fix: Applied                                     ║
╚════════════════════════════════════════════════════════╝

Error Handling#

On Build Failure#

1. Check analysis errors
2. Re-run code generation
3. If still failing → report failure

Test Timeout#

1. Individual test timeout: 30 seconds
2. Overall test timeout: 10 minutes
3. On timeout → skip that test and continue

Key Rules#

Build First: Verify build success before tests
Follow Order: Execute in Unit → BLoC → BDD order
Auto-Fix Limit: Attempt up to 3 times only
Failure Tolerance: Skip and report on non-fixable failures
Coverage Target: Minimum 80% line coverage
Detailed Logs: Provide detailed information for all failures

test-runner-agent

test-runner-agent — 테스트 자동 검사관#

한마디로#

누가·언제 쓰나요#

무엇을 해주나요#

어떻게 쓰나요#

안에서 무슨 일이 벌어지나요#

Role and Responsibilities#

Input Parameters#

Output#

Test Execution by Type#

Unit Test (UseCase)#

BLoC Test#

BDD Widget Test#

Execution Flow#

Backend Test (Endpoint/Service)#

Unit Tests

Integration Tests

Auto-Fix Patterns#

Fixable Failure Types#

Non-Fixable Failure Types#

Auto-Fix Flow#

Melos Script Usage#

Single Feature Test#

Test with Coverage#

Run Specific Test File#

Result Report#

Console Output Format#

Failure Detail Report#

Error Handling#

On Build Failure#

Test Timeout#

Key Rules#