Critical Rules

These rules are non-negotiable and must be followed for all tests:

1. Test Coverage Requirements

• •Every public interface in domain and application layers must have tests
• •Every use case handler (command/query/operation) must have tests
• •Every adapter implementation must have tests
• •Critical business logic must have 100% branch coverage
• •Edge cases and error paths must be explicitly tested

2. Test Naming

Tests must clearly communicate their intent using Given-When-Then format:

Given [initial context/state]
When [action/event occurs]
Then [expected outcome]

The test method name should be descriptive and reflect the scenario.

3. Test Structure (Given-When-Then)

Every test must follow the Given-When-Then pattern:

test_scenario_description() {
    // Given: Set up the initial context and test data
    [setup code]

    // When: Execute the action under test
    [action code]

    // Then: Verify the expected outcome
    [assertion code]
}

4. Test Independence (Critical)

• •Tests must NOT depend on execution order
• •Tests must NOT share mutable state between test cases
• •Each test must create its own test data locally
• •Each test must be fully self-contained and runnable in isolation
• •Avoid class-level variables that are mutated across tests

Why: Shared state creates coupling between tests, making them fragile and hard to debug.

5. Test Isolation

• •Tests should be repeatable (same result every time)
• •Tests should be deterministic (no randomness unless explicitly tested)
• •Tests should not depend on external state (databases, files, network)
• •Use test doubles (mocks, stubs, fakes) for external dependencies

6. One Logical Assertion per Test

Each test should verify one logical concept, though it may have multiple assertion statements:

// Good: All assertions verify the same concept
test_user_creation_sets_all_required_fields() {
    // Given-When-Then...

    // Then: All fields are set correctly
    assert user.id is not null
    assert user.email equals "user@example.com"
    assert user.status equals ACTIVE
}

// Bad: Testing multiple unrelated concepts
test_user_operations() {
    // Tests creation, update, deletion all in one
}

Workflow

Follow this process when writing tests:

Step 1: Identify What to Test

1. •Read the code to understand its behavior and contract
2. •Identify public interfaces (these define the contract to test)
3. •Identify critical paths (happy path + failure paths)
4. •Identify edge cases (null, empty, boundary values, invalid inputs)

Step 2: Plan Test Scenarios

For each operation, identify scenarios using Given-When-Then:

• •Happy path: Given valid input, When operation executes, Then expected result
• •Edge cases: Given boundary values, When operation executes, Then handled correctly
• •Error cases: Given invalid input, When operation executes, Then appropriate error
• •State transitions: Given current state, When event occurs, Then new state reached

Step 3: Write Self-Contained Tests

Each test must:

• •Create its own test data locally (no shared class variables)
• •Set up required context and dependencies
• •Execute the operation under test
• •Verify the expected outcome
• •Be independent of other tests

Step 4: Verify Coverage

• •Run coverage analysis
• •Ensure critical paths are covered
• •Add tests for uncovered branches
• •Review for missed edge cases

Step 5: Review Test Quality

Ask yourself:

• •Are tests readable and express clear intent?
• •Are tests fully self-contained?
• •Do they test behavior, not implementation details?
• •Are they fast enough?
• •Will they help future developers understand the code?

Decision Trees

What Type of Test Should I Write?

Is it domain logic with no external dependencies?
├─ YES → Unit test (no test doubles)
│         Use real domain objects
└─ NO → Does it interact with external systems?
    ├─ YES → Integration test or Unit test with test doubles
    │         Mock external dependencies
    └─ NO → Does it coordinate between components?
        ├─ YES → Integration test
        │         Test real collaboration
        └─ NO → Unit test (minimal or no test doubles)

Should I Mock This Dependency?

Is it an external system (database, API, filesystem, network)?
├─ YES → Use test double (mock/stub/fake)
└─ NO → Is it infrastructure layer?
    ├─ YES → Use test double
    └─ NO → Is it domain logic?
        ├─ YES → Use real object
        └─ NO → Is it slow or non-deterministic?
            ├─ YES → Use test double
            └─ NO → Use real object

How Many Test Cases Do I Need?

For each public operation:
1. Happy path (at least 1 test)
2. For each input parameter:
   - Null case (if nullable)
   - Empty case (if applicable: collections, strings)
   - Invalid case (if validation exists)
   - Boundary values (min, max, zero, negative)
3. For each error condition:
   - Test the condition that triggers it
   - Verify expected error behavior
4. For each branch in logic:
   - Test true path
   - Test false path

Test Types

Unit Tests

Purpose: Test a single component in isolation

Characteristics:

• •Fast (< 100ms per test)
• •No external dependencies
• •Test doubles for collaborators
• •Test single responsibility

When to use:

• •Testing domain entities and value objects
• •Testing application use cases with mocked ports
• •Testing algorithms and business rules

Integration Tests

Purpose: Test interaction between components

Characteristics:

• •Slower (< 1 second per test)
• •May use real infrastructure (in-memory databases, test containers)
• •Test port/adapter integration
• •Verify component collaboration

When to use:

• •Testing adapters against real implementations
• •Testing database queries
• •Testing API endpoints
• •Testing message handling

Contract Tests

Purpose: Verify interface contracts are respected

Characteristics:

• •Test port interfaces are correctly implemented by adapters
• •Can use consumer-driven contract testing
• •Ensure compatibility between components

When to use:

• •Testing adapter implementations match port contracts
• •Testing external API integrations
• •Preventing breaking changes

Patterns and Best Practices

Self-Contained Tests (Critical)

Always create test data locally within each test:

// Good: Self-contained test
test_user_creation() {
    // Given: Create test data locally
    var email = "user@example.com"
    var name = "John Doe"

    // When
    var user = createUser(email, name)

    // Then
    assert user.email equals email
}

// Bad: Shared state between tests
class UserTests {
    var sharedEmail = "user@example.com"  // ❌ Don't do this
    var sharedUser = null                  // ❌ Don't do this

    test_creation() {
        sharedUser = createUser(sharedEmail)  // ❌ Mutates shared state
    }

    test_retrieval() {
        assert sharedUser is not null  // ❌ Depends on previous test
    }
}

Test Data Creation

Option 1: Inline Creation

test_scenario() {
    // Given: Create directly in test
    var product = Product(id: "123", name: "Widget", price: 9.99)

    // When-Then...
}

Option 2: Factory Functions/Builders

test_scenario() {
    // Given: Use builder/factory
    var product = buildProduct(id: "123", name: "Widget")

    // When-Then...
}

Critical: Each test must create its own data, even if using builders.

Testing Exceptions/Errors

Tests should verify both that errors occur and their details:

test_invalid_input_throws_error() {
    // Given: Invalid data
    var invalidEmail = "not-an-email"

    // When-Then: Verify error is thrown
    assertThrows(ValidationError) {
        createUser(invalidEmail)
    }
}

test_error_contains_helpful_message() {
    // Given-When-Then
    try {
        createUser("invalid")
        fail("Expected exception")
    } catch (ValidationError e) {
        assert e.message contains "email"
        assert e.message contains "invalid format"
    }
}

Parameterized Tests

When testing multiple similar cases, use parameterized tests:

test_validation_rejects_blank_inputs(input: String) {
    // Test with multiple blank values: "", "  ", "\t", "\n"

    // When-Then
    assertThrows(ValidationError) {
        validate(input)
    }
}

Anti-Patterns to Avoid

❌ Shared Mutable State

// Bad: State shared across tests
class ServiceTests {
    var service = new Service()  // ❌ Shared
    var testData = []            // ❌ Shared

    test_one() {
        testData.add("item")  // ❌ Mutates shared state
    }
}

// Good: Each test creates its own state
class ServiceTests {
    test_one() {
        var service = new Service()  // ✅ Local
        var testData = ["item"]       // ✅ Local
    }
}

❌ Testing Implementation Details

// Bad: Tests internal structure
test_uses_correct_algorithm() {
    service.calculate(input)
    verify_internal_method_was_called()  // ❌ Tests "how"
}

// Good: Tests behavior
test_calculation_returns_correct_result() {
    // Given-When
    var result = service.calculate(input)

    // Then
    assert result equals expected  // ✅ Tests "what"
}

❌ Test Interdependence

// Bad: Tests depend on execution order
test_step1_creation() {
    sharedUser = create()  // ❌ Sets shared state
}

test_step2_modification() {
    modify(sharedUser)  // ❌ Depends on step1
}

// Good: Independent tests
test_creation() {
    var user = create()  // ✅ Local setup
    assert user.isValid()
}

test_modification() {
    var user = create()  // ✅ Local setup
    modify(user)
    assert user.wasModified()
}

❌ Slow Tests

// Bad: Uses sleep/delays
test_async_completion() {
    startAsync()
    sleep(5000)  // ❌ Slow and brittle
    assert isComplete()
}

// Good: Uses proper synchronization
test_async_completion() {
    var latch = new CountDownLatch(1)
    startAsync(onComplete: -> latch.countDown())
    assert latch.await(1, SECONDS)  // ✅ Fast and reliable
}

Coverage Guidelines

Minimum Coverage Targets

What to Measure

• •Line coverage: Every line of code executed
• •Branch coverage: Every branch (if/else, switch) taken
• •Path coverage: Different execution paths tested

When 100% Coverage is Not the Goal

Some code doesn't require 100% coverage:

• •Trivial getters/setters (if no logic)
• •Framework-generated code
• •Configuration classes
• •Pure logging/debugging code

However: Complex getters with logic, validation, or transformations do need tests.

Testing Hexagonal Architecture

Testing Domain Layer

• •No test doubles: Domain should have no external dependencies
• •Test business logic: Focus on rules, invariants, and domain behavior
• •Test value objects: Equality, validation, immutability
• •Test entities: State transitions, business rules
• •Use real objects: All domain objects are real instances

Testing Application Layer (Use Cases)

• •Mock ports: External dependencies through port interfaces
• •Test orchestration: Verify correct collaboration between components
• •Test transaction boundaries: If applicable
• •Self-contained setup: Each test creates its own mocks locally

Testing Adapters (Infrastructure)

• •Integration tests: Use real or in-memory implementations when possible
• •Test contracts: Verify adapter matches port interface
• •Test error handling: Network failures, timeouts, retries
• •Test data mapping: Correct transformation between external and domain models

Notes

• •Tests are documentation: They show how to use your code
• •Tests are specifications: They define expected behavior
• •Tests enable refactoring: Change implementation with confidence
• •Self-contained tests are maintainable: No hidden dependencies
• •Fast feedback is crucial: Keep tests fast for rapid iteration
• •Test behavior, not implementation: Focus on "what", not "how"