Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

5.7 KB
Raw Blame
from datetime import date
from decimal import Decimal

import pytest

from app.services.loan_schedule import (
    add_months,
    build_schedule,
    monthly_rate,
    summarize,
)


def test_monthly_rate_follows_the_rate_period():
    assert monthly_rate(Decimal("1.5"), "monthly") == Decimal("0.015")
    assert monthly_rate(Decimal("12"), "yearly_nominal") == Decimal("0.01")
    # 12.6825% a year compounded monthly is 1% a month.
    assert monthly_rate(Decimal("12.682503"), "yearly_effective").quantize(Decimal("0.000001")) == Decimal(
        "0.010000"
    )


def test_add_months_clamps_to_the_end_of_a_short_month():
    assert add_months(date(2026, 1, 31), 1) == date(2026, 2, 28)
    assert add_months(date(2026, 1, 31), 2) == date(2026, 3, 31)
    assert add_months(date(2026, 11, 15), 3) == date(2027, 2, 15)


def test_price_schedule_has_a_constant_payment_and_pays_off_exactly():
    schedule = build_schedule(
        principal=Decimal("10000"),
        rate_percent=Decimal("1"),
        rate_period="monthly",
        term_months=12,
        first_payment_date=date(2026, 1, 10),
        method="price",
    )

    assert len(schedule) == 12
    # 10,000 at 1% a month over 12 months: 888.49 a month.
    assert {row.payment for row in schedule[:-1]} == {Decimal("888.49")}
    assert schedule[0].interest == Decimal("100.00")
    assert schedule[0].principal == Decimal("788.49")
    assert schedule[-1].balance == Decimal("0.00")
    assert sum(row.principal for row in schedule) == Decimal("10000.00")
    assert schedule[-1].due_date == date(2026, 12, 10)


def test_sac_schedule_has_constant_principal_and_falling_payments():
    schedule = build_schedule(
        principal=Decimal("12000"),
        rate_percent=Decimal("1"),
        rate_period="monthly",
        term_months=12,
        first_payment_date=date(2026, 1, 10),
        method="sac",
    )

    assert {row.principal for row in schedule} == {Decimal("1000.00")}
    assert schedule[0].payment == Decimal("1120.00")
    assert schedule[1].payment == Decimal("1110.00")
    assert schedule[-1].payment == Decimal("1010.00")
    assert schedule[-1].balance == Decimal("0.00")


def test_a_zero_rate_loan_splits_the_principal_evenly():
    schedule = build_schedule(
        principal=Decimal("1000"),
        rate_percent=Decimal("0"),
        rate_period="monthly",
        term_months=3,
        first_payment_date=date(2026, 1, 1),
        method="price",
    )

    assert [row.payment for row in schedule] == [Decimal("333.33"), Decimal("333.33"), Decimal("333.34")]
    assert schedule[-1].balance == Decimal("0.00")


def _price_12():
    return build_schedule(
        principal=Decimal("10000"),
        rate_percent=Decimal("1"),
        rate_period="monthly",
        term_months=12,
        first_payment_date=date(2026, 1, 10),
        method="price",
    )


def test_summary_compares_the_contract_with_the_real_balance():
    schedule = _price_12()

    # 6,000 owed against about 7,623 scheduled: more than a full payment ahead.
    summary = summarize(schedule, actual_balance=Decimal("6000"), today=date(2026, 4, 1), method="price", rate=Decimal("0.01"))

    # Three installments were due before April 1st.
    assert summary.payments_due == 3
    assert summary.remaining_payments == 9
    assert summary.next_payment == schedule[3]
    assert summary.scheduled_balance == schedule[2].balance
    # Owing less than the contract says means the loan is ahead of schedule.
    assert summary.ahead_by == schedule[2].balance - Decimal("6000")
    assert summary.total_interest == sum(row.interest for row in schedule)
    assert summary.payoff_date == date(2026, 12, 10)
    assert summary.projected_payoff_date is not None
    assert summary.projected_payoff_date == date(2026, 11, 10)


def test_summary_of_a_paid_off_loan():
    summary = summarize(_price_12(), actual_balance=Decimal("0"), today=date(2026, 6, 1), method="price", rate=Decimal("0.01"))

    assert summary.projected_payoff_date is None
    assert summary.paid_off is True


@pytest.mark.parametrize("method", ["price", "sac"])
def test_projection_from_the_real_balance_keeps_the_contract_payment(method: str):
    schedule = build_schedule(
        principal=Decimal("12000"),
        rate_percent=Decimal("1"),
        rate_period="monthly",
        term_months=12,
        first_payment_date=date(2026, 1, 10),
        method=method,
    )

    # Nothing paid yet and the first installment is next: the projection is the contract.
    summary = summarize(schedule, actual_balance=Decimal("12000"), today=date(2026, 1, 1), method=method, rate=Decimal("0.01"))

    assert summary.projected_payoff_date == summary.payoff_date


def test_a_balance_above_the_contract_is_behind_schedule():
    schedule = _price_12()

    summary = summarize(schedule, actual_balance=Decimal("9500"), today=date(2026, 4, 1), method="price", rate=Decimal("0.01"))

    assert summary.ahead_by < 0


def test_sac_projection_ignores_the_cents_lost_to_rounding():
    # 400,000 over 360 months amortizes 1,111.11 a month, 0.40 short over the
    # contract; one payment behind must project one month late, not two.
    schedule = build_schedule(
        principal=Decimal("400000"),
        rate_percent=Decimal("11.5"),
        rate_period="yearly_effective",
        term_months=360,
        first_payment_date=date(2025, 11, 10),
        method="sac",
    )
    behind_one_payment = schedule[11].balance + schedule[11].principal

    summary = summarize(
        schedule,
        actual_balance=behind_one_payment,
        today=date(2026, 10, 22),
        method="sac",
        rate=monthly_rate(Decimal("11.5"), "yearly_effective"),
    )

    assert summary.payoff_date == date(2055, 10, 10)
    assert summary.projected_payoff_date == date(2055, 11, 10)