# IPerson Tests Documentation

This test suite provides comprehensive coverage for the `IPerson` model's custom decoder, ensuring it handles missing, null, and malformed field values gracefully.

## Test Coverage

### 1. Complete Data Test (`testIPersonParsing_WithCompleteData`)
Tests parsing when all fields are present and properly formatted.

### 2. Missing Identity Fields (`testIPersonParsing_WithMissingIdentityFields`)
Tests behavior when critical identity fields are missing:
- `pin`
- `doc_pinfl`
- `doc_seria`
- `doc_number`
- `document`
- `current_document`
- `current_pinpp`

**Expected Behavior**: All missing String fields default to `""` (empty string)

### 3. Missing Name Fields (`testIPersonParsing_WithMissingNameFields`)
Tests all name-related fields in different languages/formats:
- Latin names: `first_name`, `last_name`, `namelat`, `surnamelat`, `patronymlat`
- Cyrillic names: `namecyr`, `surnamecyr`, `patronymcyr`
- English names: `engname`, `engsurname`, `engpatronym`
- Other variations: `surname`, `givenname`, `patronym`, `patronym_en`

**Expected Behavior**: All missing name fields default to `""`

### 4. Missing Document Date Fields (`testIPersonParsing_WithMissingDocumentDates`)
Tests document-related date and location fields:
- `date_issue`
- `date_expiry`
- `give_place`
- `give_place_name`

**Expected Behavior**: All missing fields default to `""`

### 5. Missing Location Fields (`testIPersonParsing_WithMissingLocationFields`)
Tests birth and citizenship location fields:
- Birth location: `birth_place`, `birthplace`, `birth_country`, `birth_country_name`, `birthcountry`, `birthcountryid`
- Citizenship: `citizenship`, `citizenship_name`, `citizenshipid`
- Nationality: `nationality`, `nationality_name`, `nationalityid`

**Expected Behavior**: All missing fields default to `""`

### 6. Missing Gender and Status Fields (`testIPersonParsing_WithMissingGenderAndStatus`)
Tests demographic and status fields:
- Integer fields: `gender`, `subject_state`
- String fields: `gender_name`, `sex`, `subject_state_name`, `livestatus`

**Expected Behavior**:
- Missing Int fields default to `0`
- Missing String fields default to `""`

### 7. Missing Media Fields (`testIPersonParsing_WithMissingMediaFields`)
Tests biometric and media fields:
- `photo` (base64 encoded image)
- `signature` (base64 encoded signature or JWT)
- `capture` (base64 encoded capture)
- `score` (Double value)

**Expected Behavior**:
- Missing String fields default to `""`
- Missing Double fields default to `0.0`

### 8. Missing PINPP Fields (`testIPersonParsing_WithMissingPINPPFields`)
Tests alternative PINFL fields:
- `pinpps_1`, `pinpps_2`, `pinpps_3`, `pinpps_4`

**Expected Behavior**: All missing fields default to `""`

### 9. Empty Documents Array (`testIPersonParsing_WithNoDocuments`)
Tests when no document entries are present in the JSON.

**Expected Behavior**:
- `documents` array is empty (`[]`)
- `foreignDocuments` array is empty (`[]`)

### 10. Partial Documents (`testIPersonParsing_WithPartialDocuments`)
Tests when some document indexes have data but others don't (e.g., `documents_1_*` and `documents_3_*` exist, but `documents_2_*` doesn't).

**Expected Behavior**:
- Only documents with non-empty `document` fields are included
- Documents are parsed correctly from the flat structure

### 11. Minimal Data Test (`testIPersonParsing_WithOnlyIDField`)
Tests extreme case with only the `id` field present.

**Expected Behavior**:
- `id` has the provided value
- All other fields use their default values

### 12. Null Values (`testIPersonParsing_WithNullValues`)
Tests behavior when fields explicitly have `null` values in JSON.

**Expected Behavior**: Same as missing fields (empty strings, zeros)

### 13. Empty Strings (`testIPersonParsing_WithEmptyStrings`)
Tests when fields are present but contain empty strings (`""`).

**Expected Behavior**: Empty strings remain empty strings

### 14. Whitespace Values (`testIPersonParsing_WithWhitespaceValues`)
Tests fields containing only whitespace (spaces, tabs, newlines).

**Expected Behavior**:
- Whitespace-only values are trimmed to empty strings
- Values with text and surrounding whitespace are trimmed

### 15. Mixed Fields (`testIPersonParsing_WithMixedFields`)
Tests a realistic scenario with some fields present and others missing.

**Expected Behavior**:
- Present fields retain their values
- Missing fields use defaults

## Default Values Summary

| Field Type | Default Value |
|------------|---------------|
| String | `""` (empty string) |
| Int | `0` |
| Double | `0.0` |
| Array | `[]` (empty array) |

## Running the Tests

### From Xcode
1. Open the project in Xcode
2. Press `Cmd + U` to run all tests
3. Or click the test diamond next to individual test methods

### From Command Line
```bash
xcodebuild test -scheme YourSchemeName -destination 'platform=iOS Simulator,name=iPhone 15'
```

## Key Features of the IPerson Decoder

The custom `init(from decoder: Decoder)` implementation:

1. **Flexible Field Lookup**: Uses helper functions (`str()`, `int()`, `double()`) that can try multiple field name variations
2. **Whitespace Trimming**: Automatically trims whitespace from string values
3. **Type Coercion**: Can convert between Int and String when needed
4. **Empty String Filtering**: Treats empty strings as missing values and continues searching
5. **Document Parsing**: Constructs nested document arrays from flat JSON structure
6. **Safe Defaults**: Never throws errors for missing fields, always provides safe defaults

## Edge Cases Handled

- Missing required fields
- Null values
- Empty strings
- Whitespace-only strings
- Partial document arrays with gaps
- Type mismatches (string numbers converted to Int)
- Completely empty JSON (only ID present)
