Testing Skill

Test writing standards and quality guidelines following Classical TDD (state verification only).

Quick Reference

Core Philosophy

Tests serve three purposes: verify correctness, document behavior, and enable safe refactoring.

• •Tests as Executable Documentation: Tests are the most accurate documentation because they're always up-to-date.
• •Tests Enable Fearless Refactoring: With good tests, you can safely change implementation. But this only works if tests verify behavior, not implementation.
• •Tests Reveal Design Problems: If a test is hard to write, that's feedback about your design.

The Iron Law

VERIFY STATE, NEVER INTERACTIONS.
NO EXCEPTIONS. NO NEGOTIATIONS.

This applies to ALL tests:

• •Not "except for simple utilities"
• •Not "except when state verification is hard"
• •Not "except when the team already uses verify()"
• •Not "just this once"

Violating the letter of this rule IS violating the spirit.

🚨 Red Flags - STOP If You Think These

These thoughts mean you're rationalizing. STOP and reconsider:

All of these mean: Follow the rules anyway.

Rationalization Table

Common excuses and why they're wrong:

Decision Flow: When Rules Feel Burdensome

digraph rule_check {
    "Rule feels unnecessary?" [shape=diamond];
    "Is this a real technical limitation?" [shape=diamond];
    "STOP - You're rationalizing" [shape=box, style=filled, fillcolor="#ffcccc"];
    "Consult references for the pattern" [shape=box];
    "Can you redesign to enable state verification?" [shape=diamond];
    "Follow the rule anyway" [shape=box, style=filled, fillcolor="#ccffcc"];
    "Document limitation, propose design change" [shape=box];

    "Rule feels unnecessary?" -> "Is this a real technical limitation?" [label="yes"];
    "Rule feels unnecessary?" -> "STOP - You're rationalizing" [label="no, just inconvenient"];
    "Is this a real technical limitation?" -> "Can you redesign to enable state verification?" [label="maybe"];
    "Is this a real technical limitation?" -> "STOP - You're rationalizing" [label="not really"];
    "Can you redesign to enable state verification?" -> "Follow the rule anyway" [label="yes"];
    "Can you redesign to enable state verification?" -> "Document limitation, propose design change" [label="truly impossible"];
    "STOP - You're rationalizing" -> "Consult references for the pattern";
    "Consult references for the pattern" -> "Follow the rule anyway";
}

CRITICAL: State/Result Verification ONLY (Classical TDD)

This project follows Classical TDD (Detroit School). All tests MUST verify outcomes, NOT interactions.

Verify WHAT happened, not HOW it happened.

✅ ALLOWED

assertThat(result).isEqualTo(expected)
assertThat(point.balance).isEqualTo(700L)
assertThatThrownBy { point.use(500L) }.isInstanceOf(CoreException::class.java)

❌ FORBIDDEN

verify(repository).save(any())
verify(mock, times(1)).method()
verifyNoInteractions(mock)

// ❌ ALSO FORBIDDEN: "Hybrid approach" - state + verify()
assertThat(order.status).isEqualTo(OrderStatus.PLACED)  // state verification ✅
verify(paymentClient).requestPayment(any())              // then verify ❌ STILL FORBIDDEN!

No "extra insurance" verify(): If you did state verification, you're done. Adding verify() for "safety" is still forbidden.

Test Level Overview

For level classification criteria, decision flow, and file naming conventions, see references/test-level-guide.md

BDD Structure

Nested Classes

Use @Nested per behavior (method/endpoint). No more than 1 level of nesting.

@Nested
@DisplayName("use")
inner class Use {
    // All cases for use()
}

Naming Convention

• •@DisplayName: Korean description
• •Method name: English with backticks, [result] when [condition]

Given/When/Then

Every test must have comments specifying concrete values and expected results.

@Test
@DisplayName("주문 금액이 올바르게 계산된다")
fun `calculates total correctly`() {
    // given
    val initialBalance = 1000L
    val point = createPoint(balance = initialBalance)

    // when
    val deductAmount = 300L
    point.deduct(deductAmount)

    // then
    assertThat(point.balance).isEqualTo(initialBalance - deductAmount)
}

Factory Method Pattern

Every test class must have private factory methods with all parameters defaulted.

// Unit Test: domain object creation
private fun createPoint(
    id: Long = 0L,
    userId: Long = 1L,
    balance: Long = 1000L,
    status: PointStatus = PointStatus.ACTIVE,
): Point = Point.of(id, userId, balance, status)

// Integration Test: includes DB persistence
private fun createProduct(
    price: Money = Money.krw(10000),
    stockQuantity: Int = 100,
): Product {
    val brand = brandRepository.save(Brand.create("Test Brand"))
    val product = productRepository.save(Product.create(name = "Test Product", price = price, brand = brand))
    stockRepository.save(Stock.create(product.id, stockQuantity))
    return product
}

Essential Rules

Expose Only What Matters

// ❌ Bad: What is this test about?
val point = Point.of(id = 1L, userId = 42L, balance = 1000L, status = PointStatus.ACTIVE)

// ✅ Good: Clearly about balance deduction
val point = createPoint(balance = 1000L)

Single Logical Assertion

Each test verifies one behavior. Multiple assertThat is fine if they verify aspects of the same result.

Meaningful Variable Names

// ❌ Bad
assertThat(result).isEqualTo(700)

// ✅ Good
val initialBalance = 1000L
val deductAmount = 300L
assertThat(point.balance).isEqualTo(initialBalance - deductAmount)

Test Isolation

• •No shared mutable state
• •Database cleanup in @AfterEach
• •No test interdependence

When to Skip Test Generation

Pure data objects with no behavior

• •Command - use case input (e.g., CreateOrderCommand)
• •Event - immutable fact record (e.g., OrderCreatedEvent)
• •DTO / Request / Response - data transfer only

Infrastructure triggers with no business logic

• •Scheduler - @Scheduled methods that only invoke service methods
  • •Scheduler's responsibility is only "when to call", not "what to do"
  • •Test the invoked service method instead (Integration Test)
  • •Cron expression correctness is Spring Framework's responsibility

References

Load references based on the current task. Each file provides detailed patterns and real code examples.

When determining test level

• •references/test-level-guide.md - Level classification criteria and decision flow

When generating test skeletons

• •references/test-generation.md - Spec to test skeleton process, quality checklist

When writing tests by level

• •references/unit-test.md - Unit test patterns (state change, validation, ParameterizedTest, domain events)
• •references/integration-test.md - Integration patterns (rollback, Spring Event, Kafka Consumer)
• •references/concurrency-test.md - Concurrency patterns (thread pool, locking, idempotency)
• •references/adapter-test.md - Adapter patterns (WireMock, Circuit Breaker, Retry, complex queries)
• •references/e2e-test.md - E2E patterns (HTTP status codes, auth failures, API contract)
• •references/batch-test.md - Spring Batch patterns (Processor unit test, Step/Job integration test)

When deciding external dependencies strategy

• •references/external-dependencies.md - External dependencies by test level (Real DB, WireMock, Testcontainers)

Common Mistakes