TDD and Refactoring: Characterization Tests for Legacy Code

// Legacy class — do not touch until characterized
public class PricingEngine {
    public OrderSummary calculate(Order order, Customer customer, List<Promotion> activePromotions) {
        // 400 lines of imperative logic, conditionals, magic numbers
        // Several known bugs that "customers have worked around"
        // No tests
    }
}

class PricingEngineCharacterizationTest {

    private PricingEngine engine = new PricingEngine();

    @Test
    void standardOrderWithNoPromotions() {
        var order = OrderFixture.standardOrder(); // items totalling $100.00
        var customer = CustomerFixture.regularCustomer(); // no special pricing
        var promotions = List.of();

        var result = engine.calculate(order, customer, promotions);

        // CHARACTERIZATION: Record what the code actually produces.
        // Do not change these values without understanding why they changed.
        assertThat(result.subtotal()).isEqualByComparingTo("100.00");
        assertThat(result.taxAmount()).isEqualByComparingTo("8.75"); // 8.75% tax — why? unknown
        assertThat(result.discount()).isEqualByComparingTo("0.00");
        assertThat(result.total()).isEqualByComparingTo("108.75");
    }

    @Test
    void premiumCustomerReceivesTenPercentDiscount() {
        var order = OrderFixture.standardOrder();
        var customer = CustomerFixture.premiumCustomer();
        var promotions = List.of();

        var result = engine.calculate(order, customer, promotions);

        assertThat(result.subtotal()).isEqualByComparingTo("100.00");
        assertThat(result.discount()).isEqualByComparingTo("10.00");
        assertThat(result.taxAmount()).isEqualByComparingTo("8.09"); // tax on discounted amount?
        assertThat(result.total()).isEqualByComparingTo("98.09");
    }

    @Test
    void summerSalePromotionAppliesBeforeCustomerDiscount() {
        var order = OrderFixture.standardOrder();
        var customer = CustomerFixture.premiumCustomer();
        var promotions = List.of(PromotionFixture.summerSale()); // 15% off

        var result = engine.calculate(order, customer, promotions);

        // CHARACTERIZATION: At the time of writing, the two discounts DO NOT stack.
        // The higher discount (15%) wins. Premium discount (10%) is ignored.
        // Whether this is correct behavior is unknown — characterizing as-is.
        assertThat(result.discount()).isEqualByComparingTo("15.00");
        assertThat(result.total()).isEqualByComparingTo("91.94");
    }
}

class ReportGeneratorCharacterizationTest {

    private ReportGenerator generator = new ReportGenerator();

    @Test
    void monthlyOrderReportMatchesGoldenMaster() throws Exception {
        var orders = OrderFixture.mayOrders(); // fixed dataset

        var report = generator.generateMonthlyReport(orders, YearMonth.of(2024, 5));

        // Write golden master on first run, compare on subsequent runs
        var goldenMasterPath = Path.of("src/test/resources/golden-masters/monthly-report-may-2024.txt");

        if (!Files.exists(goldenMasterPath)) {
            Files.writeString(goldenMasterPath, report);
            fail("Golden master created. Re-run the test to verify.");
        }

        var expected = Files.readString(goldenMasterPath);
        assertThat(report).isEqualTo(expected);
    }
}

// build.gradle
testImplementation 'com.approvaltests:approvaltests:22.3.3'

import org.approvaltests.Approvals;
import org.approvaltests.combinations.CombinationApprovals;

class PricingEngineApprovalTest {

    private PricingEngine engine = new PricingEngine();

    @Test
    void approvePricingForAllCustomerTypes() {
        var order = OrderFixture.standardOrder();
        var customers = new Customer[]{
            CustomerFixture.regularCustomer(),
            CustomerFixture.premiumCustomer(),
            CustomerFixture.vipCustomer()
        };
        var promotionSets = new List[]{
            List.of(),
            List.of(PromotionFixture.summerSale()),
            List.of(PromotionFixture.clearance(), PromotionFixture.loyaltyBonus())
        };

        CombinationApprovals.verifyAllCombinations(
            (customer, promotions) -> engine.calculate(order, customer, promotions).toString(),
            customers,
            promotionSets
        );
    }

    @Test
    void approveMonthlyReport() {
        var report = new ReportGenerator().generateMonthlyReport(
            OrderFixture.mayOrders(), YearMonth.of(2024, 5)
        );
        Approvals.verify(report);
    }
}

// In test setup or ApprovalTests.properties
@Before
public void configureApprovals() {
    if (System.getenv("CI") != null) {
        Approvals.setReporter(new DiffReporter());
    }
}

// Before: 400-line method
public OrderSummary calculate(Order order, Customer customer, List<Promotion> promotions) {
    // ... 400 lines
}

// After: Same behavior, decomposed
public OrderSummary calculate(Order order, Customer customer, List<Promotion> promotions) {
    var subtotal = calculateSubtotal(order);
    var promotionDiscount = applyPromotions(subtotal, promotions);
    var customerDiscount = applyCustomerDiscount(subtotal - promotionDiscount, customer);
    var taxableAmount = subtotal - Math.max(promotionDiscount, customerDiscount);
    var tax = calculateTax(taxableAmount, customer.billingAddress());
    return new OrderSummary(subtotal, Math.max(promotionDiscount, customerDiscount), tax);
}

@Test
void promotionDiscountIsHigherOfPromotionOrCustomerDiscount() {
    // This was implicit in the characterization tests.
    // Now it is explicit and documented.
    var subtotal = new BigDecimal("100.00");
    var promotions = List.of(PromotionFixture.summerSale()); // 15%
    var customer = CustomerFixture.premiumCustomer(); // 10%

    var discount = engine.applyBestDiscount(subtotal, promotions, customer);

    assertThat(discount).isEqualByComparingTo("15.00");
}

// Was characterized as: tax applied after promotion discount
// Should be: tax applied after ALL discounts (customer + promotion)
// Fix the test first, then fix the implementation
@Test
void taxIsCalculatedOnFinalDiscountedAmount() {
    var order = OrderFixture.orderTotal("100.00");
    var customer = CustomerFixture.premiumCustomer(); // 10% discount
    var promotions = List.of(PromotionFixture.summerSale()); // 15% wins

    var result = engine.calculate(order, customer, promotions);

    // Correct: tax on $85.00 (after 15% discount), not $90.00 (after 10%)
    assertThat(result.taxableAmount()).isEqualByComparingTo("85.00");
}

@Test
void orderWithZeroPriceItemsProducesNegativeTax() {
    // CHARACTERIZATION: This appears to be a bug — negative tax should not be possible.
    // Do not fix during this refactoring pass. File JIRA-4521.
    // Current behavior is documented here so refactoring does not accidentally change it.
    var result = engine.calculate(order, customer, promotions);
    assertThat(result.taxAmount()).isEqualByComparingTo("-2.25"); // negative!
}