فصل ۹ از ۱۰
تست و بررسی درستی کد
۶ دقیقه مطالعهبهروزرسانی
چه الگوریتم تبدیل تاریخ رو خودتون بنویسید و چه از یک کتابخونهٔ آماده استفاده کنید، حتما باید اون رو با دادههای مرجع مستقل تست کنید. توی این مخزن تمام دادههای لازم برای این کار آماده شده است.
فایلهای دادهٔ مرجع (data/)
پیوند به بخش فایلهای دادهٔ مرجع (data/)تمام فایلهای این پوشه با موتور محاسبهٔ نجومی tools/calendar-data (به زبان Rust) تولید شدن، نه با الگوریتمی که قراره تست بشه!
این ابزار قبل از ساختن فایلها، خروجی نجومی خودش رو با تمام سالهای جدول رسمی مرکز تقویم دانشگاه تهران چک میکنه و خروجی نهاییش هم یکسانه.
| فایل | تعداد سطرها | ستونها و محتوا | کاربرد |
|---|---|---|---|
data/years.csv |
۱٬۸۲۳ (سال ۱۱۷۸ تا ۳۰۰۰) | year, is_leap, days_in_year, nowruz_gregorian, nowruz_jdn, nowruz_weekday |
تست کبیسه بودن سالها و تاریخ دقیق نوروز |
data/test-vectors.csv |
۸٬۵۱۰ | jy, jm, jd, gy, gm, gd, jdn, weekday |
روز اول و آخر هر ماه در بازهٔ ۱۳۰۰ تا ۱۵۰۰، روز اول و آخر هر سال در ۱۱۷۸ تا ۳۰۰۰، و ۲۹ و ۳۰ اسفند تمام سالهای کبیسه |
data/leap-years.txt |
۴۴۲ | یک سال کبیسه در هر خط | لیست سریع سالهای کبیسه در بازهٔ ۱۱۷۸ تا ۳۰۰۰ |
data/corrections.txt |
۷۸ | یک سال استثنا در هر خط | جدول ۷۸ سال اصلاح فرمول ۳۳ ساله (استخراجشده به شکل مستقل) |
data/official/kabise-1206-1498.txt |
۲۹۳ | سال (همراه با علامت * یا **) و تاریخ نوروز |
نسخهٔ متنی جدول رسمی مرکز تقویم دانشگاه تهران (با مجوز CC0، استخراجشده توسط روزبه پورنادر) |
data/locale-names.json |
۱۱ زبان | نام ماهها، روزهای هفته و پسوند تقویم | نامهای استاندارد استخراجشده از CLDR 48 |
قراردادهای فایلها: ماهها از ۱ تا ۱۲؛ روز هفته (weekday) از ۰ = شنبه تا ۶ = جمعه؛ jdn = عدد روز ژولینی؛ تاریخهای میلادی بر اساس تقویم میلادی پیشگستر (Proleptic Gregorian)؛ فرمت UTF-8 با پایان خط LF.
ده تستی که هر پیادهسازی باید پاس کنه
پیوند به بخش ده تستی که هر پیادهسازی باید پاس کنه- تمام سطرهای
years.csv: بررسی اینکه خروجیis_leap_year(year)و تبدیلto_gregorian(year, 1, 1)دقیقا با ستونهایis_leapوnowruz_gregorianیکی باشه. - تمام سطرهای
test-vectors.csvدر هر دو جهت: تبدیل شمسی به میلادی و میلادی به شمسی. - تبدیل دوطرفهٔ (Round-trip) تکتک روزها در کل بازهٔ پشتیبانی: چک کردن اینکه برای هر روز
n، رابطهٔto_jdn(from_jdn(n)) == nبرقرار باشه، تاریخ خروجی معتبر باشه و دو روز متوالی دقیقا به دو تاریخ متوالی تبدیل بشن. این تست باگهای یکروزه در مرز ماهها و سالها رو (که ممکنه از چشم تستهای نمونهای دور بمونن) شکار میکنه. - اعتبارسنجی تاریخها: تاریخ
1403/12/30معتبره؛ اما1404/12/30،1404/07/31،1404/13/01،1404/00/01و1404/01/00همگی باید نامعتبر تشخیص داده بشن. - تایمزون: لحظهٔ زمانی
2025-03-20T21:00:00Zدر تایمزونAsia/Tehranباید بشه ۱ فروردین ۱۴۰۴ و در تایمزونUTCبشه ۳۰ اسفند ۱۴۰۳. - محاسبات ماه و سال (اگر پیادهسازی کردید): ۳۱ شهریور ۱۴۰۴ + ۱ ماه = ۳۰ مهر ۱۴۰۴؛ و ۳۰ اسفند ۱۴۰۳ + ۱ سال = ۲۹ اسفند ۱۴۰۴.
- تست اعداد میانی منفی: تبدیل دوطرفهٔ تکتک روزهای سالهای ۱۰۰۰− تا ۱۱۷۷. برای سالهای صفر و منفی، مقادیر میانی فرمولها منفی میشن و اگر تقسیم کف (Floor division) رو اشتباه نوشته باشید، دقیقا اینجا لو میره! چند مقدار ثابت که تمام پیادهسازیهای این مخزن با اونها چک میشن:
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. - رد کردن ورودیهای غیرصحیح در زبانهای داینامیک (مثلا
is_valid(1404, 1.5, 1)بایدfalseبرگردونه یا خطا بده). - کنترل مرزهای ورودی: اولین و آخرین روز بازهٔ مجاز باید درست تبدیل بشن؛ اما حتی یک روز خارج از بازه، اعداد خیلی بزرگ (۲⁵³ یا
INT64_MAX) و تاریخهای میلادی نامعتبر (2025-02-29،2025-02-30،1900-02-29) باید بدون سرریز یا هنگ کردن، با خطا رد بشن. در زبان C هم چک کنید که در صورت بروز خطا، متغیرهای خروجی دستنخورده باقی بمونن و کد رو حتما با-fsanitize=undefinedتست کنید. - تست کل بازهٔ مجاز، سالبهسال (یک حلقهٔ سریع روی تمام سالها): برای هر سال از ابتدا تا انتهای بازهٔ مجاز، بررسی کنید که ۱ فروردین دقیقا فردای آخرین روز سال قبل باشه و روز اول و آخر هر سال درست تبدیل بشن. برای بازهٔ ۱۰۰٬۰۰۰− تا ۱۰۰٬۰۰۰ در این مخزن، دو جمع کنترلی (Checksum) جای تمام کبیسهها رو تایید میکنن: ۴۸٬۴۸۵ سال کبیسه و مجموع JDN نوروزها برابر با ۳۸۹٬۵۹۲٬۹۷۸٬۱۸۰ (که چون کمتر از ۲⁵³ است، حتی با اعداد جاوااسکریپت هم بدون خطا حساب میشه). موتورهای ICU 77.1+، ICU4X و Temporal هم دقیقا همین دو عدد رو میدن.
تمام ۱۴ پیادهسازی موجود در پوشهٔ implementations تستهای ۱ تا ۴، ۷، ۹ و ۱۰ رو دارن و تست شمارهٔ ۱ رو برای تکتک ۶۶۵٬۸۳۷ روز بازهٔ ۱۱۷۸ تا ۳۰۰۰ اجرا میکنن. وقتی کد هر زبانی رو برمیدارید، فایل تستش رو هم همراهش کپی کنید.
مقایسهٔ متقابل با موتورهای ICU و ICU4X
پیوند به بخش مقایسهٔ متقابل با موتورهای ICU و ICU4Xابزار tools/icu-cross-check تکتک روزهای سال ۱۱۷۸ تا ۳۰۰۰ رو بین دادههای مرجع نجومی، هر ۱۴ پیادهسازی این مخزن، کتابخونهٔ ICU4X (icu_calendar 2.4 و calendrical_calculations)، کتابخونهٔ ICU4J نسخههای 76.1 تا 79.1 (در Java، Kotlin و Scala)، کتابخونهٔ ICU4C نسخههای 76.1 تا 79.1 (Intl در Node.js، افزونهٔ intl در PHP و فراخوانی مستقیم C API از طریق Python، Ruby، Go، C#، Dart و C)، موتور Temporal (temporal_rs در Node.js 26) و کلاس PersianCalendar در .NET مقایسه میکنه. (چون PostgreSQL تقویم شمسی داخلی نداره، توابع SQL ما روی موتور واقعی PGlite اجرا میشن و خروجیشون با ICU و Temporal مقایسه میشه.)
نتیجه: ICU 77.1 به بعد، ICU4X و Temporal در تمام روزها صددرصد منطبق هستن؛ ICU 76.1 دقیقا فرمول سادهٔ ۳۳ ساله رو اجرا میکنه (از سال ۱۵۰۳ خطا داره) و PersianCalendar در .NET هم در ۱۲ سال (مجموعا ۲٬۱۹۶ روز، از سال ۱۵۳۵ به بعد) اختلاف داره.
مقایسه با Formatter داخلی پلتفرم
پیوند به بخش مقایسه با Formatter داخلی پلتفرماگر روی پلتفرمی کار میکنید که ICU 77.1 یا جدیدتر داره (مثل Node.js 24+ یا مرورگرهای بهروز)، میتونید خروجی کدتون رو در یک حلقه با Intl.DateTimeFormat مقایسه کنید؛ دقیقا مثل کاری که در implementations/javascript/persian-calendar.test.js انجام شده است:
const fmt = new Intl.DateTimeFormat('en-u-ca-persian-nu-latn', { timeZone: 'UTC', year: 'numeric', month: 'numeric', day: 'numeric' })چطور یک کتابخانهٔ جدید رو تست و ارزیابی کنیم؟
پیوند به بخش چطور یک کتابخانهٔ جدید رو تست و ارزیابی کنیم؟توی پوشهٔ tools/library-evaluation اسکریپتهای آماده برای تست کتابخونههای JavaScript، Python، Java، Rust، Dart، PHP، Go، .NET و Ruby قرار دارن.
برای اضافه کردن یک کتابخونهٔ جدید، کافیه تاریخ میلادی نوروز رو برای سالهای ۱۱۰۰ تا ۳۳۰۰ از اون کتابخونه بگیرید و توی فایل results/<name>.txt (در هر خط به فرمت <year> <YYYY-MM-DD>) ذخیره کنید، و بعد توی پوشهٔ tools/calendar-data دستور cargo run --release -- score-libraries رو اجرا کنید.
اجرای تمام تستهای این مخزن
پیوند به بخش اجرای تمام تستهای این مخزنcd tools/calendar-data && cargo run --release -- --check # data files are up to date
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 (via PGlite)همچنین میتونید با اجرای اسکریپت bash tools/run-all-tests.sh تمام تستهایی رو که کامپایلر/مفسرشون روی سیستمتون نصبه، یکجا اجرا کنید. همین دستورات در سرویس CI گیتهاب هم اجرا میشن: .github/workflows/test.yml.