Skip to main content
Contents

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.

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.

If you are testing a Persian calendar implementation, here is the complete checklist of tests it should pass:

  1. Every row of years.csv (1178–3000 AP): Verify is_leap_year(year) == is_leap and to_gregorian(year, 1, 1) == nowruz_gregorian.
  2. 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), plus day_of_week.
  3. Exhaustive day-by-day round-trip: For every single day n in your supported range, verify that to_jdn(from_jdn(n)) == n, that from_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.)
  4. Date validation: Confirm that 1403/12/30 is valid (leap year), while 1404/12/30 (non-leap year), 1404/07/31 (30-day month), 1404/13/01, 1404/00/01, and 1404/01/00 are rejected as invalid.
  5. Time-zone boundary: Confirm that the UTC instant 2025-03-20T21:00:00Z converts to 1 Farvardin 1404 in Asia/Tehran (00:30 local time), but 30 Esfand 1403 in UTC.
  6. Month & year arithmetic (if your API supports it): Confirm that 31 Shahrivar 1404 + 1 month = 30 Mehr 1404 and 30 Esfand 1403 + 1 year = 29 Esfand 1404.
  7. Negative years & negative intermediate values: Round-trip every day of years −1000 … 1177 as 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) == 1582713
    • to_jdn(0, 1, 1) == 1947955
    • to_jdn(4000, 1, 1) == 3408925
    • from_jdn(0) == (-5334, 9, 3)
    • is_leap_year(-3) == true
  8. Non-integer rejection (in dynamically typed languages like JS, Python, PHP, Ruby): Confirm that fractional inputs like is_valid(1404, 1.5, 1) or from_jdn(2460756.5) are rejected rather than silently producing fractional dates.
  9. Input range limits & invalid Gregorian dates: Confirm that the exact minimum and maximum supported days (−100000/01/01 and 100000/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.)
  10. Full-range year-by-year sweep (−100000 … 100000): Loop over all 200,001 years in the accepted range, verifying that 1 Farvardin of year y immediately follows the last day of y − 1 and 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 below 2⁵³, so even JavaScript Number computes 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 .NET

The 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_calendar 2.4 and calendrical_calculations),
  • ICU4J 76.1–79.1 (tested from Java, Kotlin, and Scala),
  • ICU4C 76.1–79.1 (tested via Node.js Intl, PHP intl, and via direct C FFI from Python, Ruby, Go, C#, Dart, and C),
  • Temporal (temporal_rs in 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:

JavaScript
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 library

tools/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 repository
Shell
cd 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).