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:

# 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:

# 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

# 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

# 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

# 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

# Complete workflow test
curl -X POST "http://localhost:8080/test/end-to-end"

# Should show all systems operational

Step 5: Production Testing

# 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+)

# 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+)

# 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.