nfoguard/TESTING.md

# NFOGuard Testing Guide

## 🧪 Test Scripts Overview

NFOGuard includes 3 specialized testing scripts to validate different parts of the workflow. These are designed to be run via webhooks or manual API calls, not directly on the command line.

### 1. `test_bulk_update.py` - Database Connection Validator
**Purpose**: Tests that the bulk update system can connect to databases without modifying any data.

**What it tests**:
- Radarr database connection
- NFOGuard database connection  
- Query execution (reads first 5 movies)
- Import detection logic

**When to use**: Before running the full bulk update to ensure everything is configured correctly.

**How to run**:
```bash
# Via webhook/API inside container
curl -X POST "http://nfoguard:8080/test/bulk-update"

# Or manually inside container
python3 test_bulk_update.py
```

### 2. `test_movie_scan.py` - Directory Structure Validator  
**Purpose**: Tests the movie directory scanning logic to ensure movies will be found.

**What it tests**:
- Path configuration validation
- IMDb ID parsing from directory names
- Movie discovery logic
- Directory structure understanding

**When to use**: When manual scans report "0 movies found" to debug path issues.

**Sample output**:
```
🔍 Testing Movie Directory Scanning
✅ '/media/Movies/movies' -> Found 150 movies with IMDb IDs
✅ 'The Dark Knight [imdb-tt0468569] (2008)' -> tt0468569
❌ 'Invalid Movie (2020)' -> No IMDb ID found
```

### 3. `test_end_to_end.py` - Complete Workflow Validator
**Purpose**: Tests the entire NFOGuard workflow from database queries to NFO creation.

**What it tests**:
- Server health and connectivity
- Database performance (your July 2025 date test)
- Manual scan trigger
- Batch processing status
- Statistics endpoints

**When to use**: After deployment to verify the complete system works end-to-end.

**How to run**:
```bash
# Via webhook inside container
curl -X POST "http://nfoguard:8080/test/end-to-end"
```

## 🚀 Testing Workflow for Docker Deployment

### Step 1: Deploy with Environment Variables
```bash
# Copy your environment template
cp .env.example .env
# Edit .env with your actual database password
nano .env

# Deploy
docker-compose up -d
```

### Step 2: Validate Database Connections
```bash
# Test database connectivity
curl -X POST "http://localhost:8080/test/bulk-update"

# Should show:
# ✅ Radarr database connection successful
# ✅ NFOGuard database connection successful
```

### Step 3: Test Movie Discovery
```bash
# Test that movies will be found
curl -X POST "http://localhost:8080/test/movie-scan"

# Should show paths and sample movies found
```

### Step 4: Run Full End-to-End Test
```bash
# Complete workflow test
curl -X POST "http://localhost:8080/test/end-to-end"

# Should show all systems operational
```

### Step 5: Production Testing
```bash
# Test database performance (your working July date)
curl "http://localhost:8080/debug/movie/tt1674782"

# Should return: 2025-07-08T03:30:04+00:00

# Run manual scan
curl -X POST "http://localhost:8080/manual/scan?scan_type=movies"

# Run bulk update
curl -X POST "http://localhost:8080/bulk/update"
```

### Step 6: Test Enhanced TV Processing (v0.6.0+)
```bash
# Test Sonarr API integration
curl "http://localhost:8080/health"
# Check that Sonarr connection shows up

# Test single season processing (URL-safe)
curl -X POST "http://localhost:8080/tv/scan-season" \
  -H "Content-Type: application/json" \
  -d '{
    "series_path": "/media/TV/tv/Your Show [imdb-tt1234567]",
    "season_name": "Season 01"
  }'

# Test single episode processing (URL-safe)
curl -X POST "http://localhost:8080/tv/scan-episode" \
  -H "Content-Type: application/json" \
  -d '{
    "series_path": "/media/TV/tv/Your Show [imdb-tt1234567]",
    "season_name": "Season 01",
    "episode_name": "S01E01.mkv"
  }'

# Verify enhanced NFO was created with metadata
find /media/TV/tv -name "S01E*.nfo" | head -1 | xargs cat
# Should show: <title>, <plot>, <rating>, <runtime>, timestamps

# Test TV webhook processing modes
export TV_WEBHOOK_PROCESSING_MODE=targeted  # or series
# Download episode in Sonarr and check logs for processing mode
```

### Step 7: Test TV Webhook Processing Modes (v0.6.0+)
```bash
# Test targeted mode (default - processes only webhook episodes)
echo "TV_WEBHOOK_PROCESSING_MODE=targeted" >> .env
docker restart nfoguard

# Download single episode in Sonarr, check logs should show:
# "Using targeted episode processing for 1 episodes"
# "Completed targeted processing: 1/1 episodes processed"

# Test series mode (processes entire series)  
echo "TV_WEBHOOK_PROCESSING_MODE=series" >> .env
docker restart nfoguard

# Download single episode in Sonarr, check logs should show:
# "Using series processing mode (fallback or configured)"
# "Processing TV series: Show Name"
# "Found X episodes on disk"
```

## 🛠 Why These Tests Are Needed

1. **Docker Environment Isolation**: Tests run in the same environment as the production app
2. **Database-Only Validation**: Ensures the optimized database queries work correctly
3. **Path Configuration**: Validates that your specific directory structure is properly configured
4. **Webhook Integration**: Tests run via HTTP calls, same as Radarr webhooks
5. **CI/CD Integration**: Can be automated in deployment pipelines

## 🔍 Troubleshooting with Tests

**"0 movies processed"** → Run `test_movie_scan.py` to check path configuration
**Database errors** → Run `test_bulk_update.py` to validate connections
**Workflow issues** → Run `test_end_to_end.py` for comprehensive diagnosis

These tests are designed to catch issues before they impact your media processing workflow.