Test Driven Development Aim

Write code before the test? Delete it. Start over.

No exceptions:

• Don't keep it as "reference"
• Don't "adapt" it while writing tests
• Don't look at it
• Delete means delete

Implement fresh from tests. Period.

Red-Green-Refactor

digraph tdd_cycle {
    rankdir=LR;
    red [label="RED\nWrite failing gtest", shape=box, style=filled, fillcolor="#ffcccc"];
    verify_red [label="dx make gtest\nfails correctly?", shape=diamond];
    green [label="GREEN\nMinimal C code", shape=box, style=filled, fillcolor="#ccffcc"];
    verify_green [label="dx make gtest\nall pass?", shape=diamond];
    refactor [label="REFACTOR\nClean + dx make", shape=box, style=filled, fillcolor="#ccccff"];
    next [label="Next", shape=ellipse];

    red -> verify_red;
    verify_red -> green [label="yes"];
    verify_red -> red [label="wrong\nfailure"];
    green -> verify_green;
    verify_green -> refactor [label="yes"];
    verify_green -> green [label="no"];
    refactor -> verify_green [label="stay\ngreen"];
    verify_green -> next;
    next -> red;
}

RED - Write Failing Test

Write one minimal GoogleTest showing what should happen.

EXPECT_EQ(rc, AIM_OK);
EXPECT_EQ(attempts, 3);

}

Clear name, tests real behavior, one thing
</Good>

<Bad>
```cpp
TEST(AimRetry, TestRetry) {
    // just calls the function and checks return
    EXPECT_EQ(aim_retry_operation(NULL, 0), 0);
}

Vague name, doesn't verify actual retry count </Bad>

Requirements:

• One behavior per test
• Clear descriptive name (TestSuite, TestName)
• Real code (avoid mocking unless unavoidable)

Verify RED - Watch It Fail

MANDATORY. Never skip.

빌드 스코프 최소화 (시간 절약): RED 단계에서는 방금 추가한 테스트 바이너리만 빌드/실행한다. 전체 dx make gtest는 금지 — 불필요한 전체 재컴파일로 빌드 4회가 누적되어 태스크당 20분 이상 낭비된다.

# gtest 실행 전 서버 종료 (Text file busy 방지)
dx tmdown -y

# 방금 추가한 테스트 바이너리만 빌드/실행
dx bash -c "cd /root/ofsrc/aim/test/unit/gtest/src/<zone>/<module> && make -f Makefile_<target> && ./gtest_<module>_<target>"

Confirm:

• Test fails (not build errors)
• Failure message is expected
• Fails because feature missing (not typos or link errors)

Test passes? You're testing existing behavior. Fix test.

Build error? Fix build error first, re-run until it fails correctly.

GREEN - Minimal Code

Write simplest C code to pass the test.

Don't add features, refactor other code, or "improve" beyond the test.

Verify GREEN - Watch It Pass

MANDATORY.

빌드 스코프 최소화: 태스크 중간에는 수정한 모듈의 테스트만 실행한다. 전체 dx make gtest(전 모듈 회귀)는 모든 태스크 완료 후 1회만 수행 (verification-before-completion-aim에서 처리).

# 서버 종료 후 해당 모듈 테스트만 재빌드/실행
dx tmdown -y
dx bash -c "cd /root/ofsrc/aim/test/unit/gtest/src/<zone>/<module> && make && ./gtest_<module>_<target>"

Confirm:

• Test passes
• Modified module's other tests still pass
• No warnings or errors in output

Then verify production build:

dx make

Test fails? Fix code, not test.

Build fails? Fix now.

REFACTOR - Clean Up

After green only:

• Remove duplication
• Improve names
• Extract helpers
• Run clang-format -i on changed files

Keep tests green. Don't add behavior.

dx make gtest   # still green after refactor
dx make         # production build still clean

Repeat

Next failing test for next feature.

AIM-Specific Testing Patterns

Static Function Testing

Static functions that need testing must be promoted:

1. Remove static keyword
2. Keep underscore prefix (_helper_func)
3. Declare in {SOURCE FILE}.h with block comment:

/******************************************************************************
 *                          Static Function                                   *
 *Although it is a static function, it is declared as follows for unit testing*
 ******************************************************************************/
int _aim_parse_header(const char *buf, aim_header_t *hdr);

4. Remove forward declaration from .c file
5. Include {SOURCE FILE}.h in the .c file

Test File Organization

소스 트리와 테스트 트리가 1:1 대응한다:

src/<zone>/<module>/<source>.c
  → test/unit/gtest/src/<zone>/<module>/gtest_<module>_<function>.cpp

예시:

src/lib/acp/acp_parser.c
  → test/unit/gtest/src/lib/acp/gtest_acp_acp_parser.cpp

• 네이밍: gtest_<module>_<function>.cpp — 함수 1개당 cpp 1개 권장
• 예외: 함수 간 결합이 강한 경우(연속 호출/동일 워크플로우)는 1개 cpp 허용
• 디렉토리: test/unit/gtest/src/<zone>/<module>/

Test Authoring Rules

핵심 규칙 (test/unit/gtest/AGENTS.override.md 전체 기준 적용):

• 구조: setup / exercise / verify / cleanup
• 주석: 영어로 작성
  • Test Fixture class 위: 테스트 suite 목적, 대상 함수, mock 대상 기술
  • 각 TEST_F 위: 검증 내용 간략 기술, 정상/오류 경로 명시
• 신규 테스트는 최소 정상 경로 1개 + 오류 경로 1개 포함
• 테스트 내부에서 구조체/상수/extern 재정의 금지 — 실제 헤더를 include

Mocking Rules

• 외부 호출 검증: gmock (EXPECT_CALL, Times) 우선
• mock 필요한 cpp만 Makefile_<target>으로 분리. mock 불필요 테스트는 기본 Makefile의 SOURCES에 추가
• 제품 코드(.c, .h)에 테스트 전용 함수 추가 금지 — static 승격 또는 symbol 가로채기로 해결
• symbol 가로채기(mock wrapper): extern "C" 직접 감싸지 않고, 원본 헤더의 extern "C" guard에 의존

Coverage Requirement

커버리지 측정 시 반드시 make clean && make gtest 실행. make gtest-run만 하면 소스 .o가 커버리지 플래그 없이 빌드된 캐시가 남아 .gcda가 생성되지 않음 (커버리지 0%).

gtest 실행 전 dx tmdown -y 필수 — 실행 중인 서버 바이너리가 Text file busy를 유발하여 cp aimdcms 등에서 실패한다. 개별 tmdown -s <server>는 의존 서버(aimidcm 등)가 많아 불완전하므로 전체 종료를 사용한다.

dx tmdown -y
dx bash -c "cd /root/ofsrc/aim && make clean && make gtest"
dx bash -c "cd /root/ofsrc/aim && bash .claude/skills/code-reviewer-aim/scripts/measure_diff_cov.sh"

미커버 라인 식별: gcov를 직접 grep/awk로 파싱하지 말 것. gcov 출력이 메타데이터 5줄만 나오는 재현성 있는 현상이 관찰됨. measure_diff_cov.sh 출력 + dx git diff --unified=0 <base>..HEAD 조합으로 추가 라인을 직접 확인한다.

mock 바이너리가 있는 경우 빌드하지 않고 실행만 추가 (빌드하면 gcda 리셋):

dx bash -c "cd /root/ofsrc/aim/test/unit/gtest/src/<zone>/<module> && ./gtest_<module>_<target>"

80% added-code line coverage required. If below, write more tests.

Good Tests

Why Order Matters

"I'll write tests after to verify it works"

Tests written after code pass immediately. Passing immediately proves nothing:

• Might test wrong thing
• Might test implementation, not behavior
• Might miss edge cases you forgot
• You never saw it catch the bug

"I already manually tested all the edge cases"

Manual testing is ad-hoc:

• No record of what you tested
• Can't re-run when code changes
• Easy to forget cases under pressure
• "It worked when I tried it" != comprehensive

"Deleting X hours of work is wasteful"

Sunk cost fallacy. The time is already gone. Working code without real tests is technical debt.

"TDD is dogmatic, being pragmatic means adapting"

TDD IS pragmatic: finds bugs before commit, prevents regressions, documents behavior, enables refactoring. "Pragmatic" shortcuts = debugging in production = slower.

Common Rationalizations

Red Flags - STOP and Start Over

• Code before test
• Test after implementation
• Test passes immediately
• Can't explain why test failed
• Tests added "later"
• Rationalizing "just this once"
• "I already manually tested it"
• "Tests after achieve the same purpose"
• "It's about spirit not ritual"
• "Keep as reference" or "adapt existing code"
• "Already spent X hours, deleting is wasteful"
• "Static function, can't test it" (promote it!)
• "This is different because..."

All of these mean: Delete code. Start over with TDD.

Example: Bug Fix (C/GoogleTest)

Bug: Empty message queue name accepted

RED

TEST(AimMqn, RejectsEmptyQueueName) {
    int rc = aim_mqn_validate("");
    EXPECT_EQ(rc, AIM_ERR_INVALID_PARAM);
}

Verify RED

$ dx make gtest
[ FAILED ] AimMqn.RejectsEmptyQueueName
  Expected: AIM_ERR_INVALID_PARAM
  Actual: AIM_OK

GREEN

int aim_mqn_validate(const char *mqn) {
    if (mqn == NULL || mqn[0] == '\0') {
        return AIM_ERR_INVALID_PARAM;
    }
    // existing validation...
}

Verify GREEN

$ dx make gtest
[  PASSED  ] AimMqn.RejectsEmptyQueueName
$ dx make
Build complete.

REFACTOR Extract validation for reuse if needed. clang-format -i on changed files.

Verification Checklist

Before marking work complete:

• Every new function has a gtest
• Watched each test fail before implementing
• Each test failed for expected reason (feature missing, not build error)
• Wrote minimal code to pass each test
• All tests pass (dx make gtest)
• Production build clean (dx make)
• Coverage >= 80% on added code
• clang-format -i applied

Can't check all boxes? You skipped TDD. Start over.

When Stuck

Debugging Integration

Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression.

Never fix bugs without a test.

Testing Anti-Patterns

When adding test utilities or isolating dependencies, read @testing-anti-patterns.md to avoid common pitfalls:

• Testing stub behavior instead of real behavior
• Adding test-only methods to production code
• Over-isolating without understanding dependencies

Final Rule

Production code -> test exists and failed first
Otherwise -> not TDD

No exceptions without user's explicit permission.

Integration

Called by:

• executing-plans-aim — 각 태스크 실행 시
• subagent-driven-development-aim — implementer 서브에이전트 내부
• systematic-debugging-aim Phase 4 — 수정 검증 테스트 작성 시
• receiving-code-review-aim — 리뷰 피드백 기반 로직 수정 시