# LocalData Testing Strategy

## Goal
To ensure high reliability for data persistence, security, and migration across all supported platforms (iOS and watchOS).

## Test Suites

### Unit Tests (`Tests/LocalDataTests/`)
- **LocalDataTests.swift**: Core round-trip tests for each storage domain (UserDefaults, FileSystem).
- **KeychainHelperTests.swift**: Verification of Keychain API interactions (add, update, delete, exists).
- **EncryptionHelperTests.swift**: Round-trip tests for AES and ChaCha20 encryption/decryption with various key derivation methods.
- **StorageCatalogTests.swift**: Validation of catalog registration, duplicate detection, and missing description checks.

## Key Testing Patterns

### 1. Domain Round-Trips
Always test the full cycle: `set` -> `get` (compare) -> `remove` -> `get` (expect `notFound`).

### 2. Migration Tests
Simulate legacy data by writing to a "legacy" key first, then verifying that the "modern" key can retrieve and consolidate that data.

### 3. Error Handling
Verify that the correct `StorageError` is thrown for:
- `notFound`
- `unregisteredKey`
- `dataTooLargeForSync`
- Domain-specific failures (e.g., Keychain errors)

## Running Tests
Run all tests from the package root:
```bash
swift test
```

### Xcode Command Line
For packages that use platform-specific features (like `WatchConnectivity`), use `xcodebuild`:

```bash
# Run on an available simulator (e.g., iPhone 16)
xcodebuild test -scheme LocalData -destination 'platform=iOS Simulator,name=iPhone 16'

# Or using the specific device ID
xcodebuild test -scheme LocalData -destination 'id=4BF0FAE0-8FC1-4E19-89F4-2EDF12A28847'
```

### Xcode Test Plans
For granular control (enabling/disabling specific tests or trying different configurations), use **Xcode Test Plans**:

1. **Create a Test Plan**:
   - Go to **Product > Test Plan > New Test Plan...**
   - Save it in your `Tests/` directory as `LocalData.xctestplan`.
2. **Configure Tests**:
   - Open the `.xctestplan` file.
   - You will see a list of all test targets, classes, and individual test methods.
   - Use the **check/uncheck** boxes to include or exclude specific tests.
3. **Run the Plan**:
   - Hold down the **Play** button for the test action or go to **Product > Test > [Plan Name]**.
   - You can also run it via terminal: `xcodebuild test -plan LocalData`.

> [!TIP]
> Test plans are excellent for CI/CD environments where you might want to run a "Smoke Test" plan (subset of tests) or a "Full Integration" plan.