Chapter 9 of 10
Testing
5 min readUpdated
Whether you write your own calendar converter or adopt a third-party library, you should never take its accuracy on faith—test it against independent ground-truth data. This repository includes everything you need to run those tests in seconds.
The reference data files (data/)
Link to section: The reference data files (data/)Every file in data/ is generated by the astronomical engine in tools/calendar-data (written in Rust)—not by the arithmetic algorithm under test.
Before writing any file, the tool verifies its astronomical output against all 293 years of the official University of Tehran Calendar Center table and produces identical results.
| File | Rows | Columns / Format | What to use it for |
|---|---|---|---|
data/years.csv |
1,823 (1178–3000 AP) |
year, is_leap, days_in_year, nowruz_gregorian, nowruz_jdn, nowruz_weekday |
Testing leap-year detection and exact Nowruz start dates |
data/test-vectors.csv |
8,510 | jy, jm, jd, gy, gm, gd, jdn, weekday |
First and last day of every month in 1300–1500 AP, first and last day of every year in 1178–3000 AP, plus 29 & 30 Esfand of every leap year |
data/leap-years.txt |
442 | One Persian year per line | Quick list of all leap years in 1178–3000 AP |
data/corrections.txt |
78 | One Persian year per line | The 78 correction years for the 33-year rule, derived directly from astronomy |
data/official/kabise-1206-1498.txt |
293 | Persian year (with */** leap markers) and Gregorian Nowruz date |
Plain-text CC0 transcription of the official Calendar Center table (prepared by R. Pournader) |
data/locale-names.json |
11 locales | Months, weekdays, and era names | Verifying localized formatting against Unicode CLDR |
Conventions used across all files: Months are 1..12; weekday is 0 = Saturday … 6 = Friday; jdn is the standard Julian Day Number; Gregorian dates use the proleptic Gregorian calendar; CSV files are UTF-8 with \n (LF) line endings and a header row.
The 10-point test suite
Link to section: The 10-point test suiteIf you are testing a Persian calendar implementation, here is the complete checklist of tests it should pass:
- Every row of
years.csv(1178–3000 AP): Verifyis_leap_year(year) == is_leapandto_gregorian(year, 1, 1) == nowruz_gregorian. - Every row of
test-vectors.csv(8,510 boundary dates): Verify both directions—Persian → Gregorian (to_gregorian,to_jdn) and Gregorian → Persian (from_gregorian,from_jdn), plusday_of_week. - Exhaustive day-by-day round-trip: For every single day
nin your supported range, verify thatto_jdn(from_jdn(n)) == n, thatfrom_jdn(n)returns a valid(y, m, d), and that consecutive JDNs produce consecutive calendar dates. (Sample tests often miss off-by-one bugs at month and year transitions; a full loop catches them all.) - Date validation: Confirm that
1403/12/30is valid (leap year), while1404/12/30(non-leap year),1404/07/31(30-day month),1404/13/01,1404/00/01, and1404/01/00are rejected as invalid. - Time-zone boundary: Confirm that the UTC instant
2025-03-20T21:00:00Zconverts to1 Farvardin 1404inAsia/Tehran(00:30local time), but30 Esfand 1403inUTC. - Month & year arithmetic (if your API supports it): Confirm that
31 Shahrivar 1404 + 1 month = 30 Mehr 1404and30 Esfand 1403 + 1 year = 29 Esfand 1404. - Negative years & negative intermediate values: Round-trip every day of years
−1000 … 1177as well. For years≤ 0, the internal math produces negative numbers—which immediately exposes any bug where/or%truncates toward zero instead of using floor division! All 14 implementations in this repo check these exact anchor points:to_jdn(-1000, 1, 1) == 1582713to_jdn(0, 1, 1) == 1947955to_jdn(4000, 1, 1) == 3408925from_jdn(0) == (-5334, 9, 3)is_leap_year(-3) == true
- Non-integer rejection (in dynamically typed languages like JS, Python, PHP, Ruby): Confirm that fractional inputs like
is_valid(1404, 1.5, 1)orfrom_jdn(2460756.5)are rejected rather than silently producing fractional dates. - Input range limits & invalid Gregorian dates: Confirm that the exact minimum and maximum supported days (
−100000/01/01and100000/12/29) convert cleanly, while 1 day outside that range, huge numbers (2⁵³,INT64_MAX,INT64_MIN), and impossible Gregorian dates (2025-02-29,2025-02-30,1900-02-29) are rejected immediately without integer overflow or hanging loops. (In C, also verify that output pointers are left untouched on error, and run under-fsanitize=undefined.) - Full-range year-by-year sweep (
−100000 … 100000): Loop over all 200,001 years in the accepted range, verifying that1 Farvardinof yearyimmediately follows the last day ofy − 1and that the first and last day of every year round-trip. Across−100000 … 100000, two exact checksums lock down every single leap year:- Total leap years: 48,485
- Sum of
nowruz_jdn(y)across all 200,001 years: 389,592,978,180 (which fits comfortably below2⁵³, so even JavaScriptNumbercomputes it without losing a single bit of precision). ICU 77.1+, ICU4X, and Temporal produce the exact same two checksums.
Every implementation in implementations/ runs tests 1–4, 7, 9, and 10—and runs Test 1 across all 665,837 individual days of 1178–3000 AP in both directions. When you copy an implementation into your project, copy its test file too!
Cross-checking against ICU, ICU4X, Temporal, and .NET
Link to section: Cross-checking against ICU, ICU4X, Temporal, and .NETThe test harness in tools/icu-cross-check compares all 665,837 days of 1178–3000 AP across:
- Our astronomical ground truth (
data/years.csv), - All 14 language implementations in this repository,
- ICU4X (
icu_calendar2.4 andcalendrical_calculations), - ICU4J 76.1–79.1 (tested from Java, Kotlin, and Scala),
- ICU4C 76.1–79.1 (tested via Node.js
Intl, PHPintl, and via direct C FFI from Python, Ruby, Go, C#, Dart, and C), - Temporal (
temporal_rsin Node.js 26), and - .NET's
PersianCalendar.
(Since PostgreSQL has no built-in Persian calendar, our SQL functions are cross-checked against ICU and Temporal.)
The result: ICU 77.1+, ICU4X, Temporal, and all 14 of our implementations agree on every single day. ICU 76.1 matches the plain 33-year rule (diverging starting in 1503 AP), and .NET's PersianCalendar differs on 2,196 days across 12 years starting in 1535 AP.
Quick cross-check against your own runtime (Intl)
Link to section: Quick cross-check against your own runtime (Intl)If you are running on a modern platform with ICU 77.1+ (such as Node.js 24+ or a current browser), you can also cross-check your code directly against Intl.DateTimeFormat, just like implementations/javascript/persian-calendar.test.js does:
const fmt = new Intl.DateTimeFormat('en-u-ca-persian-nu-latn', { timeZone: 'UTC', year: 'numeric', month: 'numeric', day: 'numeric' })How to evaluate a third-party library
Link to section: How to evaluate a third-party librarytools/library-evaluation contains automated test runners for JavaScript, Python, Java/Kotlin, Rust, Dart, PHP, Go, .NET, and Ruby libraries.
To evaluate a new library, write a small script that outputs its computed Gregorian Nowruz date for each Persian year from 1100 to 3300 into results/<name>.txt (<year> <YYYY-MM-DD> per line), then run cargo run --release -- score-libraries inside tools/calendar-data.
Running all tests in this repository
Link to section: Running all tests in this repositorycd tools/calendar-data && cargo run --release -- --check # Verify data/ files match astronomical ground truth
python -m unittest discover -s implementations/python # Python
node --test implementations/javascript/ # JavaScript
cd implementations/typescript && node --test # TypeScript (Node 23.6+)
cd implementations/java && javac -d out *.java && java -cp out PersianCalendarTest
cd implementations/kotlin && kotlinc *.kt -include-runtime -d t.jar && java -jar t.jar
cd implementations/scala && scala run . --main-class persiancalendar.PersianCalendarTest -- ../../data
cd implementations/csharp/tests && dotnet run
cd implementations/go && go test ./...
cd implementations/rust && cargo test --release
cd implementations/php && php test.php
cd implementations/dart && dart pub get && dart test
cd implementations/c && cc -std=c99 -O2 persian_calendar.c test.c -o t && ./t
cd implementations/ruby && ruby test_persian_calendar.rb
cd implementations/sql && npm install && npm test # PostgreSQL (runs in-process via PGlite)Or simply run bash tools/run-all-tests.sh to execute every test suite installed on your machine. The exact same commands run automatically on every commit in GitHub Actions (.github/workflows/test.yml).