herolib/lib/threefold/models_ledger/README_TESTS.md

Models Ledger Tests

This directory contains comprehensive tests for all models in the models_ledger module. The tests focus primarily on encoding/decoding functionality to ensure data integrity through the database layer.

Test Structure

Each model has its own test file following the naming convention {model}_test.v:

• account_test.v - Tests for Account model with complex nested structures
• asset_test.v - Tests for Asset model with metadata maps
• user_test.v - Tests for User model with SecretBox arrays
• transaction_test.v - Tests for Transaction model with signature arrays
• dnszone_test.v - Tests for DNSZone model with DNS records and SOA records
• group_test.v - Tests for Group model with configuration structs
• member_test.v - Tests for Member model with enums
• notary_test.v - Tests for Notary model
• signature_test.v - Tests for Signature model
• userkvs_test.v - Tests for UserKVS model
• userkvsitem_test.v - Tests for UserKVSItem model
• models_test.v - Integration tests for all models together

Test Categories

1. Model Creation (test_{model}_new)

Tests the creation of new model instances with all field types:

• Required fields
• Optional fields
• Default values
• Complex nested structures
• Arrays and maps

2. Encoding/Decoding (test_{model}_encoding_decoding)

Primary focus - Tests the serialization and deserialization:

• Encoding to binary format using dump(mut encoder.Encoder)
• Decoding from binary format using load(mut decoder.Decoder)
• Field-by-field verification after roundtrip
• Complex data structures (nested structs, arrays, maps)
• Edge cases (empty data, large data)

3. Database Operations (test_{model}_set_and_get)

Tests CRUD operations through the database layer:

• Create and save (set)
• Retrieve (get)
• ID assignment
• Data persistence through database roundtrip

4. Update Operations (test_{model}_update)

Tests updating existing records:

• Modify fields
• Save changes
• Verify updates persist
• ID and created_at preservation

5. Existence and Deletion (test_{model}_exist_and_delete)

Tests existence checking and deletion:

• Check non-existent records
• Create and verify existence
• Delete records
• Verify deletion

6. List Operations (test_{model}_list)

Tests listing all records:

• Initial empty state
• Create multiple records
• List and count verification
• Find specific records in lists

7. Edge Cases (test_{model}_edge_cases)

Tests boundary conditions:

• Empty/minimal data
• Very large data
• Special characters
• Unicode handling
• Maximum array sizes

Key Features Tested

Encoding/Decoding Integrity

• Primitive types: strings, integers, floats, booleans
• Arrays: []u32, []string, []SecretBox, etc.
• Maps: map[string]string for metadata
• Enums: All enum types with proper conversion
• Nested structs: Complex hierarchical data
• Binary data: Encrypted data in SecretBox

Complex Data Structures

• Account: Nested AccountPolicy and AccountAsset arrays
• DNSZone: DNS records with different types and SOA records
• User: Encrypted data arrays (userprofile, kyc)
• Transaction: Signature arrays with timestamps
• Group: Configuration structs with multiple fields

Performance Considerations

• Large array handling (1000+ elements)
• Large binary data (10KB+ encrypted data)
• Complex nested structures
• Memory efficiency during encoding/decoding

Running Tests

Run all model tests:

vtest ~/code/github/incubaid/herolib/lib/threefold/models_ledger/

Run specific model tests:

vtest ~/code/github/incubaid/herolib/lib/threefold/models_ledger/account_test.v
vtest ~/code/github/incubaid/herolib/lib/threefold/models_ledger/user_test.v

Run integration tests:

vtest ~/code/github/incubaid/herolib/lib/threefold/models_ledger/models_test.v

Common Test Patterns

Setup

Each test file uses a common setup function:

fn setup_test_db() !db.DB {
    return db.new(path: ':memory:')!
}

Encoding/Decoding Pattern

// Test encoding
mut encoder_obj := encoder.encoder_new()
original_object.dump(mut encoder_obj)!
encoded_data := encoder_obj.data

// Test decoding
mut decoder_obj := encoder.decoder_new(encoded_data)
mut decoded_object := ObjectType{}
object_db.load(mut decoded_object, mut decoder_obj)!

// Verify all fields match
assert decoded_object.field == original_object.field

CRUD Pattern

// Create
mut object := object_db.new(args)!

// Save
object = object_db.set(object)!
assert object.id > 0

// Get
retrieved := object_db.get(object.id)!
assert retrieved.field == object.field

// Update
object.field = new_value
object = object_db.set(object)!

// Delete
object_db.delete(object.id)!
assert object_db.exist(object.id)! == false

Error Conditions

Tests verify proper error handling for:

• Non-existent record retrieval
• Invalid data encoding/decoding
• Database constraint violations
• Memory allocation failures

Performance Metrics

Integration tests include performance verification:

• Large data encoding/decoding speed
• Memory usage with complex structures
• Database roundtrip efficiency
• Array and map handling performance

The tests ensure that all models can handle real-world usage scenarios with proper data integrity and performance characteristics.