Rust Unit & Golden Testing
Relevant source files
The following files were used as context for generating this wiki page:
- README.md
- rust/hesabyar-core/README.md
- app/src/test/java/io/github/mojri/hesabyar/rust/RustBridgeTest.kt
- rust/hesabyar-core/src/ai_validation.rs
- rust/hesabyar-core/src/analytics.rs
- rust/hesabyar-core/src/parser/nlp.rs
- app/src/test/java/io/github/mojri/hesabyar/domain/usecase/GetAnalyticsUseCaseRustTest.kt
The Hesabyar project employs a robust testing strategy for its shared native core, hesabyar-core. This strategy ensures the reliability of critical business logic, including Persian Natural Language Processing (NLP), Jalali calendar conversions, and financial analytics. Testing is conducted at multiple levels: internal Rust unit tests, performance benchmarks, and cross-platform bridge tests that verify the integration between Kotlin and Rust via UniFFI.
The testing infrastructure is designed to prevent regressions in high-performance paths (e.g., amount parsing) and to maintain accuracy across the Jalali/Gregorian date boundary. "Golden testing" specifically refers to the use of fixed, known-good JSON datasets (found in rust/hesabyar-core/tests/golden/) to validate complex Persian parsing cases against expected outputs.
Sources: README.md:21-26, rust/hesabyar-core/README.md:9-25
Testing Architecture and Tiers
The testing suite is divided into three primary tiers: native Rust tests, performance benchmarks using Criterion, and JVM-based bridge tests.
Native Rust Tests
These tests reside within the hesabyar-core crate and use the standard cargo test harness. They cover:
- Logic Validation: Verifying internal state and algorithm correctness for analytics and search.
- NLP Verification: Testing the 200+ keyword Persian inference engine.
- Sanitization: Ensuring AI-generated text is stripped of dangerous HTML/JavaScript tags.
Performance Benchmarks
The project utilizes the Criterion framework for benchmarking "hot" code paths like numeric parsing and text normalization. This helps monitor for performance regressions during refactoring.
Cross-Platform Integration Tests
These tests run on the JVM (Android Studio environment) but load the real native hesabyar_core library. They verify that the RustBridge.kt correctly delegates calls and maps data structures between Kotlin and Rust.
The diagram shows how various testing components interact with the Rust Core logic across different layers of the application.
Sources: README.md:21-26, rust/hesabyar-core/README.md:73-86, app/src/test/java/io/github/mojri/hesabyar/rust/RustBridgeTest.kt:18-24
Validation and Sanitization Testing
A significant portion of the test suite is dedicated to the ai_validation.rs module. This module ensures that AI-generated responses (e.g., from Gemini) are safe and follow the application's domain constraints.
AI Transaction JSON Validation
Tests verify that the parser can handle malformed JSON, coerce unknown transaction types to "EXPENSE", and clamp numeric values (like confidence scores) to valid ranges.
| Test Case | Description | Expected Outcome |
|---|---|---|
test_valid_full_json | Complete AI JSON payload | Parsed into ParsedResult with 0.95 confidence |
test_unknown_type_repaired | JSON with type "TRANSFER" | Repaired to "EXPENSE" with repair notes |
test_amount_truncated | Float amount (500.7) | Truncated to i64 (500) |
test_confidence_clamped | Confidence > 1.0 | Clamped to 1.0 |
Sources: rust/hesabyar-core/src/ai_validation.rs:250-320, rust/hesabyar-core/src/ai_validation.rs:410-430
Text Sanitization
The system tests for "dangerous" patterns in free-form AI advice. The sanitization logic strips <script> tags and javascript: schemes while preserving the rest of the message.
The sequence diagram illustrates the sanitization flow for AI-generated text content.
Sources: rust/hesabyar-core/src/ai_validation.rs:200-245, app/src/test/java/io/github/mojri/hesabyar/rust/AiAdviceSanitizationTest.kt:20-35
Analytics and Data Integrity
Analytics testing ensures that the transition from Kotlin to Rust does not impact the accuracy of financial calculations.
Monthly Aggregates
Tests in analytics.rs verify that transactions are correctly grouped by Jalali months rather than Gregorian months. This is critical for Persian users whose financial cycles follow the Jalali calendar.
Sources: rust/hesabyar-core/src/analytics.rs:140-160
Debt and Progress Tracking
The analytics engine calculates progress toward loan settlement. Tests verify the math: (Original - Remaining) / Original.
Sources: rust/hesabyar-core/src/analytics.rs:250-265, app/src/test/java/io/github/mojri/hesabyar/domain/usecase/GetAnalyticsUseCaseRustTest.kt:60-80
Performance Stress Testing
The test_large_dataset_no_panic test case processes 10,000 transactions to ensure that the aggregate calculations and percentage summaries remain stable and do not cause memory overflows or panics.
Sources: rust/hesabyar-core/src/analytics.rs:300-315
Persian NLP (Natural Language Processing) Testing
The NLP parser is tested against a variety of Persian linguistic patterns. This includes checking for word boundaries to avoid false positives (e.g., ensuring the filler word "به" is not stripped from the word "نوشابه").
Feature Coverage
| Component | Tested Behavior | Source Reference |
|---|---|---|
| Category Inference | Maps 200+ keywords (e.g., "مرغ", "اسنپ") to 8 core categories | rust/hesabyar-core/src/parser/nlp.rs:400-450 |
| Date Offset | Identifies "دیروز" (-1), "پسفردا" (+2), etc. | rust/hesabyar-core/src/parser/nlp.rs:640-660 |
| Time Extraction | Parses "ساعت ۲ و نیم عصر" to 14:30 | rust/hesabyar-core/src/parser/nlp.rs:680-710 |
| Amount Parsing | Interprets "۵ هزار تومان" as 50,000 Rials | rust/hesabyar-core/src/parser/nlp.rs:770-785 |
Execution Commands
Developers can run the different tiers of tests using the following commands:
# Run all native Rust unit tests
cd rust/hesabyar-core
cargo test
# Run Rust tests with stdout captured (for debugging)
cargo test -- --nocapture
# Run Criterion performance benchmarks
cargo bench
# Run JVM bridge tests from the project root
./gradlew test --tests "io.github.mojri.hesabyar.rust.*" --no-daemon
Sources: README.md:255-275, rust/hesabyar-core/README.md:40-60
Conclusion
Rust Unit & Golden Testing in Hesabyar provides a safety net for the core financial and linguistic logic of the application. By combining strict native unit tests, performance-focused benchmarks, and real-world cross-platform integration tests, the project ensures that its high-performance Rust core remains accurate and secure across updates.