# QA Plan: User Preferences API

## Test Scenarios

### Happy Path

| ID | Scenario | Input | Expected Output | Derived From |
|----|----------|-------|-----------------|--------------|
| HP-1 | Get preferences for user with saved preferences | `GET /api/preferences-api/preferences/{user_id}` with valid JWT matching user_id | 200 with `{data: {user_id, preferences: {theme: "dark", language: "en", notifications_enabled: true}, updated_at: "..."}, meta: {...}}` | AC-1 |
| HP-2 | Get preferences for user with no saved preferences | `GET /api/preferences-api/preferences/{user_id}` for user with no row | 200 with `{data: {user_id, preferences: {}, updated_at: null}, meta: {...}}` | AC-2 |
| HP-3 | Create preferences for new user (upsert - insert) | `PUT /api/preferences-api/preferences/{user_id}` with `{"preferences": {"theme": "dark"}}` | 200 with `{data: {user_id, preferences: {theme: "dark"}, updated_at: "..."}, meta: {...}}` | AC-3 |
| HP-4 | Update existing preferences (upsert - update) | `PUT` with `{"preferences": {"theme": "light"}}` for user who already has theme: "dark" | 200 with preferences showing `theme: "light"`, other keys preserved | AC-3 |
| HP-5 | Partial update preserves omitted keys | `PUT` with `{"preferences": {"theme": "dark"}}` for user who has `language: "en"` and `notifications_enabled: true` | 200 with all three keys present: theme changed, language and notifications_enabled unchanged | AC-4 |
| HP-6 | Set theme to "light" | `PUT` with `{"preferences": {"theme": "light"}}` | 200 with `theme: "light"` | AC-5 |
| HP-7 | Set theme to "dark" | `PUT` with `{"preferences": {"theme": "dark"}}` | 200 with `theme: "dark"` | AC-5 |
| HP-8 | Set language to valid ISO 639-1 code | `PUT` with `{"preferences": {"language": "es"}}` | 200 with `language: "es"` | AC-5 |
| HP-9 | Set notifications_enabled to true | `PUT` with `{"preferences": {"notifications_enabled": true}}` | 200 with `notifications_enabled: true` | AC-5 |
| HP-10 | Set notifications_enabled to false | `PUT` with `{"preferences": {"notifications_enabled": false}}` | 200 with `notifications_enabled: false` | AC-5 |
| HP-11 | Update all three preferences at once | `PUT` with `{"preferences": {"theme": "dark", "language": "fr", "notifications_enabled": false}}` | 200 with all three keys updated | AC-3, AC-5 |
| HP-12 | Response envelope structure on GET | Valid GET request | Response has top-level `data` and `meta` keys, meta includes `request_id` and `timestamp` | AC-11 |
| HP-13 | Response envelope structure on PUT | Valid PUT request | Response has top-level `data` and `meta` keys | AC-11 |

### Edge Cases

| ID | Scenario | Input | Expected Output | Derived From |
|----|----------|-------|-----------------|--------------|
| EC-1 | Partial update with single key on user with all three set | `PUT` with `{"preferences": {"language": "de"}}` for user with theme, language, notifications_enabled | 200 with only language changed, theme and notifications_enabled preserved | AC-4 |
| EC-2 | Update same key to its current value (no-op update) | `PUT` with `{"preferences": {"theme": "dark"}}` when already `theme: "dark"` | 200 with unchanged preferences, `updated_at` refreshed | AC-3, AC-4 |
| EC-3 | Empty preferences object on PUT | `PUT` with `{"preferences": {}}` | 200 with existing preferences unchanged (no keys to update) OR 400 depending on validation rules | AC-4 |
| EC-4 | Language code at boundary - two lowercase letters | `PUT` with `{"preferences": {"language": "zz"}}` | 200 accepted (matches `^[a-z]{2}$` even if not a real language) | AC-5 |
| EC-5 | Multiple sequential partial updates accumulate correctly | PUT theme, then PUT language, then PUT notifications_enabled | GET returns all three keys | AC-4 |
| EC-6 | User ID is a valid UUID but very specific format | `GET /api/preferences-api/preferences/00000000-0000-0000-0000-000000000000` | 200 with empty preferences (valid UUID, no row) | AC-2 |
| EC-7 | Concurrent upserts for same user | Two simultaneous PUT requests with different keys | Both keys present after resolution (JSONB merge is atomic via ON CONFLICT) | AC-3, AC-4 |

### Error Cases

| ID | Scenario | Input | Expected Output | Derived From |
|----|----------|-------|-----------------|--------------|
| ER-1 | Invalid theme value | `PUT` with `{"preferences": {"theme": "blue"}}` | 400 Bad Request with descriptive error message mentioning "theme" | AC-6 |
| ER-2 | Invalid language - too long | `PUT` with `{"preferences": {"language": "eng"}}` | 400 Bad Request with descriptive error | AC-6 |
| ER-3 | Invalid language - uppercase | `PUT` with `{"preferences": {"language": "EN"}}` | 400 Bad Request | AC-6 |
| ER-4 | Invalid language - contains numbers | `PUT` with `{"preferences": {"language": "e1"}}` | 400 Bad Request | AC-6 |
| ER-5 | Invalid language - single character | `PUT` with `{"preferences": {"language": "e"}}` | 400 Bad Request | AC-6 |
| ER-6 | Invalid notifications_enabled - string instead of bool | `PUT` with `{"preferences": {"notifications_enabled": "yes"}}` | 400 Bad Request | AC-6 |
| ER-7 | Invalid notifications_enabled - number instead of bool | `PUT` with `{"preferences": {"notifications_enabled": 1}}` | 400 Bad Request | AC-6 |
| ER-8 | Unknown preference key | `PUT` with `{"preferences": {"font_size": 14}}` | 400 Bad Request with message about unknown key | AC-7 |
| ER-9 | Mix of valid and unknown keys | `PUT` with `{"preferences": {"theme": "dark", "unknown_key": "value"}}` | 400 Bad Request (entire request rejected) | AC-7 |
| ER-10 | Unauthenticated GET request | `GET` without Authorization header | 401 Unauthorized | AC-8 |
| ER-11 | Unauthenticated PUT request | `PUT` without Authorization header | 401 Unauthorized | AC-8 |
| ER-12 | Invalid JWT token on GET | `GET` with `Authorization: Bearer invalid-token` | 401 Unauthorized | AC-8 |
| ER-13 | Invalid JWT token on PUT | `PUT` with `Authorization: Bearer invalid-token` | 401 Unauthorized | AC-8 |
| ER-14 | User accessing another user's preferences (GET) | `GET /api/preferences-api/preferences/{other_user_id}` with JWT for different user | 403 Forbidden with "access denied" | AC-9 |
| ER-15 | User updating another user's preferences (PUT) | `PUT /api/preferences-api/preferences/{other_user_id}` with JWT for different user | 403 Forbidden with "access denied" | AC-9 |
| ER-16 | Invalid UUID format in path (GET) | `GET /api/preferences-api/preferences/not-a-uuid` | 400 Bad Request with "invalid user ID format" | AC-1, Design |
| ER-17 | Invalid UUID format in path (PUT) | `PUT /api/preferences-api/preferences/not-a-uuid` | 400 Bad Request with "invalid user ID format" | AC-3, Design |
| ER-18 | Missing preferences field in PUT body | `PUT` with `{}` (empty body) | 400 Bad Request (BindAndValidate rejects missing required field) | AC-3, Design |
| ER-19 | Malformed JSON body on PUT | `PUT` with `{invalid json` | 400 Bad Request | Design |
| ER-20 | Theme value is null | `PUT` with `{"preferences": {"theme": null}}` | 400 Bad Request | AC-6 |
| ER-21 | Preference value is nested object | `PUT` with `{"preferences": {"theme": {"mode": "dark"}}}` | 400 Bad Request | AC-6 |
| ER-22 | Preference value is array | `PUT` with `{"preferences": {"theme": ["dark"]}}` | 400 Bad Request | AC-6 |
| ER-23 | Empty string for language | `PUT` with `{"preferences": {"language": ""}}` | 400 Bad Request | AC-6 |

## Domain Validation Unit Tests

| ID | Scenario | Input | Expected Output | Derived From |
|----|----------|-------|-----------------|--------------|
| DV-1 | ValidatePreferences accepts valid theme | `{"theme": "dark"}` | nil (no error) | AC-13 |
| DV-2 | ValidatePreferences accepts valid language | `{"language": "en"}` | nil | AC-13 |
| DV-3 | ValidatePreferences accepts valid notifications_enabled | `{"notifications_enabled": true}` | nil | AC-13 |
| DV-4 | ValidatePreferences accepts all three valid keys | `{"theme": "light", "language": "fr", "notifications_enabled": false}` | nil | AC-13 |
| DV-5 | ValidatePreferenceKey rejects unknown key | `"font_size"` | ErrInvalidPreferenceKey | AC-13 |
| DV-6 | ValidatePreferenceValue rejects invalid theme | `("theme", "blue")` | ErrInvalidPreferenceValue | AC-13 |
| DV-7 | ValidatePreferenceValue rejects invalid language format | `("language", "ENG")` | ErrInvalidPreferenceValue | AC-13 |
| DV-8 | ValidatePreferenceValue rejects non-boolean notifications | `("notifications_enabled", "yes")` | ErrInvalidPreferenceValue | AC-13 |

## Service Layer Unit Tests

| ID | Scenario | Input | Expected Output | Derived From |
|----|----------|-------|-----------------|--------------|
| SV-1 | Get returns preferences for existing user | Mock repo returns UserPreferences | *UserPreferences with data | AC-15 |
| SV-2 | Get returns empty preferences for new user | Mock repo returns nil | *UserPreferences with empty map | AC-15 |
| SV-3 | Update with valid preferences calls repo Upsert | Valid prefs map | Upsert called, result returned | AC-15 |
| SV-4 | Update with unknown key returns domain error | `{"unknown": "value"}` | ErrInvalidPreferenceKey (no repo call) | AC-15 |
| SV-5 | Update with invalid value returns domain error | `{"theme": "blue"}` | ErrInvalidPreferenceValue (no repo call) | AC-15 |
| SV-6 | Update propagates repository error | Valid prefs, repo returns error | Error propagated unchanged | AC-15 |

## Handler Integration Tests

| ID | Scenario | Input | Expected Output | Derived From |
|----|----------|-------|-----------------|--------------|
| HI-1 | GET 200 with existing preferences | Authenticated request, mock repo returns data | 200, {data, meta} envelope | AC-16 |
| HI-2 | GET 200 with empty preferences | Authenticated request, mock repo returns nil | 200, empty preferences in envelope | AC-16 |
| HI-3 | GET 400 for invalid UUID | `/preferences/not-a-uuid` | 400 | AC-16 |
| HI-4 | PUT 200 on success | Valid body, authenticated | 200, merged preferences | AC-16 |
| HI-5 | PUT 400 for unknown key | `{"preferences": {"bad_key": "val"}}` | 400 | AC-16 |
| HI-6 | PUT 400 for invalid value | `{"preferences": {"theme": "nope"}}` | 400 | AC-16 |
| HI-7 | PUT 400 for missing preferences field | `{}` | 400 | AC-16 |
| HI-8 | All responses use {data, meta} envelope | Any successful response | Top-level keys are `data` and `meta` | AC-16 |

## Test Data Requirements

### Fixtures
- **Test user UUID**: A fixed UUID for the authenticated test user (e.g., `550e8400-e29b-41d4-a716-446655440000`)
- **Other user UUID**: A different UUID for authorization tests (e.g., `660e8400-e29b-41d4-a716-446655440001`)
- **Sample preferences**: `{"theme": "dark", "language": "en", "notifications_enabled": true}`

### Mocks
- **Mock PreferencesRepository**: Implements `port.PreferencesRepository` with configurable return values and error injection for service-layer unit tests
- **Mock PreferencesService**: For handler tests, a service mock that returns canned responses or errors
- **Auth context**: Test helper to inject authenticated user into request context via `auth.MustGetUser()` compatible format
- **No-op logger**: `logging.Nop()` for all test setups

### Database (for integration tests if added later)
- PostgreSQL test database with migrations applied
- Each test should run in a transaction that is rolled back after the test

## Integration Test Plan

### Component Interaction Points
1. **Handler → Service**: Handlers delegate to service methods; test with mock service to verify correct method calls and argument passing
2. **Service → Domain Validation**: Service calls `domain.ValidatePreferences` before repository; test that invalid input never reaches the repository mock
3. **Service → Repository**: Service calls `repo.Get` and `repo.Upsert`; test with mock repository to verify correct delegation
4. **Handler → Auth Middleware**: Auth middleware extracts JWT and sets user context; handler reads context to check ownership
5. **Handler → chi Router**: URL parameters extracted correctly with `{user_id}` brace syntax; test that routing dispatches correctly

### Cross-Layer Scenarios
| Scenario | Layers Involved | What to Verify |
|----------|----------------|----------------|
| Valid GET end-to-end | Router → Middleware → Handler → Service → Repo | Correct user_id flows through all layers, response is properly enveloped |
| Valid PUT end-to-end | Router → Middleware → Handler → BindAndValidate → Service → Domain → Repo | Input validated at domain layer, merged result returned through all layers |
| Invalid key rejected | Handler → Service → Domain | Domain error maps to 400 at handler layer, repo never called |
| Auth failure | Router → Middleware | 401 returned before handler is invoked |
| Authorization failure | Handler (ownership check) | 403 returned before service is called |
| DB error propagation | Repo → Service → Handler → app.Wrap | Raw error becomes 500, error is logged, no internal details leaked to client |

### Route Registration Verification
- `GET /api/preferences-api/preferences/{user_id}` is registered and routable
- `PUT /api/preferences-api/preferences/{user_id}` is registered and routable
- Both routes require authentication (middleware applied)
- Health endpoint (`GET /api/preferences-api/health`) remains functional and unauthenticated
- URL parameters use `{user_id}` brace syntax (not `:user_id` colon syntax)

## Performance Considerations

### Load Expectations
- **Read pattern**: Preferences fetched once per session start; expect ~1 GET per active user session
- **Write pattern**: Preferences updated infrequently (settings changes); expect <<1 PUT per session
- **Overall**: High read, very low write workload

### Latency Budget
- **GET**: < 10ms at p99 (single primary key lookup on small table)
- **PUT**: < 20ms at p99 (single upsert on primary key)

### Benchmarks to Run
| Benchmark | Method | Target |
|-----------|--------|--------|
| Single GET by primary key | `go test -bench BenchmarkGet` | < 1ms per operation against test DB |
| Single PUT upsert | `go test -bench BenchmarkUpsert` | < 2ms per operation against test DB |
| JSONB merge correctness under concurrent writes | Parallel test with `t.Parallel()` | No data loss or corruption |

### Data Size
- Each row ~200 bytes (UUID + small JSONB + timestamps)
- Table fits entirely in PostgreSQL buffer cache even at millions of users
- No additional indexes needed beyond the primary key

## Manual Verification Steps

1. **OpenAPI documentation renders correctly**
   - Start the service and navigate to the Scalar docs endpoint
   - Verify both GET and PUT endpoints appear with correct schemas
   - Verify request/response examples are accurate
   - Verify security requirements (Bearer auth) are documented

2. **Database migration runs cleanly**
   - Start the service against a fresh database
   - Verify `user_preferences` table is created with correct schema
   - Restart the service — verify migration is idempotent (no errors on re-run)

3. **Health endpoint still works**
   - `curl http://localhost:8001/api/preferences-api/health` returns 200

4. **End-to-end flow with real JWT**
   - Obtain a valid JWT token
   - `GET /api/preferences-api/preferences/{your_user_id}` → 200 with empty preferences
   - `PUT /api/preferences-api/preferences/{your_user_id}` with `{"preferences": {"theme": "dark"}}` → 200
   - `GET /api/preferences-api/preferences/{your_user_id}` → 200 with `{"theme": "dark"}`
   - `PUT` with `{"preferences": {"language": "en"}}` → 200, verify theme is still "dark"
   - `GET` → 200, verify both theme and language are present

5. **Authorization boundary**
   - Use JWT for user A, try to GET/PUT preferences for user B → verify 403

6. **No Example scaffold remnants**
   - Verify no `/examples` routes respond
   - Verify no Example types in OpenAPI docs
   - `go build ./...` and `go test ./...` pass cleanly

## Acceptance Criteria Coverage Matrix

| AC # | Description | Test IDs |
|------|-------------|----------|
| AC-1 | GET returns all preferences as key-value pairs | HP-1, HI-1 |
| AC-2 | GET returns empty preferences (not 404) for new users | HP-2, EC-6, HI-2 |
| AC-3 | PUT creates or updates (upsert semantics) | HP-3, HP-4, HP-11, HI-4 |
| AC-4 | PUT supports partial updates, omitted keys preserved | HP-5, EC-1, EC-2, EC-5 |
| AC-5 | Supported preference keys with valid values | HP-6, HP-7, HP-8, HP-9, HP-10, EC-4 |
| AC-6 | Invalid values rejected with 400 and descriptive message | ER-1 through ER-7, ER-20 through ER-23 |
| AC-7 | Unknown keys rejected with 400 | ER-8, ER-9, HI-5 |
| AC-8 | Both endpoints require authentication (401) | ER-10, ER-11, ER-12, ER-13 |
| AC-9 | Users can only access own preferences (403) | ER-14, ER-15 |
| AC-10 | Persisted to PostgreSQL | Manual step 2, T3 acceptance criteria |
| AC-11 | Standard {data, meta} envelope | HP-12, HP-13, HI-8 |
| AC-12 | OpenAPI spec documented | Manual step 1 |
| AC-13 | Domain layer validates independently of HTTP | DV-1 through DV-8 |
| AC-14 | Hexagonal architecture followed | Manual step 6, code review |
| AC-15 | Unit tests cover service layer | SV-1 through SV-6 |
| AC-16 | Integration tests cover handler layer | HI-1 through HI-8 |

## Summary

| Category | Count |
|----------|-------|
| Happy Path | 13 |
| Edge Cases | 7 |
| Error Cases | 23 |
| Domain Validation Unit Tests | 8 |
| Service Layer Unit Tests | 6 |
| Handler Integration Tests | 8 |
| Manual Verification Steps | 6 |
| **Total Scenarios** | **71** |

All 16 acceptance criteria have corresponding test coverage. No acceptance criterion is left untested.