acesesibiliti
This commit is contained in:
432
docs/guides/SCREEN_READER_TESTING.md
Normal file
432
docs/guides/SCREEN_READER_TESTING.md
Normal file
@@ -0,0 +1,432 @@
|
||||
# 🔊 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
|
||||
Reference in New Issue
Block a user