nextav/tests/README.md

# NextAV Test Suite Documentation

## 📋 **Test Organization**

This directory contains all test scripts and testing utilities for the NextAV media library system, organized by testing category.

---

## 🎬 **Player Testing** (`tests/player/`)

### **HTML Interface Tests**
- **`test-artplayer.html`** - ArtPlayer integration testing
  - Tests ArtPlayer functionality across different pages
  - Validates bookmark/rating integration
  - Provides interactive checklist for manual testing
  
- **`test-hls.html`** - HLS streaming endpoint testing
  - Tests HLS playlist generation and segment delivery
  - Interactive buttons for testing different endpoints
  - Video player integration testing

**Usage**: Open in browser at `http://localhost:3000/tests/player/[filename].html`

---

## ⚙️ **Streaming Tests** (`tests/streaming/`)

### **Node.js Streaming Tests**
- **`test-ts-streaming.mjs`** - .ts file streaming test suite
  - Tests format detection for .ts files
  - Validates streaming URL generation
  - Tests different quality levels and endpoints
  
- **`verify-hls.js`** - HLS endpoint verification script
  - Automated HLS implementation diagnostics
  - Tests playlist and segment endpoints
  - Validates HTTP headers and responses

**Usage**: `node tests/streaming/[script-name].mjs`

---

## 🚀 **Performance Tests** (`tests/performance/`)

### **Progress and Transcoding Tests**
- **`test-progress-bar.mjs`** - Progress bar accuracy testing
  - Tests duration header detection
  - Validates progress calculation for transcoded videos
  - Checks transcoding endpoint headers
  
- **`test-transcoding.mjs`** - Video transcoding system testing
  - Tests codec detection logic
  - Validates transcoding decision making
  - Simulates different video format scenarios

**Usage**: `node tests/performance/[script-name].mjs`

---

## 🔧 **Diagnostic Tools** (`tests/diagnostics/`)

### **System Diagnostics**
- **`diagnose-hls.js`** - HLS implementation diagnostic tool
  - Checks HLS API route existence
  - Validates format detector configuration
  - Identifies potential implementation issues
  
- **`migrate-folder-bookmarks.sh`** - Database migration utility
  - Migrates folder bookmark data
  - Shell script for database operations
  - Backup and migration procedures

- **`test-intellisense-case-sensitivity.mjs`** - IntelliSense case sensitivity test
  - Tests the fix for case sensitivity issues in the library IntelliSense feature
  - Verifies that paths with different case are properly matched on Linux systems
  - Validates path normalization logic

**Usage**: 
- `node tests/diagnostics/diagnose-hls.js`
- `bash tests/diagnostics/migrate-folder-bookmarks.sh`
- `node tests/diagnostics/test-intellisense-case-sensitivity.mjs`

---

## 🎯 **Testing Categories**

| Category | Purpose | Scripts | Status |
|----------|---------|---------|---------|
| **Player Testing** | Video player functionality | 2 HTML files | ✅ Active |
| **Streaming** | HLS and .ts streaming | 2 Node.js scripts | ✅ Active |
| **Performance** | Progress and transcoding | 2 Node.js scripts | ✅ Active |
| **Diagnostics** | System health checks | 1 Node.js + 1 shell + 1 Node.js | ✅ Active |

---

## 🏃‍♂️ **Quick Start**

### **Run All Tests**
```
# Player tests (manual browser testing)
open http://localhost:3000/tests/player/test-artplayer.html
open http://localhost:3000/tests/player/test-hls.html

# Automated tests
node tests/streaming/test-ts-streaming.mjs
node tests/streaming/verify-hls.js
node tests/performance/test-progress-bar.mjs
node tests/performance/test-transcoding.mjs
node tests/diagnostics/diagnose-hls.js
node tests/diagnostics/test-intellisense-case-sensitivity.mjs

# Migration utility
bash tests/diagnostics/migrate-folder-bookmarks.sh
```

### **Test Individual Components**
```bash
# Test specific video ID
node tests/streaming/test-ts-streaming.mjs

# Verify HLS endpoints
node tests/streaming/verify-hls.js

# Check progress bar fixes
node tests/performance/test-progress-bar.mjs

# Diagnose HLS implementation
node tests/diagnostics/diagnose-hls.js

# Test IntelliSense case sensitivity fix
node tests/diagnostics/test-intellisense-case-sensitivity.mjs
```

---

## 📊 **Test Coverage**

### **Video Player Features**
- ✅ ArtPlayer integration
- ✅ HLS streaming support
- ✅ Bookmark/rating integration
- ✅ Cross-page compatibility

### **Streaming Capabilities**
- ✅ .ts file handling
- ✅ HLS playlist generation
- ✅ Segment delivery
- ✅ Format detection

### **Performance Features**
- ✅ Progress bar accuracy
- ✅ Transcoding decisions
- ✅ Duration header handling
- ✅ Process management

### **System Health**
- ✅ HLS route validation
- ✅ Database migration
- ✅ Format detector checks
- ✅ API endpoint verification

---

## 🔧 **Creating New Tests**

### **Test Script Template**
```
#!/usr/bin/env node

/**
 * Test Description
 * Brief explanation of what this test validates
 */

const BASE_URL = 'http://localhost:3000';

async function runTest() {
  console.log('🧪 Running test...');
  
  try {
    // Test implementation
    console.log('✅ Test passed');
  } catch (error) {
    console.error('❌ Test failed:', error.message);
    process.exit(1);
  }
}

runTest();
```

### **HTML Test Template**
```
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Test Title</title>
    <style>
        body { font-family: Arial, sans-serif; margin: 20px; }
        .test-section { margin: 20px 0; padding: 15px; border: 1px solid #ccc; border-radius: 5px; }
        .success { color: green; font-weight: bold; }
        .error { color: red; font-weight: bold; }
    </style>
</head>
<body>
    <h1>Test Title</h1>
    <!-- Test content -->
</body>
</html>
```

---

## 📈 **Test Statistics**

- **Total Test Scripts**: 9
- **HTML Interface Tests**: 2
- **Node.js Tests**: 5
- **Shell Scripts**: 1
- **Diagnostic Tools**: 1
- **Coverage Areas**: Player, Streaming, Performance, Diagnostics

---

## 🔄 **Continuous Testing**

### **Pre-commit Testing**
```bash
# Quick smoke tests
node tests/diagnostics/diagnose-hls.js
node tests/performance/test-transcoding.mjs
```

### **Development Testing**
```bash
# Full test suite
npm run test:player      # Browser-based tests
npm run test:streaming   # Streaming tests
npm run test:performance # Performance tests
npm run test:diagnostics # System diagnostics
```

---

*Last Updated: October 13, 2025*  
*Total Tests: 8*  
*Coverage: Player, Streaming, Performance, Diagnostics*