# Phase 7 - Frontend UI Test Plan (Spec 038)

## Overview
This document provides manual test scenarios for Phase 7 (Frontend UI) of the Deterministic Scheduling Solver implementation (Spec 038).

## Test Environment Setup
- Browser: Chrome/Firefox/Safari latest
- User: Account with `uri_schedule_ai` permission
- Store: Test store with sample data
- Python: Ensure Python 3.9+ and OR-Tools installed for Math Optimizer tests

---

## T7.2.1: Solver Type Selector Visibility

### Scenario A: Python Available
**Precondition:** Python 3.9+ and OR-Tools installed on server

1. Navigate to schedule calendar page
2. Click "Generate with AI" button
3. **Verify:** Config modal opens
4. **Verify:** Two solver options are visible:
   - ☑ Math Optimizer (with calculator icon)
   - ☑ AI Scheduler (with robot icon)
5. **Verify:** Each option has descriptive text about strengths

**Expected Result:** Both solver options visible and selectable

### Scenario B: Python Unavailable
**Precondition:** Python not installed OR OR-Tools not available

1. Navigate to schedule calendar page
2. Click "Generate with AI" button
3. **Verify:** Config modal opens
4. **Verify:** Only AI Scheduler option is visible
5. **Verify:** Math Optimizer option is hidden

**Expected Result:** Math Optimizer hidden when Python unavailable

---

## T7.2.2: Last Used Solver Type Pre-selection

### Scenario A: First Time User (No Preference)
1. Open config modal
2. **Verify:** AI Scheduler is selected by default
3. **Verify:** Custom instructions field is visible

**Expected Result:** AI selected as default for new users

### Scenario B: Last Used Math Optimizer
**Precondition:** User's last generation used Math Optimizer

1. Open config modal
2. **Verify:** Math Optimizer radio is pre-selected
3. **Verify:** Custom instructions field is hidden

**Expected Result:** Math Optimizer pre-selected based on last use

### Scenario C: Last Used AI Scheduler
**Precondition:** User's last generation used AI Scheduler

1. Open config modal
2. **Verify:** AI Scheduler radio is pre-selected
3. **Verify:** Custom instructions field is visible

**Expected Result:** AI Scheduler pre-selected based on last use

---

## T7.2.3: Custom Instructions Toggle

### Test Case: Switching Between Solver Types

1. Open config modal
2. Select "Math Optimizer"
3. **Verify:** Custom instructions textarea disappears
4. Select "AI Scheduler"
5. **Verify:** Custom instructions textarea appears
6. Enter text in custom instructions: "Test instruction"
7. Switch to "Math Optimizer"
8. **Verify:** Custom instructions hidden (text preserved in memory)
9. Switch back to "AI Scheduler"
10. **Verify:** Previously entered text "Test instruction" is still there

**Expected Result:** Custom instructions toggle correctly without data loss

---

## T7.2.4: Usage Display for Math Optimizer

### Test Case: Usage Counter Changes

1. Open config modal
2. Note current usage count (e.g., "2 / 5 runs this period")
3. Select "Math Optimizer"
4. **Verify:** Usage display changes to "∞ / ∞ unlimited runs"
5. Select "AI Scheduler"
6. **Verify:** Usage display reverts to "2 / 5 runs this period"

**Expected Result:** Usage shows unlimited for Math, actual count for AI

---

## T7.2.5: Solver Type in Generation Payload

### Test Case: Payload Includes Solver Type

**Note:** This requires browser DevTools Network tab inspection

1. Open config modal
2. Select "Math Optimizer"
3. Click "Generate Schedule"
4. Open DevTools Network tab
5. Find POST request to `/api/:typeNum/schedule/ai/generate`
6. Inspect request payload
7. **Verify:** `"solverType": "math"` is present in JSON payload

8. Repeat with AI Scheduler selected
9. **Verify:** `"solverType": "ai"` is present in JSON payload

**Expected Result:** Correct solverType included in generation request

---

## T7.2.6: Scorecard Rendering (Math Optimizer Only)

### Scenario A: Math Optimizer Schedule
**Precondition:** Generate schedule using Math Optimizer

1. Wait for generation to complete
2. Preview modal opens automatically
3. **Verify:** "Schedule Quality Metrics" section is visible
4. **Verify:** Scorecard contains 5 metrics:
   - Labor Cost (green, format: $X.XX)
   - Fairness (color-coded: High=green, Medium=amber, Low=red)
   - Coverage (blue, format: X%)
   - Overtime (orange, format: X.Xh)
   - Solution (format: "Optimal" or "Near-optimal (X% gap)")
5. **Verify:** All values are reasonable numbers (not 0 or NaN)

**Expected Result:** Scorecard displays with correct formatting and colors

### Scenario B: AI Scheduler Schedule
**Precondition:** Generate schedule using AI Scheduler

1. Wait for generation to complete
2. Preview modal opens
3. **Verify:** "Schedule Quality Metrics" section is HIDDEN
4. **Verify:** No scorecard is displayed

**Expected Result:** Scorecard only shown for Math Optimizer

---

## T7.2.7: Assignment Explanations

### Scenario A: Math Optimizer with LLM Available
**Precondition:** OpenAI key configured, Math schedule generated

1. Open preview modal
2. Navigate to day with assignments
3. Click "Why this assignment?" on any assignment
4. **Verify:** Explanation expands showing LLM-generated text
5. **Verify:** Text is natural language (e.g., "Sarah is assigned because...")
6. **Verify:** No banner about LLM unavailability

**Expected Result:** Rich LLM explanations displayed

### Scenario B: Math Optimizer with LLM Unavailable
**Precondition:** OpenAI key NOT configured OR disabled

1. Generate Math schedule
2. Open preview modal
3. **Verify:** Banner appears: "AI explanations unavailable — Explanations generated from constraint data"
4. Click "Why this assignment?" on any assignment
5. **Verify:** Explanation expands with structured fallback text
6. **Verify:** Text is technical but informative (e.g., "Qualified: Yes, Available: Yes...")

**Expected Result:** Fallback explanations shown with banner

### Scenario C: AI Scheduler
**Precondition:** AI schedule generated

1. Open preview modal
2. **Verify:** No LLM unavailable banner
3. Click "Why this assignment?" on any assignment
4. **Verify:** Explanation is AI-generated reasoning text

**Expected Result:** AI reasoning displayed (existing behavior)

---

## T7.2.8: Improvement Suggestions Panel

### Scenario A: Math Optimizer with LLM Available
**Precondition:** OpenAI configured, Math schedule generated

1. Open preview modal
2. **Verify:** "Improvement Suggestions" section is visible
3. **Verify:** Badge shows count (e.g., "3 suggestions")
4. Click to expand suggestions
5. **Verify:** Suggestions are displayed with:
   - Icon (🔥 for immediate, 📅 for long-term)
   - Action text (bold)
   - Impact description
   - Trade-off description (if applicable)
6. **Verify:** Suggestions are actionable and specific

**Expected Result:** Rich improvement suggestions displayed

### Scenario B: Math Optimizer with LLM Unavailable
**Precondition:** OpenAI NOT configured

1. Generate Math schedule
2. Open preview modal
3. **Verify:** "Improvement Suggestions" section is HIDDEN
4. **Verify:** LLM unavailable banner IS visible

**Expected Result:** Suggestions hidden when LLM unavailable

### Scenario C: AI Scheduler
**Precondition:** AI schedule generated

1. Open preview modal
2. **Verify:** "Improvement Suggestions" section is hidden (AI doesn't use this)

**Expected Result:** Suggestions only for Math Optimizer

---

## T7.2.9: LLM Unavailable Banner Visibility

### Test Matrix

| Solver Type   | LLM Available | Banner Visible? | Suggestions Visible? |
|---------------|---------------|-----------------|----------------------|
| Math Optimizer| Yes           | No              | Yes                  |
| Math Optimizer| No            | Yes             | No                   |
| AI Scheduler  | Yes           | No              | No (not applicable)  |
| AI Scheduler  | No            | No              | No (not applicable)  |

**Test each combination above and verify banner/suggestion visibility**

---

## T7.2.10: Ably Solver Channel Subscription

### Test Case: Real-time Updates for Solver Jobs

**Note:** Requires Ably configured and browser console open

1. Open browser console
2. Open config modal
3. Select "Math Optimizer"
4. Click "Generate Schedule"
5. **Verify console log:** "Subscribed to channel: solver-schedule-{typeNum}-{jobId}"
6. Wait for completion
7. **Verify:** Preview modal opens automatically when job completes
8. **Verify console log:** Job complete event received

**Expected Result:** Solver jobs use dedicated Ably channels

---

## T7.2.11: Improvement Suggestions Refresh on Accept/Reject

### Test Case: Dynamic Suggestion Updates

**Precondition:** Math Optimizer schedule with LLM available, suggestions visible

1. Open preview modal
2. Expand improvement suggestions
3. Note current suggestions
4. Select some assignments (check 2-3 boxes)
5. Click "Apply Selected"
6. **Verify:** POST request sent to `/api/:typeNum/schedule/solver/refresh-suggestions`
7. **Verify:** Request payload includes:
   - `suggestionId`
   - `acceptedShiftIds: [array of accepted IDs]`
   - `rejectedShiftIds: [array of rejected IDs]`
8. **Verify:** Suggestions panel updates with new/adjusted suggestions

**Expected Result:** Suggestions refresh based on user actions

---

## Edge Cases & Error Handling

### E1: Python Health Check Fails
1. Stop Python service mid-session
2. Try opening config modal
3. **Verify:** Math Optimizer option becomes hidden
4. **Verify:** No JavaScript errors in console

### E2: Solver Generation Fails
1. Trigger solver failure (invalid constraints)
2. **Verify:** Error toast displayed
3. **Verify:** Preview modal does not open
4. **Verify:** No scorecard or suggestions attempted

### E3: Missing Scorecard Data
1. Mock response with `solverType: 'math'` but `scorecard: null`
2. **Verify:** Scorecard section is hidden gracefully
3. **Verify:** No JavaScript errors

### E4: Malformed Improvement Suggestions
1. Mock response with malformed suggestions array
2. **Verify:** Panel is hidden gracefully
3. **Verify:** No JavaScript errors

---

## Browser Compatibility

Test the following scenarios in each browser:

- ✅ Chrome (latest)
- ✅ Firefox (latest)
- ✅ Safari (latest)
- ✅ Edge (latest)

**Key areas:**
- Solver card styling
- Scorecard grid layout
- Improvement suggestions icons
- Collapsible sections (chevron animation)

---

## Accessibility (WCAG 2.1)

### Keyboard Navigation
1. Tab through config modal
2. **Verify:** Solver radio buttons are focusable
3. **Verify:** Can toggle with Space key
4. Tab through preview modal
5. **Verify:** Suggestion expand buttons are focusable

### Screen Reader
1. Use VoiceOver (Mac) or NVDA (Windows)
2. **Verify:** Solver options are announced correctly
3. **Verify:** Scorecard metrics have readable labels
4. **Verify:** Improvement suggestions are navigable

---

## Performance

### P1: Initial Load
- Config modal should open < 500ms
- Health check should not block modal open

### P2: Preview Rendering
- Scorecard should render instantly (< 100ms)
- Suggestions should render < 200ms
- No visible lag when expanding sections

---

## Regression Tests

Ensure existing functionality still works:

1. **AI Scheduler generation** (original flow)
2. **Custom instructions** (save and reload)
3. **Owner toggles** (include/exclude)
4. **Pending job cancellation**
5. **Stale shift warnings**
6. **Hours distribution table**
7. **Apply/Dismiss actions**

---

## Sign-off Checklist

- [ ] All test scenarios pass (T7.2.1 - T7.2.11)
- [ ] Edge cases handled gracefully
- [ ] Browser compatibility verified
- [ ] Accessibility requirements met
- [ ] Performance targets achieved
- [ ] No regressions in existing features
- [ ] Console free of errors/warnings
- [ ] Network requests correct (DevTools verified)

---

## Notes for QA

- **OpenAI Key:** To test LLM features, ensure `OPENAI_API_KEY` is set in environment
- **Python Setup:** Install Python 3.9+ and `pip install ortools` for Math Optimizer
- **Ably:** Check `ABLY_KEY` is configured for real-time update tests
- **Test Data:** Use store `pc00` with sample employees and shifts

---

## Test Execution Log

| Date | Tester | Browser | Status | Issues Found |
|------|--------|---------|--------|--------------|
|      |        |         |        |              |
|      |        |         |        |              |
|      |        |         |        |              |