Every backend that touches a date of birth ends up reinventing the same arithmetic. I've watched it happen in three codebases this year alone: a fintech KYC service, a healthcare intake portal, and a small HR tool for a startup. The bug shape is almost always identical — somebody computes age by subtracting birth year from current year, the QA suite passes because it only tests inputs born in 1970 and 2000, and then someone born on February 29 walks in and gets flagged as underage. Or worse, a leap-year-spanning eligibility window quietly lets the wrong person through.
This article is a checklist for engineers who inherit one of these systems and need to harden it before the next incident. It assumes you've already decided you need to compute a duration between two dates correctly, and your job is to figure out how to test that computation so you stop shipping regressions.
The Two Questions You Actually Need to Answer
Before writing a single assertion, ask the business which of these they care about. The implementation is different for each, and conflating them is the source of most date-math bugs.
How many full years has the person been alive? This is the classic "age in years" question — what a doctor's office, a voting registration form, or an age-gated content filter wants. The answer changes only on the birthday.
