# 🔊 Screen Reader System Testing Guide

## 📋 Overview
Complete screen reader support for blind and visually impaired players with:
- ✅ Speech synthesis (text-to-speech)
- ✅ ARIA live regions
- ✅ Audio cues (beeps/tones)
- ✅ Keyboard navigation
- ✅ Context announcements
- ✅ Verbose mode

---

## 🎯 Features to Test

### 1. **Speech Synthesis**

#### Test Cases:
- [ ] System announces "Screen reader system ready" on startup
- [ ] Speech rate can be adjusted (0.1 - 10)
- [ ] Speech pitch can be adjusted (0 - 2)
- [ ] Speech volume can be adjusted (0 - 1)
- [ ] Multiple voices are available
- [ ] Voice can be changed
- [ ] Speech can be interrupted
- [ ] Speech can be stopped

#### How to Test:
```javascript
// In browser console (F12):
const sr = game.scene.scenes[1].screenReader;

// Test basic speech
sr.speak('Hello, this is a test.');

// Test with priority
sr.speak('This is an alert!', 'alert', true);

// Adjust settings
sr.setRate(1.5); // Faster
sr.setRate(0.5); // Slower
sr.setPitch(1.5); // Higher pitch
sr.setPitch(0.5); // Lower pitch
sr.setVolume(0.5); // 50% volume

// List available voices
console.log(sr.getAvailableVoices());

// Change voice
sr.setVoice('Microsoft David Desktop'); // Windows
sr.setVoice('Alex'); // macOS

// Stop speech
sr.stop();
```

---

### 2. **Keyboard Navigation**

#### Keyboard Shortcuts:
- **Ctrl+H**: Help (lists all commands)
- **Ctrl+R**: Repeat last announcement
- **Ctrl+S**: Announce settings
- **Ctrl+P**: Announce position
- **Ctrl+I**: Announce inventory
- **Ctrl+N**: Announce nearby objects
- **Ctrl+T**: Announce stats (health, hunger, stamina)
- **Ctrl+V**: Toggle verbose mode

#### Test Cases:
- [ ] All keyboard shortcuts work
- [ ] Help command lists all shortcuts
- [ ] Repeat command replays last announcement
- [ ] Settings command announces current settings
- [ ] Position command announces X, Y coordinates
- [ ] Inventory command lists items
- [ ] Nearby command describes surroundings
- [ ] Stats command announces health/hunger/stamina

#### How to Test:
1. Start the game
2. Press **Ctrl+H** to hear help
3. Press **Ctrl+P** to hear position
4. Press **Ctrl+I** to hear inventory
5. Press **Ctrl+T** to hear stats
6. Press **Ctrl+N** to hear nearby objects
7. Press **Ctrl+R** to repeat last announcement
8. Press **Ctrl+V** to toggle verbose mode

---

### 3. **Audio Cues**

#### Available Cues:
- **Focus**: 440 Hz, 100ms (UI element focused)
- **Select**: 880 Hz, 150ms (Item selected)
- **Error**: 220 Hz, 300ms (Error occurred)
- **Success**: 660 Hz, 200ms (Action successful)
- **Navigation**: 550 Hz, 80ms (Menu navigation)
- **Inventory**: 750 Hz, 120ms (Inventory opened)
- **Damage**: 200 Hz, 250ms (Player took damage)
- **Pickup**: 1000 Hz, 100ms (Item picked up)

#### Test Cases:
- [ ] Audio cues play for different actions
- [ ] Cues can be toggled on/off
- [ ] Cue frequencies are distinct
- [ ] Cues don't overlap speech

#### How to Test:
```javascript
const sr = game.scene.scenes[1].screenReader;

// Test different audio cues
sr.playAudioCue('focus');
sr.playAudioCue('select');
sr.playAudioCue('error');
sr.playAudioCue('success');
sr.playAudioCue('navigation');
sr.playAudioCue('inventory');
sr.playAudioCue('damage');
sr.playAudioCue('pickup');

// Toggle sound cues
sr.toggleSoundCues(); // Off
sr.toggleSoundCues(); // On
```

---

### 4. **Context Announcements**

#### Available Contexts:
- **menu**: Main menu
- **game**: In game
- **inventory**: Inventory screen
- **crafting**: Crafting menu
- **dialogue**: Dialogue
- **combat**: In combat
- **building**: Build mode
- **map**: Map view

#### Test Cases:
- [ ] Context is announced when entering new area
- [ ] Context includes navigation instructions
- [ ] Context can be manually triggered

#### How to Test:
```javascript
const sr = game.scene.scenes[1].screenReader;

// Announce different contexts
sr.announceContext('menu');
sr.announceContext('game');
sr.announceContext('inventory');
sr.announceContext('crafting');
sr.announceContext('dialogue');
sr.announceContext('combat');
sr.announceContext('building');
sr.announceContext('map');
```

---

### 5. **Action Announcements**

#### Supported Actions:
- move, attack, interact, pickup, drop
- craft, build, harvest, plant, dig
- damage, heal, die, respawn

#### Test Cases:
- [ ] Actions are announced when performed
- [ ] Action details are included (if provided)
- [ ] Audio cue plays with announcement

#### How to Test:
```javascript
const sr = game.scene.scenes[1].screenReader;

// Test action announcements
sr.announceAction('move');
sr.announceAction('attack', 'zombie');
sr.announceAction('pickup', 'carrot');
sr.announceAction('craft', 'wooden sword');
sr.announceAction('build', 'fence');
sr.announceAction('harvest', 'wheat');
sr.announceAction('damage', '10 health');
sr.announceAction('heal', '25 health');
```

---

### 6. **Game State Announcements**

#### Test Cases:
- [ ] Stats announcement includes health, hunger, stamina
- [ ] Inventory announcement lists items and gold
- [ ] Position announcement includes X, Y coordinates
- [ ] Nearby announcement describes surroundings
- [ ] Verbose mode provides detailed information

#### How to Test:
```javascript
const sr = game.scene.scenes[1].screenReader;

// Announce game state
sr.announceStats();
sr.announceInventory();
sr.announcePosition();
sr.announceNearby();

// Toggle verbose mode for detailed info
sr.toggleVerboseMode(); // On
sr.announceInventory(); // Detailed item list
sr.toggleVerboseMode(); // Off
```

---

### 7. **ARIA Live Regions**

#### Test Cases:
- [ ] Polite region exists (non-interrupting)
- [ ] Alert region exists (interrupting)
- [ ] Regions are hidden from visual display
- [ ] Screen readers detect region updates

#### How to Test:
1. Open browser DevTools (F12)
2. Inspect DOM for ARIA live regions
3. Verify `role="status"` and `aria-live="polite"`
4. Verify `role="alert"` and `aria-live="assertive"`
5. Test with actual screen reader (NVDA, JAWS, VoiceOver)

---

### 8. **Auto-Narration**

#### Test Cases:
- [ ] Low health warning is announced automatically
- [ ] UI changes are announced (if enabled)
- [ ] Notifications are announced
- [ ] Auto-narration can be toggled

#### How to Test:
```javascript
const sr = game.scene.scenes[1].screenReader;

// Toggle auto-narration
sr.toggleAutoNarrate(); // Off
sr.toggleAutoNarrate(); // On

// Test notifications
sr.announceNotification('You found a treasure!');
sr.announceNotification('Error: Cannot craft item', 'alert');

// Test UI announcements
sr.announceUI('Inventory', 'opened');
sr.announceUI('Crafting menu', 'closed');
```

---

### 9. **Settings Persistence**

#### Test Cases:
- [ ] Settings are saved to localStorage
- [ ] Settings persist after page reload
- [ ] All settings are saved (rate, pitch, volume, etc.)

#### How to Test:
```javascript
const sr = game.scene.scenes[1].screenReader;

// Change settings
sr.setRate(1.5);
sr.setPitch(1.2);
sr.setVolume(0.8);
sr.toggleVerboseMode();
sr.toggleSoundCues();

// Reload page (F5)
// Settings should be restored

// Verify settings
sr.announceSettings();
```

---

### 10. **Screen Reader Compatibility**

#### Supported Screen Readers:
- **NVDA** (Windows) - Free
- **JAWS** (Windows) - Commercial
- **VoiceOver** (macOS/iOS) - Built-in
- **TalkBack** (Android) - Built-in
- **ChromeVox** (Chrome OS) - Built-in

#### Test Cases:
- [ ] Works with NVDA
- [ ] Works with JAWS
- [ ] Works with VoiceOver
- [ ] ARIA regions are detected
- [ ] Keyboard navigation works

#### How to Test:
1. Install/Enable screen reader
2. Start NovaFarma
3. Navigate using keyboard only
4. Verify announcements are heard
5. Test all keyboard shortcuts
6. Test ARIA live regions

---

## 🎮 Integration Testing

### Complete Workflow Test:
```javascript
const sr = game.scene.scenes[1].screenReader;

// 1. Help
sr.announceHelp();

// 2. Check stats
sr.announceStats();

// 3. Check inventory
sr.announceInventory();

// 4. Check position
sr.announcePosition();

// 5. Check nearby
sr.announceNearby();

// 6. Perform action
sr.announceAction('move', 'north');
sr.announceAction('pickup', 'wood');

// 7. Change context
sr.announceContext('inventory');

// 8. Adjust settings
sr.setRate(1.2);
sr.setPitch(1.0);
sr.setVolume(0.9);

// 9. Toggle features
sr.toggleVerboseMode();
sr.toggleSoundCues();
sr.toggleAutoNarrate();

// 10. Verify settings
sr.announceSettings();
```

---

## 📊 Expected Results

### ✅ Success Criteria:
1. Speech synthesis works on all platforms
2. All keyboard shortcuts function correctly
3. Audio cues are distinct and helpful
4. Context announcements provide clear guidance
5. Action announcements are timely and accurate
6. Game state announcements are comprehensive
7. ARIA live regions work with screen readers
8. Auto-narration detects important events
9. Settings persist after reload
10. Compatible with major screen readers

### ❌ Known Issues:
- Speech synthesis voices vary by platform
- Some browsers may require user interaction before speech
- Audio cues may not work in all browsers

---

## 🐛 Bug Reporting

If you find any issues, please report:
1. **What you were testing**
2. **What you expected to happen**
3. **What actually happened**
4. **Browser and OS**
5. **Screen reader (if applicable)**
6. **Console errors** (if any)

---

## 📝 Quick Reference

### Keyboard Shortcuts:
| Shortcut | Action |
|----------|--------|
| Ctrl+H | Help |
| Ctrl+R | Repeat |
| Ctrl+S | Settings |
| Ctrl+P | Position |
| Ctrl+I | Inventory |
| Ctrl+N | Nearby |
| Ctrl+T | Stats |
| Ctrl+V | Verbose Mode |

### API Commands:
```javascript
const sr = game.scene.scenes[1].screenReader;

sr.speak(text, priority, interrupt);
sr.announceStats();
sr.announceInventory();
sr.announcePosition();
sr.announceNearby();
sr.announceAction(action, details);
sr.setRate(rate);
sr.setPitch(pitch);
sr.setVolume(volume);
sr.toggleVerboseMode();
sr.toggleSoundCues();
sr.toggleAutoNarrate();
```

---

**Last Updated**: 2025-12-12  
**Version**: 2.5.0  
**Status**: ✅ Ready for Testing