learning_ai_common_plat/AI.dev/SKILLS/test-desktop-app.md

Test Desktop App Skill

Description: Run and test desktop applications locally during development.

When to Use

• Developing new desktop features
• Verifying fixes before release
• Manual testing workflows
• Debugging desktop-specific issues

Prerequisites

Environment Setup

• Backend services running (if applicable)
• Python 3.12+ with virtual environment
• Required platform-specific dependencies
• Configuration files with necessary secrets

LysnrAI Desktop Specific

# Backend must be running
./run-local-all-services.sh start

# Verify backend health
curl http://127.0.0.1:8000/health

# Azure credentials required
ls ~/.lysnrai/.env  # Must contain AZURE_SPEECH_KEY, AZURE_OPENAI_KEY, etc.

Testing Workflow

1. Prepare Environment

# Activate virtual environment
source .venv/bin/activate

# Or create if doesn't exist
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. Verify Configuration

# Check environment file
ls ~/.lysnrai/.env || echo "Missing env file"

# Verify required variables
grep -E "AZURE_SPEECH_KEY|AZURE_OPENAI_KEY" ~/.lysnrai/.env

3. Launch Application

# Python desktop app
python3 -m src.main

# Or with specific module
python src/main.py

# For Electron apps
npm run dev

# For Qt apps
python main.py

4. Test Core Functionality

Create a test checklist:

Basic Functionality

• Application window opens correctly
• Menu bar/toolbar appears
• App icon shows in dock/taskbar
• Window can be resized and moved

Authentication

• Login/registration flow works
• License key activation (if applicable)
• Session persistence
• Logout functionality

Core Features

• Main feature works (e.g., dictation, recording)
• Settings panel opens and saves
• File operations (save/load)
• Keyboard shortcuts work

Platform Integration

• Menu bar integration (macOS)
• System tray icon (Windows/Linux)
• Global hotkeys
• Notifications

5. Platform-Specific Testing

macOS

# Test menu bar integration
# Verify Fn/Globe key works (if applicable)
# Check sandboxing permissions
# Test Notarization (if signed)

# macOS specific checks
spctl -a -v /Applications/YourApp.app
codesign -dv --verbose=4 /Applications/YourApp.app

Windows

# Test Windows integration
# Check registry entries
# Verify installer works
# Test auto-startup

# Windows specific checks
signtool verify /pa YourApp.exe

Linux

# Test Linux integration
# Verify desktop entry
# Check file associations
# Test package installation

# Linux specific checks
desktop-file-validate yourapp.desktop

Debugging Desktop Apps

Logging Setup

# Python logging example
import structlog

logger = structlog.get_logger()

# In main()
logger.info("Application starting", version="1.0.0")
logger.error("Failed to connect", service="backend", error=str(e))

Common Issues

1. Application won't start

   # Check Python version
   python --version
   
   # Check dependencies
   pip list
   
   # Run with verbose output
   python -v src/main.py
   

2. Backend connection issues

   # Verify backend is running
   curl http://localhost:8000/health
   
   # Check network configuration
   netstat -an | grep 8000
   

3. Permission issues

   # macOS: check sandboxing
   spctl -a -v YourApp.app
   
   # Check file permissions
   ls -la ~/.lysnrai/
   

Debug Mode

# Add debug flag
import argparse

parser = argparse.ArgumentParser()
parser.add_argument('--debug', action='store_true')
args = parser.parse_args()

if args.debug:
    logging.basicConfig(level=logging.DEBUG)

Test Data Management

Sample Data Setup

# Create test data directory
os.makedirs(os.path.expanduser('~/.lysnrai/test_data'), exist_ok=True)

# Sample configuration
test_config = {
    "user_id": "test-user-123",
    "license_key": "LYSNR-TEST-1234-5678",
    "theme": "dark"
}

Reset Test Environment

# Clear test data
rm -rf ~/.lysnrai/test_data

# Reset settings
rm ~/.lysnrai/settings.json

# Clear logs
> ~/.lysnrai/app.log

Automated Testing

Unit Tests for Desktop

# tests/test_desktop.py
import pytest
from src.main import DesktopApp

class TestDesktopApp:
    def test_app_initialization(self):
        app = DesktopApp()
        assert app.is_initialized

    def test_settings_load(self):
        app = DesktopApp()
        settings = app.load_settings()
        assert 'theme' in settings

    def test_backend_connection(self):
        app = DesktopApp()
        assert app.check_backend_health()

UI Automation (Python)

# Using PyAutoGUI for UI testing
import pyautogui

def test_main_window():
    # Find and click menu
    pyautogui.click('File', duration=0.25)
    pyautogui.click('New', duration=0.25)

    # Verify new window
    assert pyautogui.locateOnScreen('new_window.png')

Performance Testing

Memory Usage

# Monitor memory usage
top -pid $(pgrep -f "python.*main.py")

# Or with psutil
python -c "
import psutil
import time
while True:
    p = psutil.Process()
    print(f'Memory: {p.memory_info().rss / 1024 / 1024:.2f} MB')
    time.sleep(1)
"

Startup Time

import time
import subprocess

start = time.time()
subprocess.run(['python', 'src/main.py'])
startup_time = time.time() - start
print(f"Startup time: {startup_time:.2f}s")

Test Documentation

Test Report Template

# Desktop Test Report

## Environment

- OS: macOS 14.0
- Python: 3.12.0
- App Version: 1.0.0

## Test Results

| Feature   | Status | Notes                        |
| --------- | ------ | ---------------------------- |
| Launch    | ✅     | Starts in 2.3s               |
| Login     | ✅     | Works with test account      |
| Recording | ❌     | Fails without mic permission |
| Settings  | ✅     | Saves correctly              |

## Issues Found

1. Microphone permission not requested on first launch
2. High memory usage (~200MB idle)

## Recommendations

1. Add permission request on startup
2. Investigate memory leak

CI/CD Integration

GitHub Actions for Desktop Tests

name: Test Desktop App

on: [push, pull_request]

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v4
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          pip install pytest          

      - name: Run unit tests
        run: pytest tests/test_desktop.py

      - name: Test app launch
        run: |
          timeout 10s python -m src.main || true
          # Check if process started
          pgrep -f "python.*main.py" && echo "App started successfully"          

Best Practices

Testing Strategy

1. Test early, test often - Run tests after each change
2. Automate repetitive tests - Use scripts for common workflows
3. Test on target platforms - Don't rely on cross-platform behavior
4. Document test cases - Keep track of what needs testing

Test Environment

1. Isolate test data - Use separate directory for tests
2. Clean state - Reset between test runs
3. Mock external services - Don't depend on real APIs
4. Version control test data - Commit test fixtures

Notes

• Platform differences matter - Test on all target platforms
• Permissions are critical - Especially on macOS and Windows
• User interaction varies - Consider different user workflows
• Performance matters - Monitor startup time and memory usage

Related Skills

• Desktop Release - After testing
• Debug Service - When tests fail
• Production Readiness - Pre-release testing
• Security Auditing - Security testing