voculinux/tests/distro-testing-checklist.md

Distribution Testing Checklist

Use this checklist when testing Vocalinux on a new Linux distribution.

Pre-Installation

System Information

• Record distribution name and version

  cat /etc/os-release
  

• Record desktop environment

  echo $XDG_CURRENT_DESKTOP
  

• Record display server

  echo $XDG_SESSION_TYPE
  echo $WAYLAND_DISPLAY  # For Wayland
  echo $DISPLAY          # For X11
  

• Record architecture

  uname -m
  

• Run the dependency checker

  bash scripts/check-system-deps.sh
  

• Note missing packages

• Note any special requirements (musl libc, specific library versions, etc.)

Installation

Standard Installation

• Download installer

  curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh -o /tmp/vl.sh
  

• Run installer

  bash /tmp/vl.sh
  

• Check for errors during installation

• Verify virtual environment was created

  ls -la ~/.local/share/vocalinux/venv/
  

• Check wrapper scripts exist

  ls -la ~/.local/bin/vocalinux*
  

• Check desktop entry was created

  ls -la ~/.local/share/applications/vocalinux.desktop
  

• Check icons were installed

  ls -la ~/.local/share/icons/hicolor/scalable/apps/vocalinux*
  

Post-Installation

Launch from Terminal

• Launch from terminal

  ~/.local/bin/vocalinux-gui
  

• Check for startup errors

• Verify the application starts

• Check that tray icon appears

• Verify keyboard shortcut works (Hold Right Alt by default)

Launch from Application Menu

• Launch from desktop environment's application menu
• Verify the application starts
• Check that tray icon appears

Core Functionality Tests

Tray Icon and Menu

• Left-click tray icon opens menu
• Right-click tray icon opens settings menu
• "Start Recording" menu item works
• "Stop Recording" menu item works
• "Settings" menu item opens settings dialog
• "Quit" menu item exits the application

Keyboard Shortcuts

• Default shortcut (Hold Right Alt) starts push-to-talk recording
• Custom shortcuts can be configured in Settings
• Shortcut works in different applications (terminal, text editor, browser)

Audio Recording

• Recording starts without errors

• Default audio device is detected

  # Check audio devices
  pactl list sources short  # PulseAudio
  # or
  arecord -l                 # ALSA
  

• Audio levels are adequate

• Start sound plays (ascending tone)

• Stop sound plays (descending tone)

Speech Recognition

• Speech is transcribed accurately
• Transcription appears in target application
• Punctuation works
• Capitalization works
• No backslash escapes in output (no \', \", etc.)

Text Injection

X11 (if applicable)

• Text injection works with xdotool
• Works in different applications:
  • Terminal (gnome-terminal, konsole, etc.)
  • Text editor (gedit, kate, mousepad, etc.)
  • Browser (Firefox, Chromium, etc.)
  • LibreOffice Writer
  • Chat applications (Discord, Telegram, etc.)

Wayland (if applicable)

• Text injection works with wtype
• Works in Wayland-native applications
• XWayland fallback works if needed
• Works in same applications as X11 test list

Universal (ydotool if available)

• Text injection works with ydotool
• Works across both X11 and Wayland

Settings Dialog

• Settings dialog opens from tray menu
• Can configure audio input device
• Can configure keyboard shortcuts
• Can enable/disable sounds
• Can configure recognition engine (VOSK/Whisper)
• Can configure language
• Settings persist after restart
• Config file is created correctly

  cat ~/.config/vocalinux/config.json
  

Model Download (if using Whisper)

• Model download works
• Download progress is shown
• Model is saved to correct location

  ls -la ~/.local/share/vocalinux/models/
  

Error Handling

• Graceful handling when no microphone is available
• Graceful handling when text injection fails
• Error messages are helpful
• Application doesn't crash on errors

Performance

• Application starts within reasonable time (< 5 seconds)

• Recording starts/stops responsively

• Transcription appears without significant lag

• Memory usage is reasonable

  # Check memory usage
  ps aux | grep vocalinux
  

• CPU usage is reasonable during idle

• CPU usage is reasonable during recording

Cleanup and Uninstallation

• Application can be quit cleanly

• No processes left running

  ps aux | grep vocalinux
  

• Uninstallation works

  bash ~/.local/share/vocalinux/uninstall.sh  # if exists
  # or manual cleanup
  rm -rf ~/.local/share/vocalinux
  rm -rf ~/.config/vocalinux
  rm ~/.local/share/applications/vocalinux.desktop
  rm ~/.local/bin/vocalinux*
  

Known Issues

Record any issues found during testing:

Distribution-Specific Issues

Issue	Severity	Workaround	Notes

Desktop Environment Issues

DE	Issue	Severity	Workaround	Notes
GNOME
KDE Plasma
Xfce
sway
i3

Application-Specific Issues

Application	Issue	Severity	Workaround	Notes
Firefox
Chromium
LibreOffice
Terminal

Sign-Off

Tester: ____________________

Date: ____________________

Distribution: ____________________ ____________________

Desktop Environment: ____________________

Display Server: ____________________

Overall Status: ☐ Pass / ☐ Pass with Issues / ☐ Fail

Additional Comments:

---

Submitting Results

After completing the checklist:

1. Create a GitHub issue with the title: Distro Test Results: [Distribution Name] [Version]

2. Include the checklist (either filled out or as a summary)

3. Attach logs if there were errors:

   • Installer output
   • Application output from terminal
   • Journal logs: journalctl --user -u vocalinux -b

4. Mention any workarounds you found

5. Suggest improvements to the documentation or installer

Testing Tips

1. Test early, test often - Don't wait until everything is installed to test
2. Keep notes - Document everything, even things that seem minor
3. Be thorough - Test with multiple applications if possible
4. Be patient - Some distributions may require workarounds
5. Share your findings - Even negative results are valuable

Quick Reference Commands

# Check distribution
cat /etc/os-release

# Check desktop environment
echo $XDG_CURRENT_DESKTOP

# Check display server
echo $XDG_SESSION_TYPE

# Check audio devices
pactl list sources short  # PulseAudio
arecord -l                 # ALSA

# Check for running processes
ps aux | grep vocalinux

# Check memory usage
ps aux | grep vocalinux | awk '{print $6}'

# Check logs
journalctl --user -b | grep vocalinux

# Run dependency checker
bash scripts/check-system-deps.sh

# Test installation
bash -n install.sh

# Verify installation
ls -la ~/.local/bin/vocalinux*
ls -la ~/.local/share/vocalinux/
ls -la ~/.config/vocalinux/