# Testing Guide

This document provides comprehensive testing procedures, checklists, and best practices for the MPV.Rocks Installer project.

## Table of Contents

- [Testing Strategy](#testing-strategy)
- [Unit Testing](#unit-testing)
- [Integration Testing](#integration-testing)
- [Manual Testing](#manual-testing)
- [Platform-Specific Testing](#platform-specific-testing)
- [Test Coverage](#test-coverage)
- [CI/CD](#cicd)

---

## Testing Strategy

### Test Pyramid

```
           /\
          /  \
         / E2E \     - End-to-end user scenarios
        /--------\
       /Integration\   - Package interactions and workflows
      /------------\
     /   Unit      \  - Individual function testing
    /----------------\
```

### Testing Levels

1. **Unit Tests:** Test individual functions in isolation
2. **Integration Tests:** Test package interactions
3. **Manual Tests:** User acceptance and exploratory testing
4. **Platform Tests:** Verify behavior on each supported platform

### Test Coverage Target

- **Minimum:** 80% code coverage
- **Target:** 90% code coverage
- **Critical Path:** 100% coverage (installation, configuration, updates)

---

## Unit Testing

### Running Unit Tests

```bash
# Run all tests
go test ./...

# Run tests with verbose output
go test -v ./...

# Run tests with coverage
go test -cover ./...

# Run tests with coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
```

### Test File Organization

```
pkg/
├── platform/
│   ├── platform_test.go
│   ├── cpu_test.go
│   └── gpu_test.go
├── config/
│   └── config_test.go
├── version/
│   ├── version_test.go
│   └── updates_test.go
├── web/
│   ├── api_test.go
│   ├── validation_test.go
│   └── server_test.go
├── installer/
│   ├── common_test.go
│   └── package_manager_test.go
└── locale/
    └── locale_test.go
```

### Writing Unit Tests

**Example Test Structure:**

```go
func TestValidateConfigValue_ValidHWA(t *testing.T) {
    tests := []struct {
        name  string
        key   string
        value string
        want  error
    }{
        {
            name:  "Valid nvdec",
            key:   "hwdec",
            value: "nvdec",
            want:  nil,
        },
        {
            name:  "Valid vaapi",
            key:   "hwdec",
            value: "vaapi",
            want:  nil,
        },
        {
            name:  "Invalid method",
            key:   "hwdec",
            value: "invalid",
            want:  errors.New("invalid HWA method: invalid"),
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got := ValidateConfigValue(tt.key, tt.value)
            if (got == nil) != (tt.want == nil) {
                if got == nil || tt.want == nil || got.Error() != tt.want.Error() {
                    t.Errorf("ValidateConfigValue() = %v, want %v", got, tt.want)
                }
            }
        })
    }
}
```

### Test Categories

#### 1. Validation Tests

**Purpose:** Test input validation functions

**Files:** `pkg/web/validation_test.go`

**Test Cases (136 total):**
- ValidateConfigValue - 33 test cases
- ValidateMethodID - 17 test cases
- ValidateAppName - 11 test cases
- ValidateAppType - 7 test cases
- ValidateLanguageCode - 14 test cases
- ValidateHWAValue - 20 test cases
- ValidateInstallMethod - 34 test cases

**Running Validation Tests:**
```bash
go test -v ./pkg/web/...
```

#### 2. Version Tests

**Purpose:** Test version management and download with progress

**Files:** `pkg/version/version_test.go`

**Test Cases:**
- ProgressWriter - 6 test cases
- DownloadFileWithProgress - 8 test cases
- UpdateSelfWithProgress - 2 test cases

**Test Scenarios:**
- Progress callback frequency
- Retry on connection errors
- HTTP 404 error handling
- File write error handling
- Exponential backoff delays
- Empty download handling
- Error propagation from underlying writer

**Running Version Tests:**
```bash
go test -v ./pkg/version/...
```

#### 3. API Tests

**Purpose:** Test API endpoints and modal system

**Files:** `pkg/web/api_test.go`

**Test Cases (13 total):**
- Modal API handlers
  - Shutdown modal
  - Update installer with version parameter
  - Uninstall with parameters
  - File associations
  - Config reset
  - Config restore with backup
  - Config apply
  - Error handling (missing type, unknown type, missing params)

**Running API Tests:**
```bash
go test -v ./pkg/web/...
```

#### 4. Modal System Tests

**Test Scenarios:**
- Modal configuration JSON serialization
- All 7 modal types return correct config
- Parameters passed correctly
- Danger flag handled correctly
- Error cases return appropriate messages

---

## Integration Testing

### Integration Test Scenarios

#### 1. Configuration Persistence

**Test Steps:**
1. Start with fresh config directory
2. Load language preferences (should return empty)
3. Save language preferences (en, es, fr)
4. Load language preferences (should return en, es, fr)
5. Update language preferences (de, it)
6. Load language preferences (should return de, it)
7. Verify config file contains correct values
8. Verify backup file created

**Expected Results:**
- ✅ Save/load cycle works correctly
- ✅ Backup created on first write
- ✅ Comments preserved
- ✅ Empty arrays clear config values

#### 2. Installation Flow

**Test Steps:**
1. Select MPV binary installation
2. Choose installation path
3. Start installation
4. Monitor output streaming
5. Verify installation completes
6. Verify app added to installed_apps
7. Verify shortcut created

**Expected Results:**
- ✅ Installation succeeds
- ✅ Output streamed in real-time
- ✅ App added to installed_apps
- ✅ Shortcut created
- ✅ Config backup created

#### 3. Update Detection

**Test Steps:**
1. Mock version server with old version
2. Check for updates
3. Verify update available indicator shown
4. Mock version server with same version
5. Check for updates
6. Verify no update indicator shown
7. Mock version server with new version
8. Download and install update
9. Verify version updated

**Expected Results:**
- ✅ Version comparison works correctly
- ✅ Update indicator displayed when needed
- ✅ Download with progress works
- ✅ BLAKE3 verification
- ✅ Version updated successfully

#### 4. Platform Detection

**Test Steps:**
1. Run on Windows
2. Verify OS detected as Windows
3. Verify architecture detected correctly
4. Run on Linux
5. Verify OS detected as Linux
6. Verify distribution detected
7. Run on macOS
8. Verify OS detected as macOS

**Expected Results:**
- ✅ Correct OS type detected
- ✅ Correct architecture detected
- ✅ Correct distribution detected (Linux only)
- ✅ GPU information gathered

---

## Manual Testing

### Pre-Test Checklist

**Environment Setup:**
- [ ] Clean installation directory (no previous installations)
- [ ] No existing config file
- [ ] All dependencies installed (Go, Make)
- [ ] Test machine has target OS/ARCH

**Platform-Specific Setup:**

**Windows:**
- [ ] Run as administrator for UAC tests
- [ ] PowerShell available
- [ ] Test on Windows 10 and Windows 11

**Linux:**
- [ ] Package manager available (apt/dnf/pacman)
- [ ] Permissions to write to /usr/local or home
- [ ] Test on Ubuntu, Fedora, Arch

**macOS:**
- [ ] Xcode command line tools installed
- [ ] Test on Intel and Apple Silicon

### Manual Test Cases

#### TUI Tests

**1. Main Menu Navigation**
- [ ] All menu items display correctly
- [ ] Arrow keys navigate up/down
- [ ] Enter key selects item
- [ ] Esc key returns to parent
- [ ] Quit command exits cleanly

**2. MPV Player Apps Installation**
- [ ] MPV binary installs successfully
- [ ] Celluloid installs successfully (Linux)
- [ ] IINA installs successfully (macOS)
- [ ] MPC-QT installs successfully (Windows)
- [ ] Installation output displayed in real-time
- [ ] Success message shown
- [ ] Error messages shown for failures
- [ ] Installed apps appear in menu

**3. Hardware Acceleration Configuration**
- [ ] HWA options filtered by platform/GPU
- [ ] Options display correctly
- [ ] Current HWA status shown
- [ ] Save updates config file
- [ ] GPU vendor colored correctly

**4. Language Preferences**
- [ ] Page opens without errors
- [ ] Languages loaded from config
- [ ] Major languages display (33 languages)
- [ ] Regional variants load correctly
- [ ] Search functionality works
- [ ] Save updates config
- [ ] Retry logic works (simulate failure)

**5. Updates Menu**
- [ ] Installer update check works
- [ ] App update check works
- [ ] Load latest config option works
- [ ] Config backup list loads
- [ ] Update available indicator shown
- [ ] Download progress bar displays

#### Web UI Tests

**1. Dashboard**
- [ ] Dashboard loads without errors
- [ ] Installed apps display correctly
- [ ] App logos show correctly
- [ ] Package manager versions displayed
- [ ] "Up to Date" status shown when applicable
- [ ] Client updates display correctly

**2. MPV Player Apps Page**
- [ ] Apps list loads correctly
- [ ] Install buttons work
- [ ] Uninstall buttons work
- [ ] Update buttons work
- [ ] Modals display correctly
- [ ] SSE streaming works for installations

**3. Configuration Pages**
- [ ] Language preferences load/save
- [ ] Hardware acceleration options work
- [ ] Apply config works
- [ ] Reset config works
- [ ] Restore config works

**4. System Information**
- [ ] All sections display correctly
- [ ] OS type capitalized with icon
- [ ] Architecture properly capitalized
- [ ] Distribution capitalized with icon
- [ ] Distro family capitalized with icon
- [ ] CPU features conditionally displayed

**5. Modal System**
- [ ] Shutdown modal works
- [ ] Update installer modal works
- [ ] Uninstall modal works
- [ ] Config reset modal works
- [ ] Config restore modal works
- [ ] Apply config modal works
- [ ] Esc key closes modal
- [ ] Click outside closes modal
- [ ] Fallback to browser confirm works

#### Installation Tests

**Windows:**
- [ ] MPV binary installs
- [ ] File associations set (with UAC)
- [ ] File associations removed (with UAC)
- [ ] Shortcuts created on desktop
- [ ] Shortcuts created in start menu
- [ ] VBS script auto-extracts

**Linux:**
- [ ] MPV binary installs (portable)
- [ ] Flatpak installs
- [ ] Snap installs
- [ ] .desktop file created
- [ ] Permissions set correctly

**macOS:**
- [ ] MPV binary installs
- [ ] App bundle installed
- [ ] Dock icon appears
- [ ] Spotlight indexing works

---

## Platform-Specific Testing

### Windows Testing

**Test Environments:**
- Windows 10 (latest update)
- Windows 11 (latest update)
- Different CPU architectures (x86-64-v2, x86-64-v3, x86-64-v4)

**Test Cases:**

**UAC Elevation:**
- [ ] UAC prompt appears for file associations
- [ ] UAC prompt appears for uninstall
- [ ] Operations complete after UAC approval
- [ ] Fire-and-forget pattern works

**Console Resize:**
- [ ] Console resizes to 120x40
- [ ] Full menu visible
- [ ] Success messages displayed

**File Associations:**
- [ ] Install file associations works
- [ ] Remove file associations works
- [ ] Batch file pause stripped at runtime

**Shortcuts:**
- [ ] Desktop shortcut created with correct icon
- [ ] Start menu shortcut created
- [ ] Icon-128.png used if available
- [ ] Falls back to mpv-manager.ico

**Known Issues:**
- Windows Defender may block downloads/exes
- OneDrive sync may interfere with config files

### Linux Testing

**Test Distributions:**
- Ubuntu 22.04/24.04 LTS
- Fedora 38/39
- Arch Linux
- Debian 12

**Test Cases:**

**Package Manager Detection:**
- [ ] APT version detection works
- [ ] Flatpak version detection works
- [ ] Snap version detection works
- [ ] Version queries parse correctly

**GPU Detection:**
- [ ] glxinfo detection works
- [ ] vulkaninfo detection works
- [ ] CPU iGPU filtering works
- [ ] Codec detection via VAAPI works
- [ ] Codec lookup from CSV works

**Installation:**
- [ ] Portable binary installs
- [ ] .desktop file created
- [ ] Executable permissions set

### macOS Testing

**Test Configurations:**
- Intel (x86_64)
- Apple Silicon (arm64)

**Test Cases:**

**GPU Detection:**
- [ ] VideoToolbox detection works with CGO
- [ ] Model-based fallback works for cross-compilation
- [ ] Codec detection accurate (M1/M2/M3 support)

**Installation:**
- [ ] App bundle installed
- [ ] Moved to /Applications
- [ ] Dock icon appears
- [ ] LaunchServices registered

**Architecture-Specific:**
- [ ] x86_64 builds work on Intel Macs
- [ ] arm64 builds work on Apple Silicon
- [ ] Universal binary (if created)

---

## Test Coverage

### Current Coverage Status

**Measured Coverage:**
- pkg/web: 98.0% (exceeds 80% target)
- pkg/version: ~75%
- pkg/platform: ~60%
- Overall: ~75%

### Coverage Goals

| Package | Current | Target | Priority |
|---------|---------|--------|----------|
| pkg/web | 98.0% | 90% | High ✅ |
| pkg/version | 75% | 80% | Medium |
| pkg/platform | 60% | 70% | Medium |
| pkg/installer | ~40% | 70% | High |
| pkg/config | ~30% | 70% | High |
| pkg/locale | ~20% | 60% | Low |

### Generating Coverage Report

```bash
# Run all tests with coverage
go test -coverprofile=coverage.out ./...

# Generate HTML report
go tool cover -html=coverage.out

# Open in browser
open coverage.html
```

### Coverage Exclusions

Valid exclusions from coverage:
- Generated code (bindata, embedded assets)
- Test code (test files themselves)
- Platform-specific code not testable on current platform
- External dependencies (syscall, platform APIs)

---

## CI/CD

### Automated Testing Pipeline

**Stages:**
1. **Linting** - Run golangci-lint
2. **Unit Tests** - Run all unit tests
3. **Integration Tests** - Run package integration tests
4. **Build** - Build for all platforms
5. **Artifact Upload** - Upload binaries and checksums

### Test Commands

```bash
# Lint
golangci-lint run ./...

# Unit tests with coverage
go test -v -coverprofile=coverage.out ./...

# Race detection
go test -race ./...

# Build all platforms
make build-all

# Generate checksums
make checksums
```

### Continuous Integration

**Actions:**
- Pull request triggers automated tests
- Tests run on multiple OS versions
- Coverage reports uploaded
- Binaries built and uploaded as artifacts

---

## Best Practices

### Writing Tests

**DO:**
- Write descriptive test names (e.g., `TestValidateConfigValue_ValidHWA`)
- Use table-driven tests for multiple similar cases
- Test both success and failure paths
- Test edge cases (empty, nil, invalid input)
- Use t.Run for sub-tests
- Mock external dependencies

**DON'T:**
- Don't ignore errors in tests
- Don't use time.Sleep (use channels for async)
- Don't test internal implementation details
- Don't duplicate test logic

### Test Organization

**File Organization:**
- Test files in same package as code
- Test files named `*_test.go`
- Related tests grouped in same file
- Platform-specific tests in separate files

**Test Structure:**
- Arrange: Set up test data and dependencies
- Act: Execute function being tested
- Assert: Verify expected results
- Cleanup: Release resources

### Running Tests

**Before Commit:**
```bash
# Run all tests
go test ./...

# Run with race detector
go test -race ./...

# Run with coverage
go test -cover ./...
```

**After Changes:**
- Run affected package tests only
- Verify no new test failures
- Check coverage not decreased

---

## Troubleshooting Tests

### Common Test Failures

**Issue:** "no test files" error

**Solution:**
```bash
# Ensure test files follow naming convention
# *_test.go pattern is required
ls *_test.go
```

**Issue:** Tests timing out

**Solution:**
```go
// Add timeout to test
func TestLongOperation(t *testing.T) {
    timeout := time.AfterFunc(5*time.Second, func() {
        t.Errorf("Test timed out")
    })
    defer timeout.Stop()
    
    // Run operation
    performLongOperation()
}
```

**Issue:** Race conditions in tests

**Solution:**
```bash
# Run with race detector
go test -race ./...

# Fix race conditions with proper synchronization
```

---

## Debugging Tests

### Verbose Mode

```bash
# Run tests with verbose output
go test -v ./pkg/web/...

# Run specific test with verbose output
go test -v -run TestValidateConfigValue ./pkg/web/
```

### Test with Debugger

```bash
# Install Delve debugger
go install github.com/go-delve/delve/cmd/dlv@latest

# Run tests with Delve
dlv test ./pkg/platform/
```

### Logging in Tests

```go
func TestWithLogging(t *testing.T) {
    // Enable debug logging for tests
    log.SetDebugMode(true)
    
    // Run test
    result := performOperation()
    
    // Log result for debugging
    if result.Error != nil {
        t.Logf("Operation failed: %v", result.Error)
    }
}
```

---

## Performance Testing

### Benchmark Tests

**Writing Benchmarks:**

```go
func BenchmarkValidateConfigValue(b *testing.B) {
    for i := 0; i < b.N; i++ {
        ValidateConfigValue("hwdec", "nvdec")
    }
}
```

**Running Benchmarks:**

```bash
# Run benchmarks
go test -bench=. -benchmem ./...

# Run specific benchmark
go test -bench=BenchmarkValidateConfigValue ./pkg/web/
```

### Profiling

```bash
# CPU profile
go test -cpuprofile=cpu.prof -bench=. ./...

# Memory profile
go test -memprofile=mem.prof ./...

# Analyze profile
go tool pprof cpu.prof
```

---

## Regression Testing

### Critical Path Testing

Before each release, verify:
1. [ ] Installation works on all platforms
2. [ ] Configuration save/load works
3. [ ] Update check and download works
4. [ ] TUI navigation works
5. [ ] Web UI loads and functions
6. [ ] No new test failures
7. [ ] Coverage not decreased

### Smoke Tests

Quick sanity checks:
```bash
# Build all platforms
make build-all

# Run installer on each platform
./mpv-manager-linux-x86_64 --version
./mpv-manager-win-x86_64.exe --version
./mpv-manager-darwin-arm64 --version

# Verify version output
```

---

## Documentation Testing

### Documentation Examples

**Verify:**
- All code examples compile
- All command examples work
- All file paths are correct
- All links resolve correctly

### Procedure Validation

**Test each documented procedure:**
1. Quick start instructions work
2. Build instructions work
3. Troubleshooting steps solve issues

---

## Test Checklist Summary

### Pre-Release Checklist

- [ ] All unit tests pass
- [ ] All integration tests pass
- [ ] Code coverage at target (80%+)
- [ ] Manual tests on Windows successful
- [ ] Manual tests on Linux successful
- [ ] Manual tests on macOS successful
- [ ] No new test failures
- [ ] No regressions in existing functionality
- [ ] Documentation updated
- [ ] Release notes written

### Post-Release Monitoring

- [ ] Monitor crash reports
- [ ] Monitor error logs
- [ ] Collect user feedback
- [ ] Track update adoption rate
- [ ] Track issue reports

---

## Testing Resources

### Useful Tools

- **Testing Framework:** Go testing package
- **Mocking:** testify/mock
- **Coverage:** go tool cover
- **Benchmarking:** Go benchmarking support
- **Profiling:** pprof
- **Linting:** golangci-lint

### Test Data

**Mock Data:**
- Mock release JSON for version testing
- Mock GPU detection data
- Mock package manager outputs
- Mock API responses

### Test Utilities

**Helper Functions:**
- Test setup helpers
- Test assertion helpers
- Mock HTTP servers
- Test file cleanup

---

## Conclusion

This testing guide provides comprehensive procedures for maintaining quality across the MPV.Rocks Installer project. Follow these guidelines to ensure reliable, bug-free releases.

For specific testing procedures, see:
- [Session Summaries](docs/SESSION_SUMMARIES.md) - Detailed session testing procedures
- [Architecture](docs/ARCHITECTURE.md) - Component interaction and design patterns
- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and solutions