# Testing

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/`)

Every file in [`data/`](https://goudarzjafari.com/persian-calendar/data/) is generated by the astronomical engine in [`tools/calendar-data`](https://goudarzjafari.com/persian-calendar/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`](https://goudarzjafari.com/persian-calendar/files/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`](https://goudarzjafari.com/persian-calendar/files/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`](https://goudarzjafari.com/persian-calendar/files/data/leap-years.txt)                               | 442                    | One Persian year per line                                                   | Quick list of all leap years in `1178–3000 AP`                                                                                                  |
| [`data/corrections.txt`](https://goudarzjafari.com/persian-calendar/files/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`](https://goudarzjafari.com/persian-calendar/files/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`](https://goudarzjafari.com/persian-calendar/files/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

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/`](https://goudarzjafari.com/persian-calendar/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

The test harness in [`tools/icu-cross-check`](https://goudarzjafari.com/persian-calendar/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`)

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`](https://goudarzjafari.com/persian-calendar/implementations/javascript/#file-persian-calendar-test-js) does:

```js
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

[`tools/library-evaluation`](https://goudarzjafari.com/persian-calendar/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

```sh
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`](https://github.com/Goudarz/PersianCalendar/blob/main/.github/workflows/test.yml)).

---

Page: https://goudarzjafari.com/persian-calendar/testing/
License: text CC BY 4.0, code MIT, data CC0 1.0. Version 1.0.0 of https://github.com/Goudarz/PersianCalendar
