novafarma/docs/guides/SCREEN_READER_TESTING.md

🔊 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:

// 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:

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:

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:

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:

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:

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:

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:

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:

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