repo restructure

tests/test_api.py

@@ -0,0 +1,275 @@
+#!/usr/bin/env python3
+"""
+API Test Script
+
+This script helps test your API endpoints before running the full image downloader.
+It will check if the list endpoint returns valid data and if the download endpoint
+is accessible.
+
+Usage:
+    python test_api.py --api-url <base_url> --list-endpoint <endpoint> --download-endpoint <endpoint>
+"""
+
+import argparse
+import asyncio
+import aiohttp
+import json
+from urllib.parse import urljoin
+from typing import Dict, Any
+
+
+class APITester:
+    def __init__(self, api_url: str, list_endpoint: str, download_endpoint: str, timeout: int = 30, api_key: str = None):
+        self.api_url = api_url.rstrip('/')
+        self.list_endpoint = list_endpoint.lstrip('/')
+        self.download_endpoint = download_endpoint.lstrip('/')
+        self.timeout = timeout
+        self.api_key = api_key
+
+    async def test_list_endpoint(self, session: aiohttp.ClientSession) -> Dict[str, Any]:
+        """Test the list endpoint and return information about the response."""
+        url = urljoin(self.api_url, self.list_endpoint)
+        print(f"Testing list endpoint: {url}")
+        
+        try:
+            headers = {}
+            if self.api_key:
+                headers['x-api-key'] = self.api_key
+            
+            async with session.get(url, headers=headers, timeout=self.timeout) as response:
+                print(f"Status Code: {response.status}")
+                print(f"Content-Type: {response.headers.get('content-type', 'Not specified')}")
+                
+                if response.status == 200:
+                    data = await response.json()
+                    print(f"Response type: {type(data)}")
+                    
+                    # Analyze the response structure
+                    if isinstance(data, list):
+                        print(f"Found {len(data)} assets in array")
+                        if data:
+                            print(f"First asset keys: {list(data[0].keys())}")
+                    elif isinstance(data, dict):
+                        print(f"Response keys: {list(data.keys())}")
+                        
+                        # Check common patterns
+                        for key in ['data', 'results', 'items', 'assets', 'images']:
+                            if key in data and isinstance(data[key], list):
+                                print(f"Found {len(data[key])} assets in '{key}' field")
+                                if data[key]:
+                                    print(f"First asset keys: {list(data[key][0].keys())}")
+                                break
+                        else:
+                            print("No recognized array field found in response")
+                    else:
+                        print(f"Unexpected response format: {type(data)}")
+                    
+                    return {
+                        'success': True,
+                        'data': data,
+                        'url': url
+                    }
+                else:
+                    print(f"Error: HTTP {response.status_code}")
+                    return {
+                        'success': False,
+                        'error': f"HTTP {response.status_code}",
+                        'url': url
+                    }
+                    
+        except Exception as e:
+            print(f"Error testing list endpoint: {e}")
+            return {
+                'success': False,
+                'error': str(e),
+                'url': url
+            }
+
+    async def test_download_endpoint(self, session: aiohttp.ClientSession, asset_id: str) -> Dict[str, Any]:
+        """Test the download endpoint with a sample asset ID."""
+        url = urljoin(self.api_url, f"{self.download_endpoint}/{asset_id}")
+        print(f"\nTesting download endpoint: {url}")
+        
+        try:
+            headers = {}
+            if self.api_key:
+                headers['x-api-key'] = self.api_key
+            
+            async with session.get(url, headers=headers, timeout=self.timeout) as response:
+                print(f"Status Code: {response.status}")
+                print(f"Content-Type: {response.headers.get('content-type', 'Not specified')}")
+                print(f"Content-Length: {response.headers.get('content-length', 'Not specified')}")
+                
+                if response.status == 200:
+                    content_type = response.headers.get('content-type', '')
+                    if content_type.startswith('image/'):
+                        print("✓ Download endpoint returns image content")
+                        return {
+                            'success': True,
+                            'url': url,
+                            'content_type': content_type
+                        }
+                    else:
+                        print(f"⚠ Warning: Content type is not an image: {content_type}")
+                        return {
+                            'success': True,
+                            'url': url,
+                            'content_type': content_type,
+                            'warning': 'Not an image'
+                        }
+                else:
+                    print(f"Error: HTTP {response.status}")
+                    return {
+                        'success': False,
+                        'error': f"HTTP {response.status}",
+                        'url': url
+                    }
+                    
+        except Exception as e:
+            print(f"Error testing download endpoint: {e}")
+            return {
+                'success': False,
+                'error': str(e),
+                'url': url
+            }
+
+    async def run_tests(self):
+        """Run all API tests."""
+        print("=" * 60)
+        print("API Endpoint Test")
+        print("=" * 60)
+        
+        timeout = aiohttp.ClientTimeout(total=self.timeout)
+        async with aiohttp.ClientSession(timeout=timeout) as session:
+            # Test list endpoint
+            list_result = await self.test_list_endpoint(session)
+            
+            if list_result['success']:
+                # Try to test download endpoint with first asset
+                data = list_result['data']
+                asset_id = None
+                
+                # Find an asset ID to test with
+                if isinstance(data, list) and data:
+                    asset = data[0]
+                    for key in ['id', 'asset_id', 'image_id', 'file_id', 'uuid', 'key']:
+                        if key in asset:
+                            asset_id = asset[key]
+                            break
+                elif isinstance(data, dict):
+                    for key in ['data', 'results', 'items', 'assets', 'images']:
+                        if key in data and isinstance(data[key], list) and data[key]:
+                            asset = data[key][0]
+                            for id_key in ['id', 'asset_id', 'image_id', 'file_id', 'uuid', 'key']:
+                                if id_key in asset:
+                                    asset_id = asset[id_key]
+                                    break
+                            if asset_id:
+                                break
+                
+                if asset_id:
+                    print(f"\nUsing asset ID '{asset_id}' for download test")
+                    download_result = await self.test_download_endpoint(session, asset_id)
+                else:
+                    print("\n⚠ Could not find an asset ID to test download endpoint")
+                    print("You may need to manually test the download endpoint")
+            
+            # Print summary
+            print("\n" + "=" * 60)
+            print("TEST SUMMARY")
+            print("=" * 60)
+            
+            if list_result['success']:
+                print("✓ List endpoint: Working")
+            else:
+                print("✗ List endpoint: Failed")
+                print(f"  Error: {list_result['error']}")
+            
+            if 'download_result' in locals():
+                if download_result['success']:
+                    print("✓ Download endpoint: Working")
+                    if 'warning' in download_result:
+                        print(f"  Warning: {download_result['warning']}")
+                else:
+                    print("✗ Download endpoint: Failed")
+                    print(f"  Error: {download_result['error']}")
+            
+            print("\nRecommendations:")
+            if list_result['success']:
+                print("- List endpoint is working correctly")
+                print("- You can proceed with the image downloader")
+            else:
+                print("- Check your API URL and list endpoint")
+                print("- Verify the API is accessible")
+                print("- Check if authentication is required")
+            
+            if 'download_result' in locals() and not download_result['success']:
+                print("- Check your download endpoint format")
+                print("- Verify asset IDs are being passed correctly")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Test API endpoints for image downloader",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python test_api.py --api-url "https://api.example.com" \\
+                     --list-endpoint "/assets" \\
+                     --download-endpoint "/download"
+        """
+    )
+    
+    parser.add_argument(
+        '--api-url',
+        required=True,
+        help='Base URL of the API (e.g., https://api.example.com)'
+    )
+    
+    parser.add_argument(
+        '--list-endpoint',
+        required=True,
+        help='Endpoint to get the list of assets (e.g., /assets or /images)'
+    )
+    
+    parser.add_argument(
+        '--download-endpoint',
+        required=True,
+        help='Endpoint to download individual assets (e.g., /download or /assets)'
+    )
+    
+    parser.add_argument(
+        '--timeout',
+        type=int,
+        default=30,
+        help='Request timeout in seconds (default: 30)'
+    )
+    
+    parser.add_argument(
+        '--api-key',
+        help='API key for authentication (x-api-key header)'
+    )
+    
+    args = parser.parse_args()
+    
+    tester = APITester(
+        api_url=args.api_url,
+        list_endpoint=args.list_endpoint,
+        download_endpoint=args.download_endpoint,
+        timeout=args.timeout,
+        api_key=args.api_key
+    )
+    
+    try:
+        asyncio.run(tester.run_tests())
+    except KeyboardInterrupt:
+        print("\nTest interrupted by user")
+    except Exception as e:
+        print(f"Error: {e}")
+        return 1
+    
+    return 0
+
+
+if __name__ == "__main__":
+    exit(main()) 

tests/test_asset_tracking.py

@@ -0,0 +1,366 @@
+#!/usr/bin/env python3
+"""
+Test Asset Tracking Functionality
+
+This script tests the asset tracking system to ensure new assets are detected
+and only new/modified assets are downloaded.
+"""
+
+import asyncio
+import json
+import logging
+import sys
+import tempfile
+from pathlib import Path
+from datetime import datetime
+import os
+
+# Add the current directory to the path so we can import modules
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from asset_tracker import AssetTracker
+from auth_manager import AuthManager
+from image_downloader import ImageDownloader
+
+
+class AssetTrackingTester:
+    """Test class for asset tracking functionality."""
+
+    def __init__(self):
+        """Initialize the tester."""
+        self.logger = logging.getLogger(__name__)
+
+        # Mock API data for testing
+        self.mock_assets_v1 = [
+            {
+                "id": "asset_001",
+                "name": "family_photo_1.jpg",
+                "updated": "2024-01-01T10:00:00Z",
+                "size": 1024000,
+                "mimeType": "image/jpeg"
+            },
+            {
+                "id": "asset_002",
+                "name": "birthday_party.jpg",
+                "updated": "2024-01-02T15:30:00Z",
+                "size": 2048000,
+                "mimeType": "image/jpeg"
+            },
+            {
+                "id": "asset_003",
+                "name": "school_event.png",
+                "updated": "2024-01-03T09:15:00Z",
+                "size": 1536000,
+                "mimeType": "image/png"
+            }
+        ]
+
+        self.mock_assets_v2 = [
+            # Existing asset - unchanged
+            {
+                "id": "asset_001",
+                "name": "family_photo_1.jpg",
+                "updated": "2024-01-01T10:00:00Z",
+                "size": 1024000,
+                "mimeType": "image/jpeg"
+            },
+            # Existing asset - modified
+            {
+                "id": "asset_002",
+                "name": "birthday_party.jpg",
+                "updated": "2024-01-05T16:45:00Z",  # Updated timestamp
+                "size": 2100000,  # Different size
+                "mimeType": "image/jpeg"
+            },
+            # Existing asset - unchanged
+            {
+                "id": "asset_003",
+                "name": "school_event.png",
+                "updated": "2024-01-03T09:15:00Z",
+                "size": 1536000,
+                "mimeType": "image/png"
+            },
+            # New asset
+            {
+                "id": "asset_004",
+                "name": "new_vacation_photo.jpg",
+                "updated": "2024-01-06T14:20:00Z",
+                "size": 3072000,
+                "mimeType": "image/jpeg"
+            }
+        ]
+
+    def test_basic_tracking(self):
+        """Test basic asset tracking functionality."""
+        print("=" * 60)
+        print("TEST 1: Basic Asset Tracking")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            tracker = AssetTracker(storage_dir=temp_dir)
+
+            print(f"Testing with temporary directory: {temp_dir}")
+
+            # Test with empty tracker
+            print("\n1. Testing new asset detection (empty tracker)...")
+            new_assets = tracker.get_new_assets(self.mock_assets_v1)
+            print(f"   Found {len(new_assets)} new assets (expected: 3)")
+            assert len(new_assets) == 3, f"Expected 3 new assets, got {len(new_assets)}"
+            print("   ✅ All assets correctly identified as new")
+
+            # Simulate downloading first batch
+            print("\n2. Simulating download of first batch...")
+            for asset in self.mock_assets_v1:
+                filename = asset['name']
+                filepath = Path(temp_dir) / filename
+
+                # Create dummy file
+                filepath.write_text(f"Mock content for {asset['id']}")
+
+                # Mark as downloaded
+                tracker.mark_asset_downloaded(asset, filepath, True)
+                print(f"   Marked as downloaded: {filename}")
+
+            # Test tracker stats
+            stats = tracker.get_stats()
+            print(f"\n3. Tracker statistics after first batch:")
+            print(f"   Total tracked assets: {stats['total_tracked_assets']}")
+            print(f"   Successful downloads: {stats['successful_downloads']}")
+            print(f"   Existing files: {stats['existing_files']}")
+
+            # Test with same assets (should find no new ones)
+            print("\n4. Testing with same assets (should find none)...")
+            new_assets = tracker.get_new_assets(self.mock_assets_v1)
+            print(f"   Found {len(new_assets)} new assets (expected: 0)")
+            assert len(new_assets) == 0, f"Expected 0 new assets, got {len(new_assets)}"
+            print("   ✅ Correctly identified all assets as already downloaded")
+
+            print("\n✅ Basic tracking test passed!")
+
+    def test_modified_asset_detection(self):
+        """Test detection of modified assets."""
+        print("\n" + "=" * 60)
+        print("TEST 2: Modified Asset Detection")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            tracker = AssetTracker(storage_dir=temp_dir)
+
+            # Simulate first batch download
+            print("1. Simulating initial download...")
+            for asset in self.mock_assets_v1:
+                filename = asset['name']
+                filepath = Path(temp_dir) / filename
+                filepath.write_text(f"Mock content for {asset['id']}")
+                tracker.mark_asset_downloaded(asset, filepath, True)
+
+            print(f"   Downloaded {len(self.mock_assets_v1)} assets")
+
+            # Test with modified assets
+            print("\n2. Testing with modified asset list...")
+            new_assets = tracker.get_new_assets(self.mock_assets_v2)
+            print(f"   Found {len(new_assets)} new/modified assets")
+
+            # Should detect 1 modified + 1 new = 2 assets
+            expected = 2  # asset_002 (modified) + asset_004 (new)
+            assert len(new_assets) == expected, f"Expected {expected} assets, got {len(new_assets)}"
+
+            # Check which assets were detected
+            detected_ids = [asset['id'] for asset in new_assets]
+            print(f"   Detected asset IDs: {detected_ids}")
+
+            assert 'asset_002' in detected_ids, "Modified asset_002 should be detected"
+            assert 'asset_004' in detected_ids, "New asset_004 should be detected"
+            assert 'asset_001' not in detected_ids, "Unchanged asset_001 should not be detected"
+            assert 'asset_003' not in detected_ids, "Unchanged asset_003 should not be detected"
+
+            print("   ✅ Correctly identified 1 modified + 1 new asset")
+            print("✅ Modified asset detection test passed!")
+
+    def test_cleanup_functionality(self):
+        """Test cleanup of missing files."""
+        print("\n" + "=" * 60)
+        print("TEST 3: Cleanup Functionality")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            tracker = AssetTracker(storage_dir=temp_dir)
+
+            # Create some files and track them
+            print("1. Creating and tracking assets...")
+            filepaths = []
+            for asset in self.mock_assets_v1:
+                filename = asset['name']
+                filepath = Path(temp_dir) / filename
+                filepath.write_text(f"Mock content for {asset['id']}")
+                tracker.mark_asset_downloaded(asset, filepath, True)
+                filepaths.append(filepath)
+                print(f"   Created and tracked: {filename}")
+
+            # Remove one file manually
+            print("\n2. Removing one file manually...")
+            removed_file = filepaths[1]
+            removed_file.unlink()
+            print(f"   Removed: {removed_file.name}")
+
+            # Check stats before cleanup
+            stats_before = tracker.get_stats()
+            print(f"\n3. Stats before cleanup:")
+            print(f"   Total tracked: {stats_before['total_tracked_assets']}")
+            print(f"   Existing files: {stats_before['existing_files']}")
+            print(f"   Missing files: {stats_before['missing_files']}")
+
+            # Run cleanup
+            print("\n4. Running cleanup...")
+            tracker.cleanup_missing_files()
+
+            # Check stats after cleanup
+            stats_after = tracker.get_stats()
+            print(f"\n5. Stats after cleanup:")
+            print(f"   Total tracked: {stats_after['total_tracked_assets']}")
+            print(f"   Existing files: {stats_after['existing_files']}")
+            print(f"   Missing files: {stats_after['missing_files']}")
+
+            # Verify cleanup worked
+            assert stats_after['missing_files'] == 0, "Should have no missing files after cleanup"
+            assert stats_after['total_tracked_assets'] == len(self.mock_assets_v1) - 1, "Should have one less tracked asset"
+
+            print("   ✅ Cleanup successfully removed missing file metadata")
+            print("✅ Cleanup functionality test passed!")
+
+    async def test_integration_with_downloader(self):
+        """Test integration with ImageDownloader."""
+        print("\n" + "=" * 60)
+        print("TEST 4: Integration with ImageDownloader")
+        print("=" * 60)
+
+        # Note: This test requires actual API credentials to work fully
+        # For now, we'll test the initialization and basic functionality
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            print(f"1. Testing ImageDownloader with asset tracking...")
+
+            try:
+                downloader = ImageDownloader(
+                    api_url="https://api.parentzone.me",
+                    list_endpoint="/v1/media/list",
+                    download_endpoint="/v1/media",
+                    output_dir=temp_dir,
+                    track_assets=True
+                )
+
+                # Check if asset tracker was initialized
+                if downloader.asset_tracker:
+                    print("   ✅ Asset tracker successfully initialized in downloader")
+
+                    # Test tracker stats
+                    stats = downloader.asset_tracker.get_stats()
+                    print(f"   Initial stats: {stats['total_tracked_assets']} tracked assets")
+                else:
+                    print("   ❌ Asset tracker was not initialized")
+
+            except Exception as e:
+                print(f"   Error during downloader initialization: {e}")
+
+            print("✅ Integration test completed!")
+
+    def run_all_tests(self):
+        """Run all tests."""
+        print("🚀 Starting Asset Tracking Tests")
+        print("=" * 80)
+
+        try:
+            self.test_basic_tracking()
+            self.test_modified_asset_detection()
+            self.test_cleanup_functionality()
+            asyncio.run(self.test_integration_with_downloader())
+
+            print("\n" + "=" * 80)
+            print("🎉 ALL TESTS PASSED!")
+            print("=" * 80)
+            return True
+
+        except Exception as e:
+            print(f"\n❌ TEST FAILED: {e}")
+            import traceback
+            traceback.print_exc()
+            return False
+
+
+async def test_with_real_api():
+    """Test with real API (requires authentication)."""
+    print("\n" + "=" * 60)
+    print("REAL API TEST: Asset Tracking with ParentZone API")
+    print("=" * 60)
+
+    # Test credentials
+    email = "tudor.sitaru@gmail.com"
+    password = "mTVq8uNUvY7R39EPGVAm@"
+
+    with tempfile.TemporaryDirectory() as temp_dir:
+        print(f"Using temporary directory: {temp_dir}")
+
+        try:
+            # Create downloader with asset tracking
+            downloader = ImageDownloader(
+                api_url="https://api.parentzone.me",
+                list_endpoint="/v1/media/list",
+                download_endpoint="/v1/media",
+                output_dir=temp_dir,
+                email=email,
+                password=password,
+                track_assets=True,
+                max_concurrent=2  # Limit for testing
+            )
+
+            print("\n1. First run - downloading all assets...")
+            await downloader.download_all_assets()
+
+            if downloader.asset_tracker:
+                stats1 = downloader.asset_tracker.get_stats()
+                print(f"\nFirst run statistics:")
+                print(f"   Downloaded assets: {stats1['successful_downloads']}")
+                print(f"   Failed downloads: {stats1['failed_downloads']}")
+                print(f"   Total size: {stats1['total_size_mb']} MB")
+
+            print("\n2. Second run - should find no new assets...")
+            downloader.stats = {'total': 0, 'successful': 0, 'failed': 0, 'skipped': 0}
+            await downloader.download_all_assets()
+
+            if downloader.asset_tracker:
+                stats2 = downloader.asset_tracker.get_stats()
+                print(f"\nSecond run statistics:")
+                print(f"   New downloads: {downloader.stats['successful']}")
+                print(f"   Skipped (unchanged): {len(stats2.get('total_tracked_assets', 0))}")
+
+            print("\n✅ Real API test completed!")
+
+        except Exception as e:
+            print(f"❌ Real API test failed: {e}")
+            import traceback
+            traceback.print_exc()
+
+
+def main():
+    """Main test function."""
+    # Setup logging
+    logging.basicConfig(
+        level=logging.INFO,
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+    )
+
+    tester = AssetTrackingTester()
+
+    # Run unit tests
+    success = tester.run_all_tests()
+
+    # Ask user if they want to run real API test
+    if success and len(sys.argv) > 1 and sys.argv[1] == '--real-api':
+        print("\n" + "🌐 Running real API test...")
+        asyncio.run(test_with_real_api())
+
+    return 0 if success else 1
+
+
+if __name__ == "__main__":
+    exit(main())

tests/test_config_tracking.py

@@ -0,0 +1,339 @@
+#!/usr/bin/env python3
+"""
+Test Config Downloader with Asset Tracking
+
+This script tests that the config_downloader.py now properly uses
+asset tracking to avoid re-downloading existing assets.
+"""
+
+import asyncio
+import json
+import logging
+import sys
+import tempfile
+import os
+from pathlib import Path
+
+# Add the current directory to the path so we can import modules
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from config_downloader import ConfigImageDownloader
+from asset_tracker import AssetTracker
+
+
+class ConfigTrackingTester:
+    """Test class for config downloader asset tracking functionality."""
+
+    def __init__(self):
+        """Initialize the tester."""
+        self.logger = logging.getLogger(__name__)
+
+    def create_test_config(self, output_dir: str, track_assets: bool = True) -> dict:
+        """Create a test configuration."""
+        return {
+            "api_url": "https://api.parentzone.me",
+            "list_endpoint": "/v1/media/list",
+            "download_endpoint": "/v1/media",
+            "output_dir": output_dir,
+            "max_concurrent": 2,
+            "timeout": 30,
+            "track_assets": track_assets,
+            "email": "tudor.sitaru@gmail.com",
+            "password": "mTVq8uNUvY7R39EPGVAm@"
+        }
+
+    def test_config_loading(self):
+        """Test that configuration properly loads asset tracking setting."""
+        print("=" * 60)
+        print("TEST 1: Configuration Loading")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            config_file = Path(temp_dir) / "test_config.json"
+
+            # Test with tracking enabled
+            config_data = self.create_test_config(temp_dir, track_assets=True)
+            with open(config_file, 'w') as f:
+                json.dump(config_data, f, indent=2)
+
+            print("1. Testing config with asset tracking enabled...")
+            downloader = ConfigImageDownloader(str(config_file))
+
+            if downloader.asset_tracker:
+                print("   ✅ Asset tracker initialized successfully")
+            else:
+                print("   ❌ Asset tracker not initialized")
+                return False
+
+            # Test with tracking disabled
+            config_data = self.create_test_config(temp_dir, track_assets=False)
+            with open(config_file, 'w') as f:
+                json.dump(config_data, f, indent=2)
+
+            print("\n2. Testing config with asset tracking disabled...")
+            downloader2 = ConfigImageDownloader(str(config_file))
+
+            if not downloader2.asset_tracker:
+                print("   ✅ Asset tracker correctly disabled")
+            else:
+                print("   ❌ Asset tracker should be disabled")
+                return False
+
+            print("\n✅ Configuration loading test passed!")
+            return True
+
+    def test_config_default_behavior(self):
+        """Test that asset tracking is enabled by default."""
+        print("\n" + "=" * 60)
+        print("TEST 2: Default Behavior")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            config_file = Path(temp_dir) / "test_config.json"
+
+            # Create config without track_assets field
+            config_data = self.create_test_config(temp_dir)
+            del config_data['track_assets']  # Remove the field entirely
+
+            with open(config_file, 'w') as f:
+                json.dump(config_data, f, indent=2)
+
+            print("1. Testing config without track_assets field (should default to True)...")
+            downloader = ConfigImageDownloader(str(config_file))
+
+            if downloader.asset_tracker:
+                print("   ✅ Asset tracking enabled by default")
+            else:
+                print("   ❌ Asset tracking should be enabled by default")
+                return False
+
+            print("\n✅ Default behavior test passed!")
+            return True
+
+    async def test_mock_download_with_tracking(self):
+        """Test download functionality with asset tracking using mock data."""
+        print("\n" + "=" * 60)
+        print("TEST 3: Mock Download with Tracking")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            config_file = Path(temp_dir) / "test_config.json"
+
+            # Create config with tracking enabled
+            config_data = self.create_test_config(temp_dir, track_assets=True)
+            with open(config_file, 'w') as f:
+                json.dump(config_data, f, indent=2)
+
+            print("1. Creating ConfigImageDownloader with tracking enabled...")
+            downloader = ConfigImageDownloader(str(config_file))
+
+            if not downloader.asset_tracker:
+                print("   ❌ Asset tracker not initialized")
+                return False
+
+            print("   ✅ Config downloader with asset tracker created")
+
+            # Test the asset tracker directly
+            print("\n2. Testing asset tracker integration...")
+            mock_assets = [
+                {
+                    "id": "config_test_001",
+                    "name": "test_image_1.jpg",
+                    "updated": "2024-01-01T10:00:00Z",
+                    "size": 1024000,
+                    "mimeType": "image/jpeg"
+                },
+                {
+                    "id": "config_test_002",
+                    "name": "test_image_2.jpg",
+                    "updated": "2024-01-02T11:00:00Z",
+                    "size": 2048000,
+                    "mimeType": "image/jpeg"
+                }
+            ]
+
+            # First check - should find all assets as new
+            new_assets = downloader.asset_tracker.get_new_assets(mock_assets)
+            print(f"   First check: Found {len(new_assets)} new assets (expected: 2)")
+
+            if len(new_assets) != 2:
+                print("   ❌ Should have found 2 new assets")
+                return False
+
+            # Simulate marking assets as downloaded
+            print("\n3. Simulating asset downloads...")
+            for asset in mock_assets:
+                filepath = Path(temp_dir) / asset['name']
+                filepath.write_text(f"Mock content for {asset['id']}")
+                downloader.asset_tracker.mark_asset_downloaded(asset, filepath, True)
+                print(f"   Marked as downloaded: {asset['name']}")
+
+            # Second check - should find no new assets
+            print("\n4. Second check for new assets...")
+            new_assets = downloader.asset_tracker.get_new_assets(mock_assets)
+            print(f"   Second check: Found {len(new_assets)} new assets (expected: 0)")
+
+            if len(new_assets) != 0:
+                print("   ❌ Should have found 0 new assets")
+                return False
+
+            print("   ✅ Asset tracking working correctly in config downloader")
+
+            # Check statistics
+            print("\n5. Checking statistics...")
+            stats = downloader.asset_tracker.get_stats()
+            print(f"   Total tracked assets: {stats['total_tracked_assets']}")
+            print(f"   Successful downloads: {stats['successful_downloads']}")
+            print(f"   Existing files: {stats['existing_files']}")
+
+            if stats['total_tracked_assets'] != 2:
+                print("   ❌ Should have 2 tracked assets")
+                return False
+
+            print("   ✅ Statistics correct")
+            print("\n✅ Mock download with tracking test passed!")
+            return True
+
+    def test_command_line_options(self):
+        """Test the new command line options."""
+        print("\n" + "=" * 60)
+        print("TEST 4: Command Line Options")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            config_file = Path(temp_dir) / "test_config.json"
+
+            # Create config with tracking enabled
+            config_data = self.create_test_config(temp_dir, track_assets=True)
+            with open(config_file, 'w') as f:
+                json.dump(config_data, f, indent=2)
+
+            print("1. Testing --show-stats option...")
+            try:
+                # Import the main function to test command line parsing
+                from config_downloader import main
+                import sys
+
+                # Backup original argv
+                original_argv = sys.argv.copy()
+
+                # Test show-stats option
+                sys.argv = ['config_downloader.py', '--config', str(config_file), '--show-stats']
+
+                # This would normally call main(), but we'll just check the parsing works
+                print("   ✅ Command line parsing would work for --show-stats")
+
+                # Test cleanup option
+                sys.argv = ['config_downloader.py', '--config', str(config_file), '--cleanup']
+                print("   ✅ Command line parsing would work for --cleanup")
+
+                # Test force-redownload option
+                sys.argv = ['config_downloader.py', '--config', str(config_file), '--force-redownload']
+                print("   ✅ Command line parsing would work for --force-redownload")
+
+                # Restore original argv
+                sys.argv = original_argv
+
+            except Exception as e:
+                print(f"   ❌ Command line parsing failed: {e}")
+                return False
+
+            print("\n✅ Command line options test passed!")
+            return True
+
+    def run_all_tests(self):
+        """Run all tests."""
+        print("🚀 Starting Config Downloader Asset Tracking Tests")
+        print("=" * 80)
+
+        try:
+            success = True
+
+            success &= self.test_config_loading()
+            success &= self.test_config_default_behavior()
+            success &= asyncio.run(self.test_mock_download_with_tracking())
+            success &= self.test_command_line_options()
+
+            if success:
+                print("\n" + "=" * 80)
+                print("🎉 ALL CONFIG DOWNLOADER TESTS PASSED!")
+                print("=" * 80)
+                print("✅ Asset tracking is now properly integrated into config_downloader.py")
+                print("✅ The config downloader will now skip already downloaded assets")
+                print("✅ Command line options for tracking control are available")
+            else:
+                print("\n❌ SOME TESTS FAILED")
+
+            return success
+
+        except Exception as e:
+            print(f"\n❌ TEST FAILED: {e}")
+            import traceback
+            traceback.print_exc()
+            return False
+
+
+def show_usage_instructions():
+    """Show usage instructions for the updated config downloader."""
+    print("\n" + "=" * 80)
+    print("📋 UPDATED CONFIG DOWNLOADER USAGE")
+    print("=" * 80)
+
+    print("\n🔧 Configuration File:")
+    print("Add 'track_assets': true to your config JSON file:")
+    print("""
+{
+  "api_url": "https://api.parentzone.me",
+  "list_endpoint": "/v1/media/list",
+  "download_endpoint": "/v1/media",
+  "output_dir": "./parentzone_images",
+  "max_concurrent": 5,
+  "timeout": 30,
+  "track_assets": true,
+  "email": "your_email@example.com",
+  "password": "your_password"
+}
+""")
+
+    print("\n💻 Command Line Usage:")
+    print("# Normal download (only new/modified assets):")
+    print("python3 config_downloader.py --config parentzone_config.json")
+    print()
+    print("# Force download all assets:")
+    print("python3 config_downloader.py --config parentzone_config.json --force-redownload")
+    print()
+    print("# Show asset statistics:")
+    print("python3 config_downloader.py --config parentzone_config.json --show-stats")
+    print()
+    print("# Clean up missing files:")
+    print("python3 config_downloader.py --config parentzone_config.json --cleanup")
+
+    print("\n✨ Benefits:")
+    print("• First run: Downloads all assets")
+    print("• Subsequent runs: Only downloads new/modified assets")
+    print("• Significant time and bandwidth savings")
+    print("• Automatic tracking of download history")
+
+
+def main():
+    """Main test function."""
+    # Setup logging
+    logging.basicConfig(
+        level=logging.INFO,
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+    )
+
+    tester = ConfigTrackingTester()
+
+    # Run unit tests
+    success = tester.run_all_tests()
+
+    # Show usage instructions
+    if success:
+        show_usage_instructions()
+
+    return 0 if success else 1
+
+
+if __name__ == "__main__":
+    exit(main())

tests/test_file_timestamps.py

@@ -0,0 +1,399 @@
+#!/usr/bin/env python3
+"""
+Test File Timestamps Functionality
+
+This script tests that downloaded files get their modification times set correctly
+based on the 'updated' field from the API response.
+"""
+
+import asyncio
+import json
+import logging
+import sys
+import tempfile
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+# Add the current directory to the path so we can import modules
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from config_downloader import ConfigImageDownloader
+from image_downloader import ImageDownloader
+from auth_manager import AuthManager
+
+
+class FileTimestampTester:
+    """Test class for file timestamp functionality."""
+
+    def __init__(self):
+        """Initialize the tester."""
+        self.logger = logging.getLogger(__name__)
+
+    def create_mock_asset(self, asset_id: str, filename: str, updated_time: str) -> dict:
+        """Create a mock asset with specific timestamp."""
+        return {
+            "id": asset_id,
+            "name": filename,
+            "fileName": filename,
+            "updated": updated_time,
+            "size": 1024000,
+            "mimeType": "image/jpeg",
+            "url": f"https://example.com/{asset_id}"
+        }
+
+    def test_timestamp_parsing(self):
+        """Test that timestamp parsing works correctly."""
+        print("=" * 60)
+        print("TEST 1: Timestamp Parsing")
+        print("=" * 60)
+
+        test_timestamps = [
+            "2024-01-15T10:30:00Z",           # Standard UTC format
+            "2024-01-15T10:30:00.123Z",       # With milliseconds
+            "2024-01-15T10:30:00+00:00",      # Explicit UTC timezone
+            "2024-01-15T12:30:00+02:00",      # With timezone offset
+            "2023-12-25T18:45:30.500Z"        # Christmas example
+        ]
+
+        for i, timestamp in enumerate(test_timestamps, 1):
+            print(f"\n{i}. Testing timestamp: {timestamp}")
+
+            try:
+                # This is the same parsing logic used in the downloaders
+                parsed_time = datetime.fromisoformat(timestamp.replace('Z', '+00:00'))
+                unix_timestamp = parsed_time.timestamp()
+
+                print(f"   Parsed datetime: {parsed_time}")
+                print(f"   Unix timestamp: {unix_timestamp}")
+                print(f"   ✅ Successfully parsed")
+
+            except Exception as e:
+                print(f"   ❌ Failed to parse: {e}")
+                return False
+
+        print("\n✅ All timestamp formats parsed successfully!")
+        return True
+
+    async def test_real_api_timestamps(self):
+        """Test with real API data to see what timestamp fields are available."""
+        print("\n" + "=" * 60)
+        print("TEST 2: Real API Timestamp Fields")
+        print("=" * 60)
+
+        # Test credentials
+        email = "tudor.sitaru@gmail.com"
+        password = "mTVq8uNUvY7R39EPGVAm@"
+
+        try:
+            print("1. Authenticating with ParentZone API...")
+            auth_manager = AuthManager()
+            success = await auth_manager.login(email, password)
+
+            if not success:
+                print("   ❌ Authentication failed - skipping real API test")
+                return True  # Not a failure, just skip
+
+            print("   ✅ Authentication successful")
+
+            print("\n2. Fetching asset list to examine timestamp fields...")
+
+            # Use a temporary downloader just to get the asset list
+            with tempfile.TemporaryDirectory() as temp_dir:
+                downloader = ImageDownloader(
+                    api_url="https://api.parentzone.me",
+                    list_endpoint="/v1/media/list",
+                    download_endpoint="/v1/media",
+                    output_dir=temp_dir,
+                    email=email,
+                    password=password,
+                    track_assets=False
+                )
+
+                # Get asset list
+                import aiohttp
+                connector = aiohttp.TCPConnector(limit=100, limit_per_host=30)
+                timeout = aiohttp.ClientTimeout(total=30)
+
+                async with aiohttp.ClientSession(connector=connector, timeout=timeout) as session:
+                    await downloader.authenticate()
+                    assets = await downloader.get_asset_list(session)
+
+                if assets:
+                    print(f"   Retrieved {len(assets)} assets")
+
+                    # Examine first few assets for timestamp fields
+                    print("\n3. Examining timestamp-related fields in assets:")
+
+                    timestamp_fields = ['updated', 'created', 'modified', 'lastModified', 'createdAt', 'updatedAt']
+
+                    for i, asset in enumerate(assets[:3]):  # Check first 3 assets
+                        print(f"\n   Asset {i+1} (ID: {asset.get('id', 'unknown')[:20]}...):")
+
+                        found_timestamps = False
+                        for field in timestamp_fields:
+                            if field in asset:
+                                print(f"     {field}: {asset[field]}")
+                                found_timestamps = True
+
+                        if not found_timestamps:
+                            print("     No timestamp fields found")
+                            print(f"     Available fields: {list(asset.keys())}")
+
+                    print("\n   ✅ Real API timestamp fields examined")
+                else:
+                    print("   ⚠️ No assets retrieved from API")
+
+        except Exception as e:
+            print(f"   ❌ Real API test failed: {e}")
+            # This is not a critical failure for the test suite
+            return True
+
+        return True
+
+    def test_file_modification_setting(self):
+        """Test that file modification times are set correctly."""
+        print("\n" + "=" * 60)
+        print("TEST 3: File Modification Time Setting")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            print(f"Working in temporary directory: {temp_dir}")
+
+            # Test different timestamp scenarios
+            test_cases = [
+                {
+                    "name": "Standard UTC timestamp",
+                    "timestamp": "2024-01-15T10:30:00Z",
+                    "filename": "test_standard.jpg"
+                },
+                {
+                    "name": "Timestamp with milliseconds",
+                    "timestamp": "2024-02-20T14:45:30.123Z",
+                    "filename": "test_milliseconds.jpg"
+                },
+                {
+                    "name": "Timestamp with timezone offset",
+                    "timestamp": "2024-03-10T16:20:00+02:00",
+                    "filename": "test_timezone.jpg"
+                }
+            ]
+
+            for i, test_case in enumerate(test_cases, 1):
+                print(f"\n{i}. Testing: {test_case['name']}")
+                print(f"   Timestamp: {test_case['timestamp']}")
+
+                # Create test file
+                test_file = Path(temp_dir) / test_case['filename']
+                test_file.write_text("Mock image content")
+
+                try:
+                    # Apply the same logic as the downloaders
+                    from datetime import datetime
+                    import os
+
+                    # Parse the ISO timestamp (same as downloader code)
+                    updated_time = datetime.fromisoformat(test_case['timestamp'].replace('Z', '+00:00'))
+
+                    # Set file modification time (same as downloader code)
+                    os.utime(test_file, (updated_time.timestamp(), updated_time.timestamp()))
+
+                    # Verify the modification time was set correctly
+                    file_stat = test_file.stat()
+                    file_mtime = datetime.fromtimestamp(file_stat.st_mtime, tz=timezone.utc)
+
+                    print(f"   Expected: {updated_time}")
+                    print(f"   Actual:   {file_mtime}")
+
+                    # Allow small difference due to filesystem precision
+                    time_diff = abs((file_mtime - updated_time.replace(tzinfo=timezone.utc)).total_seconds())
+
+                    if time_diff < 2.0:  # Within 2 seconds
+                        print(f"   ✅ Modification time set correctly (diff: {time_diff:.3f}s)")
+                    else:
+                        print(f"   ❌ Modification time mismatch (diff: {time_diff:.3f}s)")
+                        return False
+
+                except Exception as e:
+                    print(f"   ❌ Failed to set modification time: {e}")
+                    return False
+
+        print("\n✅ File modification time setting test passed!")
+        return True
+
+    def test_missing_timestamp_handling(self):
+        """Test behavior when timestamp field is missing."""
+        print("\n" + "=" * 60)
+        print("TEST 4: Missing Timestamp Handling")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            print("1. Testing asset without 'updated' field...")
+
+            # Create asset without timestamp
+            asset_no_timestamp = {
+                "id": "test_no_timestamp",
+                "name": "no_timestamp.jpg",
+                "size": 1024000,
+                "mimeType": "image/jpeg"
+            }
+
+            test_file = Path(temp_dir) / "no_timestamp.jpg"
+            test_file.write_text("Mock image content")
+
+            # Record original modification time
+            original_mtime = test_file.stat().st_mtime
+
+            print(f"   Original file mtime: {datetime.fromtimestamp(original_mtime)}")
+
+            # Simulate the downloader logic
+            if 'updated' in asset_no_timestamp:
+                print("   This shouldn't happen - asset has 'updated' field")
+                return False
+            else:
+                print("   ✅ Correctly detected missing 'updated' field")
+                print("   ✅ File modification time left unchanged (as expected)")
+
+            # Verify file time wasn't changed
+            new_mtime = test_file.stat().st_mtime
+            if abs(new_mtime - original_mtime) < 1.0:
+                print("   ✅ File modification time preserved when timestamp missing")
+            else:
+                print("   ❌ File modification time unexpectedly changed")
+                return False
+
+        print("\n✅ Missing timestamp handling test passed!")
+        return True
+
+    def test_timestamp_error_handling(self):
+        """Test error handling for invalid timestamps."""
+        print("\n" + "=" * 60)
+        print("TEST 5: Invalid Timestamp Error Handling")
+        print("=" * 60)
+
+        invalid_timestamps = [
+            "not-a-timestamp",
+            "2024-13-45T25:70:90Z",  # Invalid date/time
+            "2024-01-15",            # Missing time
+            "",                      # Empty string
+            "2024-01-15T10:30:00X"   # Invalid timezone
+        ]
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            for i, invalid_timestamp in enumerate(invalid_timestamps, 1):
+                print(f"\n{i}. Testing invalid timestamp: '{invalid_timestamp}'")
+
+                test_file = Path(temp_dir) / f"test_invalid_{i}.jpg"
+                test_file.write_text("Mock image content")
+
+                original_mtime = test_file.stat().st_mtime
+
+                try:
+                    # This should fail gracefully (same as downloader code)
+                    from datetime import datetime
+                    import os
+
+                    updated_time = datetime.fromisoformat(invalid_timestamp.replace('Z', '+00:00'))
+                    os.utime(test_file, (updated_time.timestamp(), updated_time.timestamp()))
+
+                    print(f"   ⚠️ Unexpectedly succeeded parsing invalid timestamp")
+
+                except Exception as e:
+                    print(f"   ✅ Correctly failed with error: {type(e).__name__}")
+
+                    # Verify file time wasn't changed
+                    new_mtime = test_file.stat().st_mtime
+                    if abs(new_mtime - original_mtime) < 1.0:
+                        print(f"   ✅ File modification time preserved after error")
+                    else:
+                        print(f"   ❌ File modification time unexpectedly changed")
+                        return False
+
+        print("\n✅ Invalid timestamp error handling test passed!")
+        return True
+
+    async def run_all_tests(self):
+        """Run all timestamp-related tests."""
+        print("🚀 Starting File Timestamp Tests")
+        print("=" * 80)
+
+        try:
+            success = True
+
+            success &= self.test_timestamp_parsing()
+            success &= await self.test_real_api_timestamps()
+            success &= self.test_file_modification_setting()
+            success &= self.test_missing_timestamp_handling()
+            success &= self.test_timestamp_error_handling()
+
+            if success:
+                print("\n" + "=" * 80)
+                print("🎉 ALL TIMESTAMP TESTS PASSED!")
+                print("=" * 80)
+                print("✅ File modification times are correctly set from API timestamps")
+                print("✅ Both config_downloader.py and image_downloader.py handle timestamps properly")
+                print("✅ Error handling works correctly for invalid/missing timestamps")
+                print("✅ Multiple timestamp formats are supported")
+            else:
+                print("\n❌ SOME TIMESTAMP TESTS FAILED")
+
+            return success
+
+        except Exception as e:
+            print(f"\n❌ TIMESTAMP TEST FAILED: {e}")
+            import traceback
+            traceback.print_exc()
+            return False
+
+
+def show_timestamp_info():
+    """Show information about timestamp handling."""
+    print("\n" + "=" * 80)
+    print("📅 FILE TIMESTAMP FUNCTIONALITY")
+    print("=" * 80)
+
+    print("\n🔍 How It Works:")
+    print("1. API returns asset with 'updated' field (ISO 8601 format)")
+    print("2. Downloader parses timestamp: datetime.fromisoformat(timestamp)")
+    print("3. File modification time set: os.utime(filepath, (timestamp, timestamp))")
+    print("4. Downloaded file shows correct modification date in file system")
+
+    print("\n📋 Supported Timestamp Formats:")
+    print("• 2024-01-15T10:30:00Z (UTC)")
+    print("• 2024-01-15T10:30:00.123Z (with milliseconds)")
+    print("• 2024-01-15T10:30:00+00:00 (explicit timezone)")
+    print("• 2024-01-15T12:30:00+02:00 (timezone offset)")
+
+    print("\n⚠️ Error Handling:")
+    print("• Missing 'updated' field → file keeps current modification time")
+    print("• Invalid timestamp format → error logged, file time unchanged")
+    print("• Network/parsing errors → gracefully handled, download continues")
+
+    print("\n🎯 Benefits:")
+    print("• File timestamps match original creation/update dates")
+    print("• Easier to organize and sort downloaded files chronologically")
+    print("• Consistent with original asset metadata from ParentZone")
+
+
+def main():
+    """Main test function."""
+    # Setup logging
+    logging.basicConfig(
+        level=logging.INFO,
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+    )
+
+    tester = FileTimestampTester()
+
+    # Run tests
+    success = asyncio.run(tester.run_all_tests())
+
+    # Show information
+    if success:
+        show_timestamp_info()
+
+    return 0 if success else 1
+
+
+if __name__ == "__main__":
+    exit(main())

tests/test_html_rendering.py

@@ -0,0 +1,386 @@
+#!/usr/bin/env python3
+"""
+Test HTML Rendering in Notes Field
+
+This script tests that the notes field HTML content is properly rendered
+in the output HTML file instead of being escaped.
+"""
+
+import asyncio
+import json
+import logging
+import sys
+import tempfile
+from pathlib import Path
+import os
+
+# Add the current directory to the path so we can import modules
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from snapshot_downloader import SnapshotDownloader
+
+
+class HTMLRenderingTester:
+    """Test class for HTML rendering functionality."""
+
+    def __init__(self):
+        """Initialize the tester."""
+        self.logger = logging.getLogger(__name__)
+
+    def test_notes_html_rendering(self):
+        """Test that HTML in notes field is properly rendered."""
+        print("=" * 60)
+        print("TEST: HTML Rendering in Notes Field")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            downloader = SnapshotDownloader(output_dir=temp_dir)
+
+            print("1. Testing snapshot with HTML content in notes...")
+
+            # Create mock snapshot with HTML content in notes
+            mock_snapshot = {
+                "id": "test_html_rendering",
+                "type": "Snapshot",
+                "code": "Snapshot",
+                "child": {
+                    "forename": "Test",
+                    "surname": "Child"
+                },
+                "author": {
+                    "forename": "Test",
+                    "surname": "Teacher"
+                },
+                "startTime": "2024-01-15T10:30:00",
+                "notes": """<p>This is a <strong>bold</strong> statement about the child's progress.</p>
+<p><br></p>
+<p>The child demonstrated <em>excellent</em> skills in:</p>
+<p>• Communication</p>
+<p>• Problem solving</p>
+<p><br></p>
+<p><span style="color: rgb(255, 0, 0);">Important note:</span> Continue encouraging creative play.</p>
+<p><span style="font-size: 14px;">Next steps: Focus on fine motor skills development.</span></p>""",
+                "frameworkIndicatorCount": 15,
+                "signed": False
+            }
+
+            # Generate HTML for the snapshot
+            html_content = downloader.format_snapshot_html(mock_snapshot)
+
+            print("2. Checking HTML content rendering...")
+
+            # Check that HTML tags are NOT escaped (should be rendered) within notes-content
+            if 'notes-content"><p>' in html_content or 'notes-content"><strong>' in html_content:
+                print("   ✅ HTML paragraph tags are rendered (not escaped)")
+            else:
+                print("   ❌ HTML paragraph tags are escaped instead of rendered")
+                # Debug output to see what we actually got
+                start = html_content.find('notes-content')
+                if start != -1:
+                    sample = html_content[start:start+150]
+                    print(f"   Debug - Found: {sample}")
+                return False
+
+            if "<strong>bold</strong>" in html_content:
+                print("   ✅ HTML strong tags are rendered (not escaped)")
+            else:
+                print("   ❌ HTML strong tags are escaped instead of rendered")
+                return False
+
+            if "<em>excellent</em>" in html_content:
+                print("   ✅ HTML emphasis tags are rendered (not escaped)")
+            else:
+                print("   ❌ HTML emphasis tags are escaped instead of rendered")
+                return False
+
+            if 'style="color: rgb(255, 0, 0);"' in html_content:
+                print("   ✅ Inline CSS styles are preserved")
+            else:
+                print("   ❌ Inline CSS styles are not preserved")
+                return False
+
+            print("\n3. Testing complete HTML file generation...")
+
+            # Generate complete HTML file
+            mock_snapshots = [mock_snapshot]
+            html_file = downloader.generate_html_file(
+                mock_snapshots, "2024-01-01", "2024-01-31"
+            )
+
+            if html_file.exists():
+                print("   ✅ HTML file created successfully")
+
+                # Read and check file content
+                with open(html_file, 'r', encoding='utf-8') as f:
+                    file_content = f.read()
+
+                # Check for proper HTML structure
+                if 'class="notes-content"' in file_content:
+                    print("   ✅ Notes content wrapper class present")
+                else:
+                    print("   ❌ Notes content wrapper class missing")
+                    return False
+
+                # Check that HTML content is rendered in the file
+                if "<p>This is a <strong>bold</strong> statement" in file_content:
+                    print("   ✅ HTML content properly rendered in file")
+                else:
+                    print("   ❌ HTML content not properly rendered in file")
+                    print("   Debug: Looking for HTML content in file...")
+                    # Show a sample of the content for debugging
+                    start = file_content.find('notes-content')
+                    if start != -1:
+                        sample = file_content[start:start+200]
+                        print(f"   Sample content: {sample}")
+                    return False
+
+                # Check for CSS styles that handle HTML content
+                if ".notes-content" in file_content:
+                    print("   ✅ CSS styles for notes content included")
+                else:
+                    print("   ❌ CSS styles for notes content missing")
+                    return False
+
+            else:
+                print("   ❌ HTML file was not created")
+                return False
+
+            print("\n4. Testing XSS safety with potentially dangerous content...")
+
+            # Test with potentially dangerous content to ensure basic safety
+            dangerous_snapshot = {
+                "id": "test_xss_safety",
+                "type": "Snapshot",
+                "startTime": "2024-01-15T10:30:00",
+                "notes": '<p>Safe content</p><script>alert("xss")</script><p>More safe content</p>',
+            }
+
+            dangerous_html = downloader.format_snapshot_html(dangerous_snapshot)
+
+            # The script tag should still be present (we're not sanitizing, just rendering)
+            # But we should document this as a security consideration
+            if '<script>' in dangerous_html:
+                print("   ⚠️  Script tags are rendered (consider content sanitization for production)")
+            else:
+                print("   ✅ Script tags are filtered/escaped")
+
+        print("\n✅ HTML rendering test completed!")
+        return True
+
+    def test_complex_html_scenarios(self):
+        """Test various complex HTML scenarios."""
+        print("\n" + "=" * 60)
+        print("TEST: Complex HTML Scenarios")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            downloader = SnapshotDownloader(output_dir=temp_dir)
+
+            test_cases = [
+                {
+                    "name": "Nested HTML Tags",
+                    "notes": '<p>Child showed <strong>excellent <em>progress</em></strong> today.</p>',
+                    "should_contain": ['<strong>', '<em>', 'excellent', 'progress']
+                },
+                {
+                    "name": "Line Breaks and Paragraphs",
+                    "notes": '<p>First paragraph.</p><p><br></p><p>Second paragraph after break.</p>',
+                    "should_contain": ['<p>First paragraph.</p>', '<p><br></p>', '<p>Second paragraph']
+                },
+                {
+                    "name": "Styled Text",
+                    "notes": '<p><span style="color: rgb(0, 0, 255); font-size: 16px;">Blue text</span></p>',
+                    "should_contain": ['style="color: rgb(0, 0, 255)', 'font-size: 16px', 'Blue text']
+                },
+                {
+                    "name": "Mixed Content",
+                    "notes": '<p>Normal text</p><p>• Bullet point 1</p><p>• Bullet point 2</p><p><strong>Next steps:</strong> Continue activities.</p>',
+                    "should_contain": ['Normal text', '• Bullet', '<strong>Next steps:</strong>']
+                }
+            ]
+
+            for i, test_case in enumerate(test_cases, 1):
+                print(f"\n{i}. Testing: {test_case['name']}")
+
+                mock_snapshot = {
+                    "id": f"test_case_{i}",
+                    "type": "Snapshot",
+                    "startTime": "2024-01-15T10:30:00",
+                    "notes": test_case['notes']
+                }
+
+                html_content = downloader.format_snapshot_html(mock_snapshot)
+
+                # Check that all expected content is present and rendered
+                all_found = True
+                for expected in test_case['should_contain']:
+                    if expected in html_content:
+                        print(f"   ✅ Found: {expected[:30]}...")
+                    else:
+                        print(f"   ❌ Missing: {expected[:30]}...")
+                        all_found = False
+
+                if not all_found:
+                    print(f"   ❌ Test case '{test_case['name']}' failed")
+                    return False
+                else:
+                    print(f"   ✅ Test case '{test_case['name']}' passed")
+
+        print("\n✅ Complex HTML scenarios test completed!")
+        return True
+
+    def test_empty_and_edge_cases(self):
+        """Test edge cases for notes field."""
+        print("\n" + "=" * 60)
+        print("TEST: Edge Cases")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            downloader = SnapshotDownloader(output_dir=temp_dir)
+
+            edge_cases = [
+                {
+                    "name": "Empty notes",
+                    "notes": "",
+                    "expected": "No description provided"
+                },
+                {
+                    "name": "None notes",
+                    "notes": None,
+                    "expected": "No description provided"
+                },
+                {
+                    "name": "Only whitespace",
+                    "notes": "   \n\t   ",
+                    "expected": "   \n\t   "  # Should preserve whitespace
+                },
+                {
+                    "name": "Plain text (no HTML)",
+                    "notes": "Just plain text without HTML tags.",
+                    "expected": "Just plain text without HTML tags."
+                }
+            ]
+
+            for i, test_case in enumerate(edge_cases, 1):
+                print(f"\n{i}. Testing: {test_case['name']}")
+
+                mock_snapshot = {
+                    "id": f"edge_case_{i}",
+                    "type": "Snapshot",
+                    "startTime": "2024-01-15T10:30:00"
+                }
+
+                if test_case['notes'] is not None:
+                    mock_snapshot['notes'] = test_case['notes']
+
+                html_content = downloader.format_snapshot_html(mock_snapshot)
+
+                if test_case['expected'] in html_content:
+                    print(f"   ✅ Correctly handled: {test_case['name']}")
+                else:
+                    print(f"   ❌ Failed: {test_case['name']}")
+                    print(f"   Expected: {test_case['expected']}")
+                    # Show relevant part of HTML for debugging
+                    start = html_content.find('notes-content')
+                    if start != -1:
+                        sample = html_content[start:start+100]
+                        print(f"   Found: {sample}")
+                    return False
+
+        print("\n✅ Edge cases test completed!")
+        return True
+
+    def run_all_tests(self):
+        """Run all HTML rendering tests."""
+        print("🚀 Starting HTML Rendering Tests")
+        print("=" * 80)
+
+        try:
+            success = True
+
+            success &= self.test_notes_html_rendering()
+            success &= self.test_complex_html_scenarios()
+            success &= self.test_empty_and_edge_cases()
+
+            if success:
+                print("\n" + "=" * 80)
+                print("🎉 ALL HTML RENDERING TESTS PASSED!")
+                print("=" * 80)
+                print("✅ HTML content in notes field is properly rendered")
+                print("✅ Complex HTML scenarios work correctly")
+                print("✅ Edge cases are handled appropriately")
+                print("✅ CSS styles support HTML content rendering")
+                print("\n⚠️  Security Note:")
+                print("   HTML content is rendered as-is for rich formatting.")
+                print("   Consider content sanitization if accepting user input.")
+            else:
+                print("\n❌ SOME HTML RENDERING TESTS FAILED")
+
+            return success
+
+        except Exception as e:
+            print(f"\n❌ HTML RENDERING TESTS FAILED: {e}")
+            import traceback
+            traceback.print_exc()
+            return False
+
+
+def show_html_rendering_info():
+    """Show information about HTML rendering in notes."""
+    print("\n" + "=" * 80)
+    print("📝 HTML RENDERING IN NOTES FIELD")
+    print("=" * 80)
+
+    print("\n🎨 What's Rendered:")
+    print("• <p> tags for paragraphs")
+    print("• <strong> and <em> for bold/italic text")
+    print("• <br> tags for line breaks")
+    print("• <span> with style attributes for colors/fonts")
+    print("• Bullet points and lists")
+    print("• All inline CSS styles")
+
+    print("\n💡 Example HTML Content:")
+    print('<p>Child showed <strong>excellent</strong> progress today.</p>')
+    print('<p><br></p>')
+    print('<p><span style="color: rgb(255, 0, 0);">Important:</span> Continue activities.</p>')
+
+    print("\n📋 Becomes:")
+    print("Child showed excellent progress today.")
+    print("")
+    print("Important: Continue activities. (in red)")
+
+    print("\n🔒 Security Considerations:")
+    print("• HTML content is rendered as-is from the API")
+    print("• Content comes from trusted ParentZone staff")
+    print("• Script tags and other content are preserved")
+    print("• Consider sanitization for untrusted input")
+
+    print("\n🎯 Benefits:")
+    print("• Rich text formatting preserved")
+    print("• Professional-looking reports")
+    print("• Colors and styling from original content")
+    print("• Better readability and presentation")
+
+
+def main():
+    """Main test function."""
+    # Setup logging
+    logging.basicConfig(
+        level=logging.INFO,
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+    )
+
+    tester = HTMLRenderingTester()
+
+    # Run tests
+    success = tester.run_all_tests()
+
+    # Show information
+    if success:
+        show_html_rendering_info()
+
+    return 0 if success else 1
+
+
+if __name__ == "__main__":
+    exit(main())

tests/test_login.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""
+Test Login Functionality
+
+This script tests the login authentication for the ParentZone API.
+"""
+
+import asyncio
+import sys
+import os
+
+# Add the current directory to the path so we can import auth_manager
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from auth_manager import AuthManager
+
+
+async def test_login():
+    """Test the login functionality."""
+    print("=" * 60)
+    print("ParentZone Login Test")
+    print("=" * 60)
+
+    auth_manager = AuthManager()
+
+    # Test credentials
+    email = "tudor.sitaru@gmail.com"
+    password = "mTVq8uNUvY7R39EPGVAm@"
+
+    print(f"Testing login for: {email}")
+
+    try:
+        success = await auth_manager.login(email, password)
+
+        if success:
+            print("✅ Login successful!")
+            print(f"User: {auth_manager.user_name}")
+            print(f"Provider: {auth_manager.provider_name}")
+            print(f"User ID: {auth_manager.user_id}")
+            print(f"API Key: {auth_manager.api_key[:20]}..." if auth_manager.api_key else "No API key found")
+
+            # Test getting auth headers
+            headers = auth_manager.get_auth_headers()
+            print(f"Auth headers: {list(headers.keys())}")
+            if 'x-api-key' in headers:
+                print(f"✅ x-api-key header present: {headers['x-api-key'][:20]}...")
+            if 'x-api-product' in headers:
+                print(f"✅ x-api-product header: {headers['x-api-product']}")
+
+            # Test if authenticated
+            if auth_manager.is_authenticated():
+                print("✅ Authentication status: Authenticated")
+            else:
+                print("❌ Authentication status: Not authenticated")
+
+        else:
+            print("❌ Login failed!")
+            return False
+
+    except Exception as e:
+        print(f"❌ Login error: {e}")
+        return False
+
+    print("\n" + "=" * 60)
+    print("LOGIN TEST COMPLETE")
+    print("=" * 60)
+
+    return success
+
+
+if __name__ == "__main__":
+    success = asyncio.run(test_login())
+    sys.exit(0 if success else 1)

tests/test_media_download.py

@@ -0,0 +1,495 @@
+#!/usr/bin/env python3
+"""
+Test Media Download Functionality
+
+This script tests that media files (images and attachments) are properly downloaded
+to the assets subfolder and referenced correctly in the HTML output.
+"""
+
+import asyncio
+import json
+import logging
+import sys
+import tempfile
+from pathlib import Path
+import os
+from unittest.mock import AsyncMock, MagicMock
+
+# Add the current directory to the path so we can import modules
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from snapshot_downloader import SnapshotDownloader
+
+
+class MediaDownloadTester:
+    """Test class for media download functionality."""
+
+    def __init__(self):
+        """Initialize the tester."""
+        self.logger = logging.getLogger(__name__)
+
+    def test_assets_folder_creation(self):
+        """Test that assets subfolder is created correctly."""
+        print("=" * 60)
+        print("TEST: Assets Folder Creation")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            print("1. Testing assets folder creation...")
+
+            downloader = SnapshotDownloader(output_dir=temp_dir)
+
+            # Check if assets folder was created
+            assets_dir = Path(temp_dir) / "assets"
+            if assets_dir.exists() and assets_dir.is_dir():
+                print("   ✅ Assets folder created successfully")
+            else:
+                print("   ❌ Assets folder not created")
+                return False
+
+            # Check if it's accessible
+            if downloader.assets_dir == assets_dir:
+                print("   ✅ Assets directory property set correctly")
+            else:
+                print("   ❌ Assets directory property incorrect")
+                return False
+
+        print("\n✅ Assets folder creation test passed!")
+        return True
+
+    def test_filename_sanitization(self):
+        """Test filename sanitization functionality."""
+        print("\n" + "=" * 60)
+        print("TEST: Filename Sanitization")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            downloader = SnapshotDownloader(output_dir=temp_dir)
+
+            test_cases = [
+                {
+                    "input": "normal_filename.jpg",
+                    "expected": "normal_filename.jpg",
+                    "description": "Normal filename"
+                },
+                {
+                    "input": "file<with>invalid:chars.png",
+                    "expected": "file_with_invalid_chars.png",
+                    "description": "Invalid characters"
+                },
+                {
+                    "input": "  .leading_trailing_spaces.  ",
+                    "expected": "leading_trailing_spaces",
+                    "description": "Leading/trailing spaces and dots"
+                },
+                {
+                    "input": "",
+                    "expected": "media_file",
+                    "description": "Empty filename"
+                },
+                {
+                    "input": "file/with\\path|chars?.txt",
+                    "expected": "file_with_path_chars_.txt",
+                    "description": "Path characters"
+                }
+            ]
+
+            print("1. Testing filename sanitization cases...")
+            for i, test_case in enumerate(test_cases, 1):
+                print(f"\n{i}. {test_case['description']}")
+                print(f"   Input: '{test_case['input']}'")
+
+                result = downloader._sanitize_filename(test_case['input'])
+                print(f"   Output: '{result}'")
+
+                if result == test_case['expected']:
+                    print("   ✅ Correctly sanitized")
+                else:
+                    print(f"   ❌ Expected: '{test_case['expected']}'")
+                    return False
+
+        print("\n✅ Filename sanitization test passed!")
+        return True
+
+    async def test_media_download_mock(self):
+        """Test media download with mocked HTTP responses."""
+        print("\n" + "=" * 60)
+        print("TEST: Media Download (Mocked)")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            downloader = SnapshotDownloader(output_dir=temp_dir)
+
+            print("1. Testing image download...")
+
+            # Mock media object
+            mock_media = {
+                "id": 794684,
+                "fileName": "test_image.jpeg",
+                "type": "image",
+                "mimeType": "image/jpeg",
+                "updated": "2025-07-31T12:46:24.413",
+                "status": "available",
+                "downloadable": True
+            }
+
+            # Create mock session and response
+            mock_response = AsyncMock()
+            mock_response.status = 200
+            mock_response.raise_for_status = MagicMock()
+
+            # Mock file content
+            fake_image_content = b"fake_image_data_for_testing"
+
+            async def mock_iter_chunked(chunk_size):
+                yield fake_image_content
+
+            mock_response.content.iter_chunked = mock_iter_chunked
+
+            mock_session = AsyncMock()
+            mock_session.get.return_value.__aenter__.return_value = mock_response
+
+            # Test the download
+            result = await downloader.download_media_file(mock_session, mock_media)
+
+            # Check result
+            if result == "assets/test_image.jpeg":
+                print("   ✅ Download returned correct relative path")
+            else:
+                print(f"   ❌ Expected 'assets/test_image.jpeg', got '{result}'")
+                return False
+
+            # Check file was created
+            expected_file = Path(temp_dir) / "assets" / "test_image.jpeg"
+            if expected_file.exists():
+                print("   ✅ File created in assets folder")
+
+                # Check file content
+                with open(expected_file, 'rb') as f:
+                    content = f.read()
+                if content == fake_image_content:
+                    print("   ✅ File content matches")
+                else:
+                    print("   ❌ File content doesn't match")
+                    return False
+            else:
+                print("   ❌ File not created")
+                return False
+
+            print("\n2. Testing existing file handling...")
+
+            # Test downloading the same file again (should return existing)
+            result2 = await downloader.download_media_file(mock_session, mock_media)
+            if result2 == "assets/test_image.jpeg":
+                print("   ✅ Existing file handling works")
+            else:
+                print("   ❌ Existing file handling failed")
+                return False
+
+            print("\n3. Testing download failure...")
+
+            # Test with invalid media (no ID)
+            invalid_media = {"fileName": "no_id_file.jpg"}
+            result3 = await downloader.download_media_file(mock_session, invalid_media)
+            if result3 is None:
+                print("   ✅ Properly handles invalid media")
+            else:
+                print("   ❌ Should return None for invalid media")
+                return False
+
+        print("\n✅ Media download mock test passed!")
+        return True
+
+    async def test_media_formatting_integration(self):
+        """Test media formatting with downloaded files."""
+        print("\n" + "=" * 60)
+        print("TEST: Media Formatting Integration")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            downloader = SnapshotDownloader(output_dir=temp_dir)
+
+            print("1. Testing snapshot with media formatting...")
+
+            # Create a test image file in assets
+            test_image_path = Path(temp_dir) / "assets" / "test_snapshot_image.jpeg"
+            test_image_path.parent.mkdir(exist_ok=True)
+            test_image_path.write_bytes(b"fake_image_content")
+
+            # Mock snapshot with media
+            mock_snapshot = {
+                "id": 123456,
+                "type": "Snapshot",
+                "child": {"forename": "Test", "surname": "Child"},
+                "author": {"forename": "Test", "surname": "Teacher"},
+                "startTime": "2024-01-15T10:30:00",
+                "notes": "<p>Test snapshot with media</p>",
+                "media": [
+                    {
+                        "id": 123456,
+                        "fileName": "test_snapshot_image.jpeg",
+                        "type": "image",
+                        "mimeType": "image/jpeg",
+                        "updated": "2024-01-15T10:30:00",
+                        "status": "available",
+                        "downloadable": True
+                    }
+                ]
+            }
+
+            # Mock session to simulate successful download
+            mock_session = AsyncMock()
+
+            # Override the download_media_file method to return our test path
+            original_download = downloader.download_media_file
+            async def mock_download(session, media):
+                if media.get('fileName') == 'test_snapshot_image.jpeg':
+                    return "assets/test_snapshot_image.jpeg"
+                return await original_download(session, media)
+
+            downloader.download_media_file = mock_download
+
+            # Test formatting
+            html_content = await downloader.format_snapshot_html(mock_snapshot, mock_session)
+
+            print("2. Checking HTML content for media references...")
+
+            # Check for local image reference
+            if 'src="assets/test_snapshot_image.jpeg"' in html_content:
+                print("   ✅ Local image path found in HTML")
+            else:
+                print("   ❌ Local image path not found")
+                print("   Debug: Looking for image references...")
+                if 'assets/' in html_content:
+                    print("   Found assets/ references in HTML")
+                if 'test_snapshot_image.jpeg' in html_content:
+                    print("   Found filename in HTML")
+                return False
+
+            # Check for image grid structure
+            if 'class="image-grid"' in html_content:
+                print("   ✅ Image grid structure present")
+            else:
+                print("   ❌ Image grid structure missing")
+                return False
+
+            # Check for image metadata
+            if 'class="image-caption"' in html_content and 'class="image-meta"' in html_content:
+                print("   ✅ Image caption and metadata present")
+            else:
+                print("   ❌ Image caption or metadata missing")
+                return False
+
+        print("\n✅ Media formatting integration test passed!")
+        return True
+
+    async def test_complete_html_generation_with_media(self):
+        """Test complete HTML generation with media downloads."""
+        print("\n" + "=" * 60)
+        print("TEST: Complete HTML Generation with Media")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            downloader = SnapshotDownloader(output_dir=temp_dir)
+
+            print("1. Setting up test environment...")
+
+            # Create test image files
+            test_images = ["image1.jpg", "image2.png"]
+            for img_name in test_images:
+                img_path = Path(temp_dir) / "assets" / img_name
+                img_path.write_bytes(f"fake_content_for_{img_name}".encode())
+
+            # Mock snapshots with media
+            mock_snapshots = [
+                {
+                    "id": 100001,
+                    "type": "Snapshot",
+                    "child": {"forename": "Alice", "surname": "Smith"},
+                    "author": {"forename": "Teacher", "surname": "One"},
+                    "startTime": "2024-01-15T10:30:00",
+                    "notes": "<p>Alice's first snapshot</p>",
+                    "media": [
+                        {
+                            "id": 1001,
+                            "fileName": "image1.jpg",
+                            "type": "image",
+                            "mimeType": "image/jpeg"
+                        }
+                    ]
+                },
+                {
+                    "id": 100002,
+                    "type": "Snapshot",
+                    "child": {"forename": "Bob", "surname": "Johnson"},
+                    "author": {"forename": "Teacher", "surname": "Two"},
+                    "startTime": "2024-01-16T14:20:00",
+                    "notes": "<p>Bob's creative work</p>",
+                    "media": [
+                        {
+                            "id": 1002,
+                            "fileName": "image2.png",
+                            "type": "image",
+                            "mimeType": "image/png"
+                        }
+                    ]
+                }
+            ]
+
+            # Mock the download_media_file method
+            async def mock_download_media(session, media):
+                filename = media.get('fileName', 'unknown.jpg')
+                if filename in test_images:
+                    return f"assets/{filename}"
+                return None
+
+            downloader.download_media_file = mock_download_media
+
+            print("2. Generating complete HTML file...")
+            html_file = await downloader.generate_html_file(mock_snapshots, "2024-01-01", "2024-12-31")
+
+            if html_file and html_file.exists():
+                print("   ✅ HTML file generated successfully")
+
+                with open(html_file, 'r', encoding='utf-8') as f:
+                    content = f.read()
+
+                print("3. Checking HTML content...")
+
+                # Check for local image references
+                checks = [
+                    ('src="assets/image1.jpg"', "Image 1 local reference"),
+                    ('src="assets/image2.png"', "Image 2 local reference"),
+                    ('Alice by Teacher One', "Snapshot 1 title"),
+                    ('Bob by Teacher Two', "Snapshot 2 title"),
+                    ('class="image-grid"', "Image grid structure"),
+                ]
+
+                all_passed = True
+                for check_text, description in checks:
+                    if check_text in content:
+                        print(f"   ✅ {description} found")
+                    else:
+                        print(f"   ❌ {description} missing")
+                        all_passed = False
+
+                if not all_passed:
+                    return False
+
+            else:
+                print("   ❌ HTML file not generated")
+                return False
+
+        print("\n✅ Complete HTML generation with media test passed!")
+        return True
+
+    async def run_all_tests(self):
+        """Run all media download tests."""
+        print("🚀 Starting Media Download Tests")
+        print("=" * 80)
+
+        try:
+            success = True
+
+            success &= self.test_assets_folder_creation()
+            success &= self.test_filename_sanitization()
+            success &= await self.test_media_download_mock()
+            success &= await self.test_media_formatting_integration()
+            success &= await self.test_complete_html_generation_with_media()
+
+            if success:
+                print("\n" + "=" * 80)
+                print("🎉 ALL MEDIA DOWNLOAD TESTS PASSED!")
+                print("=" * 80)
+                print("✅ Assets folder created correctly")
+                print("✅ Filename sanitization works properly")
+                print("✅ Media files download to assets subfolder")
+                print("✅ HTML references local files correctly")
+                print("✅ Complete integration working")
+                print("\n📁 Media Download Features:")
+                print("• Downloads images to assets/ subfolder")
+                print("• Downloads attachments to assets/ subfolder")
+                print("• Uses relative paths in HTML (assets/filename.jpg)")
+                print("• Fallback to API URLs if download fails")
+                print("• Sanitizes filenames for filesystem safety")
+                print("• Handles existing files (no re-download)")
+            else:
+                print("\n❌ SOME MEDIA DOWNLOAD TESTS FAILED")
+
+            return success
+
+        except Exception as e:
+            print(f"\n❌ MEDIA DOWNLOAD TESTS FAILED: {e}")
+            import traceback
+            traceback.print_exc()
+            return False
+
+
+def show_media_download_info():
+    """Show information about media download functionality."""
+    print("\n" + "=" * 80)
+    print("📁 MEDIA DOWNLOAD FUNCTIONALITY")
+    print("=" * 80)
+
+    print("\n🎯 How It Works:")
+    print("1. Creates 'assets' subfolder in output directory")
+    print("2. Downloads media files (images, attachments) from API")
+    print("3. Saves files with sanitized filenames")
+    print("4. Updates HTML to reference local files")
+    print("5. Fallback to API URLs if download fails")
+
+    print("\n📋 Supported Media Types:")
+    print("• Images: JPEG, PNG, GIF, WebP, etc.")
+    print("• Documents: PDF, DOC, TXT, etc.")
+    print("• Any file type from ParentZone media API")
+
+    print("\n💾 File Organization:")
+    print("output_directory/")
+    print("├── snapshots_DATE_to_DATE.html")
+    print("├── snapshots.log")
+    print("└── assets/")
+    print("    ├── image1.jpeg")
+    print("    ├── document.pdf")
+    print("    └── attachment.txt")
+
+    print("\n🔗 HTML Integration:")
+    print("• Images: <img src=\"assets/filename.jpg\">")
+    print("• Attachments: <a href=\"assets/filename.pdf\">")
+    print("• Relative paths for portability")
+    print("• Self-contained reports (HTML + assets)")
+
+    print("\n✨ Benefits:")
+    print("• Offline viewing - images work without internet")
+    print("• Faster loading - no API requests for media")
+    print("• Portable reports - can be shared easily")
+    print("• Professional presentation with embedded media")
+
+    print("\n⚠️ Considerations:")
+    print("• Requires storage space for downloaded media")
+    print("• Download time increases with media count")
+    print("• Large files may take longer to process")
+    print("• API authentication required for media download")
+
+
+def main():
+    """Main test function."""
+    # Setup logging
+    logging.basicConfig(
+        level=logging.INFO,
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+    )
+
+    tester = MediaDownloadTester()
+
+    # Run tests
+    success = asyncio.run(tester.run_all_tests())
+
+    # Show information
+    if success:
+        show_media_download_info()
+
+    return 0 if success else 1
+
+
+if __name__ == "__main__":
+    exit(main())

tests/test_parentzone.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""
+ParentZone API Test Script
+
+This script tests the ParentZone API integration specifically.
+"""
+
+import asyncio
+import aiohttp
+import json
+from urllib.parse import urljoin
+
+
+async def test_parentzone_api():
+    """Test the ParentZone API with the provided API key."""
+    api_url = "https://api.parentzone.me"
+    list_endpoint = "/v1/gallery"
+    download_endpoint = "/v1/media"
+    api_key = "b23326a9-bcbf-4bad-b026-9c79dad6a654"
+    
+    headers = {
+        'x-api-key': api_key
+    }
+    
+    print("=" * 60)
+    print("ParentZone API Test")
+    print("=" * 60)
+    
+    timeout = aiohttp.ClientTimeout(total=30)
+    async with aiohttp.ClientSession(timeout=timeout) as session:
+        # Test list endpoint
+        list_url = urljoin(api_url, list_endpoint)
+        print(f"Testing list endpoint: {list_url}")
+        
+        try:
+            async with session.get(list_url, headers=headers) as response:
+                print(f"Status Code: {response.status}")
+                print(f"Content-Type: {response.headers.get('content-type', 'Not specified')}")
+                
+                if response.status == 200:
+                    data = await response.json()
+                    print(f"Response type: {type(data)}")
+                    
+                    if isinstance(data, list):
+                        print(f"✓ Found {len(data)} assets in array")
+                        if data:
+                            print(f"First asset keys: {list(data[0].keys())}")
+                            print(f"Sample asset: {json.dumps(data[0], indent=2)}")
+                            
+                            # Test download endpoint with first asset
+                            asset_id = data[0].get('id')
+                            updated = data[0].get('updated', '')
+                            if asset_id:
+                                print(f"\nTesting download endpoint with asset ID: {asset_id}")
+                                from urllib.parse import urlencode
+                                params = {
+                                    'key': api_key,
+                                    'u': updated
+                                }
+                                download_url = urljoin(api_url, f"/v1/media/{asset_id}/full?{urlencode(params)}")
+                                print(f"Download URL: {download_url}")
+                                
+                                async with session.get(download_url) as download_response:
+                                    print(f"Download Status Code: {download_response.status}")
+                                    print(f"Download Content-Type: {download_response.headers.get('content-type', 'Not specified')}")
+                                    print(f"Download Content-Length: {download_response.headers.get('content-length', 'Not specified')}")
+                                    
+                                    if download_response.status == 200:
+                                        content_type = download_response.headers.get('content-type', '')
+                                        if content_type.startswith('image/'):
+                                            print("✓ Download endpoint returns image content")
+                                        else:
+                                            print(f"⚠ Warning: Content type is not an image: {content_type}")
+                                    else:
+                                        print(f"✗ Download endpoint failed: HTTP {download_response.status}")
+                            else:
+                                print("⚠ No asset ID found in first asset")
+                    else:
+                        print(f"✗ Unexpected response format: {type(data)}")
+                else:
+                    print(f"✗ List endpoint failed: HTTP {response.status}")
+                    
+        except Exception as e:
+            print(f"✗ Error testing API: {e}")
+    
+    print("\n" + "=" * 60)
+    print("TEST COMPLETE")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    asyncio.run(test_parentzone_api())

tests/test_snapshot_downloader.py

@@ -0,0 +1,678 @@
+#!/usr/bin/env python3
+"""
+Test Snapshot Downloader Functionality
+
+This script tests the snapshot downloader to ensure it properly fetches
+snapshots with pagination and generates HTML reports correctly.
+"""
+
+import asyncio
+import json
+import logging
+import sys
+import tempfile
+from datetime import datetime, timedelta
+from pathlib import Path
+import os
+
+# Add the current directory to the path so we can import modules
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from snapshot_downloader import SnapshotDownloader
+from config_snapshot_downloader import ConfigSnapshotDownloader
+
+
+class SnapshotDownloaderTester:
+    """Test class for snapshot downloader functionality."""
+
+    def __init__(self):
+        """Initialize the tester."""
+        self.logger = logging.getLogger(__name__)
+
+        # Test credentials
+        self.email = "tudor.sitaru@gmail.com"
+        self.password = "mTVq8uNUvY7R39EPGVAm@"
+        self.api_key = "95c74983-5d8f-4cf2-a216-3aa4416344ea"
+
+    def create_test_config(self, output_dir: str, **kwargs) -> dict:
+        """Create a test configuration."""
+        config = {
+            "api_url": "https://api.parentzone.me",
+            "output_dir": output_dir,
+            "type_ids": [15],
+            "date_from": "2024-01-01",
+            "date_to": "2024-01-31",  # Small range for testing
+            "max_pages": 2,  # Limit for testing
+            "email": self.email,
+            "password": self.password
+        }
+        config.update(kwargs)
+        return config
+
+    def test_initialization(self):
+        """Test that SnapshotDownloader initializes correctly."""
+        print("=" * 60)
+        print("TEST 1: Initialization")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            print("1. Testing basic initialization...")
+
+            downloader = SnapshotDownloader(
+                output_dir=temp_dir,
+                email=self.email,
+                password=self.password
+            )
+
+            # Check initialization
+            if downloader.output_dir == Path(temp_dir):
+                print("   ✅ Output directory set correctly")
+            else:
+                print("   ❌ Output directory not set correctly")
+                return False
+
+            if downloader.email == self.email:
+                print("   ✅ Email set correctly")
+            else:
+                print("   ❌ Email not set correctly")
+                return False
+
+            if downloader.stats['total_snapshots'] == 0:
+                print("   ✅ Statistics initialized correctly")
+            else:
+                print("   ❌ Statistics not initialized correctly")
+                return False
+
+            print("\n2. Testing with API key...")
+            downloader_api = SnapshotDownloader(
+                output_dir=temp_dir,
+                api_key=self.api_key
+            )
+
+            if downloader_api.api_key == self.api_key:
+                print("   ✅ API key set correctly")
+            else:
+                print("   ❌ API key not set correctly")
+                return False
+
+        print("\n✅ Initialization test passed!")
+        return True
+
+    def test_authentication_headers(self):
+        """Test that authentication headers are set properly."""
+        print("\n" + "=" * 60)
+        print("TEST 2: Authentication Headers")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            print("1. Testing API key headers...")
+
+            downloader = SnapshotDownloader(
+                output_dir=temp_dir,
+                api_key=self.api_key
+            )
+
+            headers = downloader.get_auth_headers()
+            if 'x-api-key' in headers and headers['x-api-key'] == self.api_key:
+                print("   ✅ API key header set correctly")
+            else:
+                print("   ❌ API key header not set correctly")
+                return False
+
+            print("\n2. Testing standard headers...")
+            expected_headers = [
+                'accept', 'accept-language', 'origin', 'user-agent',
+                'sec-fetch-dest', 'sec-fetch-mode', 'sec-fetch-site'
+            ]
+
+            for header in expected_headers:
+                if header in headers:
+                    print(f"   ✅ {header} header present")
+                else:
+                    print(f"   ❌ {header} header missing")
+                    return False
+
+        print("\n✅ Authentication headers test passed!")
+        return True
+
+    async def test_authentication_flow(self):
+        """Test the authentication flow."""
+        print("\n" + "=" * 60)
+        print("TEST 3: Authentication Flow")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            print("1. Testing login authentication...")
+
+            downloader = SnapshotDownloader(
+                output_dir=temp_dir,
+                email=self.email,
+                password=self.password
+            )
+
+            try:
+                await downloader.authenticate()
+
+                if downloader.auth_manager and downloader.auth_manager.is_authenticated():
+                    print("   ✅ Login authentication successful")
+
+                    # Check if API key was obtained
+                    headers = downloader.get_auth_headers()
+                    if 'x-api-key' in headers:
+                        print("   ✅ API key obtained from authentication")
+                        obtained_key = headers['x-api-key']
+                        if obtained_key:
+                            print(f"   ✅ API key: {obtained_key[:20]}...")
+                    else:
+                        print("   ❌ API key not obtained from authentication")
+                        return False
+                else:
+                    print("   ❌ Login authentication failed")
+                    return False
+
+            except Exception as e:
+                print(f"   ❌ Authentication error: {e}")
+                return False
+
+        print("\n✅ Authentication flow test passed!")
+        return True
+
+    async def test_url_building(self):
+        """Test URL building for API requests."""
+        print("\n" + "=" * 60)
+        print("TEST 4: URL Building")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            downloader = SnapshotDownloader(output_dir=temp_dir)
+
+            print("1. Testing basic URL construction...")
+
+            # Mock session for URL building test
+            class MockSession:
+                def __init__(self):
+                    self.last_url = None
+                    self.last_headers = None
+
+                async def get(self, url, headers=None, timeout=None):
+                    self.last_url = url
+                    self.last_headers = headers
+                    # Return mock async context manager
+                    return MockAsyncContext()
+
+                async def __aenter__(self):
+                    return self
+
+                async def __aexit__(self, *args):
+                    pass
+
+            class MockAsyncContext:
+                async def __aenter__(self):
+                    raise Exception("Mock response - URL captured")
+
+                async def __aexit__(self, *args):
+                    pass
+
+            mock_session = MockSession()
+
+            try:
+                await downloader.fetch_snapshots_page(
+                    mock_session,
+                    type_ids=[15],
+                    date_from="2024-01-01",
+                    date_to="2024-01-31",
+                    page=1,
+                    per_page=100
+                )
+            except Exception as e:
+                # Expected - we just want to capture the URL
+                if "Mock response" in str(e):
+                    url = mock_session.last_url
+                    print(f"   Generated URL: {url}")
+
+                    # Check URL components
+                    if "https://api.parentzone.me/v1/posts" in url:
+                        print("   ✅ Base URL correct")
+                    else:
+                        print("   ❌ Base URL incorrect")
+                        return False
+
+                    if "typeIDs%5B%5D=15" in url or "typeIDs[]=15" in url:
+                        print("   ✅ Type ID parameter correct")
+                    else:
+                        print("   ❌ Type ID parameter incorrect")
+                        return False
+
+                    if "dateFrom=2024-01-01" in url:
+                        print("   ✅ Date from parameter correct")
+                    else:
+                        print("   ❌ Date from parameter incorrect")
+                        return False
+
+                    if "dateTo=2024-01-31" in url:
+                        print("   ✅ Date to parameter correct")
+                    else:
+                        print("   ❌ Date to parameter incorrect")
+                        return False
+
+                    if "page=1" in url:
+                        print("   ✅ Page parameter correct")
+                    else:
+                        print("   ❌ Page parameter incorrect")
+                        return False
+                else:
+                    print(f"   ❌ Unexpected error: {e}")
+                    return False
+
+        print("\n✅ URL building test passed!")
+        return True
+
+    def test_html_formatting(self):
+        """Test HTML formatting functions."""
+        print("\n" + "=" * 60)
+        print("TEST 5: HTML Formatting")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            downloader = SnapshotDownloader(output_dir=temp_dir)
+
+            print("1. Testing snapshot HTML formatting...")
+
+            # Create mock snapshot data
+            mock_snapshot = {
+                "id": "test_snapshot_123",
+                "title": "Test Snapshot <script>alert('xss')</script>",
+                "content": "This is a test snapshot with some content & special characters",
+                "created_at": "2024-01-15T10:30:00Z",
+                "updated_at": "2024-01-15T10:30:00Z",
+                "author": {
+                    "name": "Test Author"
+                },
+                "child": {
+                    "name": "Test Child"
+                },
+                "activity": {
+                    "name": "Test Activity"
+                },
+                "images": [
+                    {
+                        "url": "https://example.com/image1.jpg",
+                        "name": "Test Image"
+                    }
+                ]
+            }
+
+            html = downloader.format_snapshot_html(mock_snapshot)
+
+            # Check basic structure
+            if '<div class="snapshot"' in html:
+                print("   ✅ Snapshot container created")
+            else:
+                print("   ❌ Snapshot container missing")
+                return False
+
+            # Check HTML escaping - should have escaped script tags and quotes
+            if "&lt;script&gt;" in html and "&quot;xss&quot;" in html:
+                print("   ✅ HTML properly escaped")
+            else:
+                print("   ❌ HTML escaping failed")
+                return False
+
+            # Check content inclusion
+            if "Test Snapshot" in html:
+                print("   ✅ Title included")
+            else:
+                print("   ❌ Title missing")
+                return False
+
+            if "Test Author" in html:
+                print("   ✅ Author included")
+            else:
+                print("   ❌ Author missing")
+                return False
+
+            if "Test Child" in html:
+                print("   ✅ Child included")
+            else:
+                print("   ❌ Child missing")
+                return False
+
+            print("\n2. Testing complete HTML file generation...")
+
+            mock_snapshots = [mock_snapshot]
+            html_file = downloader.generate_html_file(
+                mock_snapshots, "2024-01-01", "2024-01-31"
+            )
+
+            if html_file.exists():
+                print("   ✅ HTML file created")
+
+                # Check file content
+                with open(html_file, 'r', encoding='utf-8') as f:
+                    content = f.read()
+
+                if "<!DOCTYPE html>" in content:
+                    print("   ✅ Valid HTML document")
+                else:
+                    print("   ❌ Invalid HTML document")
+                    return False
+
+                if "ParentZone Snapshots" in content:
+                    print("   ✅ Title included")
+                else:
+                    print("   ❌ Title missing")
+                    return False
+
+                if "Test Snapshot" in content:
+                    print("   ✅ Snapshot content included")
+                else:
+                    print("   ❌ Snapshot content missing")
+                    return False
+
+            else:
+                print("   ❌ HTML file not created")
+                return False
+
+        print("\n✅ HTML formatting test passed!")
+        return True
+
+    def test_config_downloader(self):
+        """Test the configuration-based downloader."""
+        print("\n" + "=" * 60)
+        print("TEST 6: Config Downloader")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            print("1. Testing configuration loading...")
+
+            # Create test config file
+            config_data = self.create_test_config(temp_dir)
+            config_file = Path(temp_dir) / "test_config.json"
+
+            with open(config_file, 'w') as f:
+                json.dump(config_data, f, indent=2)
+
+            # Test config loading
+            try:
+                config_downloader = ConfigSnapshotDownloader(str(config_file))
+                print("   ✅ Configuration loaded successfully")
+
+                # Check if underlying downloader was created
+                if hasattr(config_downloader, 'downloader'):
+                    print("   ✅ Underlying downloader created")
+                else:
+                    print("   ❌ Underlying downloader not created")
+                    return False
+
+            except Exception as e:
+                print(f"   ❌ Configuration loading failed: {e}")
+                return False
+
+            print("\n2. Testing invalid configuration...")
+
+            # Test invalid config (missing auth)
+            invalid_config = config_data.copy()
+            del invalid_config['email']
+            del invalid_config['password']
+            # Don't set api_key either
+
+            invalid_config_file = Path(temp_dir) / "invalid_config.json"
+            with open(invalid_config_file, 'w') as f:
+                json.dump(invalid_config, f, indent=2)
+
+            try:
+                ConfigSnapshotDownloader(str(invalid_config_file))
+                print("   ❌ Should have failed with invalid config")
+                return False
+            except ValueError:
+                print("   ✅ Correctly rejected invalid configuration")
+            except Exception as e:
+                print(f"   ❌ Unexpected error: {e}")
+                return False
+
+        print("\n✅ Config downloader test passed!")
+        return True
+
+    def test_date_formatting(self):
+        """Test date formatting functionality."""
+        print("\n" + "=" * 60)
+        print("TEST 7: Date Formatting")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            downloader = SnapshotDownloader(output_dir=temp_dir)
+
+            print("1. Testing various date formats...")
+
+            test_dates = [
+                ("2024-01-15T10:30:00Z", "2024-01-15 10:30:00"),
+                ("2024-01-15T10:30:00.123Z", "2024-01-15 10:30:00"),
+                ("2024-01-15T10:30:00+00:00", "2024-01-15 10:30:00"),
+                ("invalid-date", "invalid-date"),  # Should pass through unchanged
+                ("", "")  # Should handle empty string
+            ]
+
+            for input_date, expected_prefix in test_dates:
+                formatted = downloader.format_date(input_date)
+                print(f"   Input: '{input_date}' → Output: '{formatted}'")
+
+                if expected_prefix in formatted or input_date == formatted:
+                    print(f"   ✅ Date formatted correctly")
+                else:
+                    print(f"   ❌ Date formatting failed")
+                    return False
+
+        print("\n✅ Date formatting test passed!")
+        return True
+
+    async def test_pagination_logic(self):
+        """Test pagination handling logic."""
+        print("\n" + "=" * 60)
+        print("TEST 8: Pagination Logic")
+        print("=" * 60)
+
+        print("1. Testing pagination parameters...")
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            downloader = SnapshotDownloader(output_dir=temp_dir)
+
+            # Mock session to test pagination
+            class PaginationMockSession:
+                def __init__(self):
+                    self.call_count = 0
+                    self.pages = [
+                        # Page 1
+                        {
+                            "data": [{"id": "snap1"}, {"id": "snap2"}],
+                            "pagination": {"current_page": 1, "last_page": 3}
+                        },
+                        # Page 2
+                        {
+                            "data": [{"id": "snap3"}, {"id": "snap4"}],
+                            "pagination": {"current_page": 2, "last_page": 3}
+                        },
+                        # Page 3
+                        {
+                            "data": [{"id": "snap5"}],
+                            "pagination": {"current_page": 3, "last_page": 3}
+                        }
+                    ]
+
+                async def get(self, url, headers=None, timeout=None):
+                    return MockResponse(self.pages[self.call_count])
+
+                async def __aenter__(self):
+                    return self
+
+                async def __aexit__(self, *args):
+                    pass
+
+            class MockResponse:
+                def __init__(self, data):
+                    self.data = data
+                    self.status = 200
+
+                def raise_for_status(self):
+                    pass
+
+                async def json(self):
+                    return self.data
+
+            mock_session = PaginationMockSession()
+
+            # Override the fetch_snapshots_page method to use our mock
+            original_method = downloader.fetch_snapshots_page
+
+            async def mock_fetch_page(session, type_ids, date_from, date_to, page, per_page):
+                response_data = mock_session.pages[page - 1]
+                mock_session.call_count += 1
+                downloader.stats['pages_fetched'] += 1
+                return response_data
+
+            downloader.fetch_snapshots_page = mock_fetch_page
+
+            try:
+                # Test fetching all pages
+                snapshots = await downloader.fetch_all_snapshots(
+                    mock_session, [15], "2024-01-01", "2024-01-31"
+                )
+
+                if len(snapshots) == 5:  # Total snapshots across all pages
+                    print("   ✅ All pages fetched correctly")
+                else:
+                    print(f"   ❌ Expected 5 snapshots, got {len(snapshots)}")
+                    return False
+
+                if downloader.stats['pages_fetched'] == 3:
+                    print("   ✅ Page count tracked correctly")
+                else:
+                    print(f"   ❌ Expected 3 pages, tracked {downloader.stats['pages_fetched']}")
+                    return False
+
+                # Test max_pages limit
+                downloader.stats['pages_fetched'] = 0  # Reset
+                mock_session.call_count = 0  # Reset
+
+                snapshots_limited = await downloader.fetch_all_snapshots(
+                    mock_session, [15], "2024-01-01", "2024-01-31", max_pages=2
+                )
+
+                if len(snapshots_limited) == 4:  # First 2 pages only
+                    print("   ✅ Max pages limit respected")
+                else:
+                    print(f"   ❌ Expected 4 snapshots with limit, got {len(snapshots_limited)}")
+                    return False
+
+            except Exception as e:
+                print(f"   ❌ Pagination test error: {e}")
+                return False
+
+        print("\n✅ Pagination logic test passed!")
+        return True
+
+    async def run_all_tests(self):
+        """Run all tests."""
+        print("🚀 Starting Snapshot Downloader Tests")
+        print("=" * 80)
+
+        try:
+            success = True
+
+            success &= self.test_initialization()
+            success &= self.test_authentication_headers()
+            success &= await self.test_authentication_flow()
+            success &= await self.test_url_building()
+            success &= self.test_html_formatting()
+            success &= self.test_config_downloader()
+            success &= self.test_date_formatting()
+            success &= await self.test_pagination_logic()
+
+            if success:
+                print("\n" + "=" * 80)
+                print("🎉 ALL SNAPSHOT DOWNLOADER TESTS PASSED!")
+                print("=" * 80)
+                print("✅ Snapshot downloader is working correctly")
+                print("✅ Pagination handling is implemented properly")
+                print("✅ HTML generation creates proper markup files")
+                print("✅ Authentication works with both API key and login")
+                print("✅ Configuration-based downloader is functional")
+            else:
+                print("\n❌ SOME TESTS FAILED")
+
+            return success
+
+        except Exception as e:
+            print(f"\n❌ TEST SUITE FAILED: {e}")
+            import traceback
+            traceback.print_exc()
+            return False
+
+
+def show_usage_examples():
+    """Show usage examples for the snapshot downloader."""
+    print("\n" + "=" * 80)
+    print("📋 SNAPSHOT DOWNLOADER USAGE EXAMPLES")
+    print("=" * 80)
+
+    print("\n💻 Command Line Usage:")
+    print("# Download snapshots with API key")
+    print("python3 snapshot_downloader.py --api-key YOUR_API_KEY")
+    print()
+    print("# Download with login credentials")
+    print("python3 snapshot_downloader.py --email user@example.com --password password")
+    print()
+    print("# Specify date range")
+    print("python3 snapshot_downloader.py --api-key KEY --date-from 2024-01-01 --date-to 2024-12-31")
+    print()
+    print("# Limit pages for testing")
+    print("python3 snapshot_downloader.py --api-key KEY --max-pages 5")
+
+    print("\n🔧 Configuration File Usage:")
+    print("# Create example config")
+    print("python3 config_snapshot_downloader.py --create-example")
+    print()
+    print("# Use config file")
+    print("python3 config_snapshot_downloader.py --config snapshot_config.json")
+    print()
+    print("# Show config summary")
+    print("python3 config_snapshot_downloader.py --config snapshot_config.json --show-config")
+
+    print("\n📄 Features:")
+    print("• Downloads all snapshots with pagination support")
+    print("• Generates interactive HTML reports")
+    print("• Includes search and filtering capabilities")
+    print("• Supports both API key and login authentication")
+    print("• Configurable date ranges and type filters")
+    print("• Mobile-responsive design")
+    print("• Collapsible sections for detailed metadata")
+
+    print("\n🎯 Output:")
+    print("• HTML file with all snapshots in chronological order")
+    print("• Embedded images and attachments (if available)")
+    print("• Raw JSON data for each snapshot (expandable)")
+    print("• Search functionality to find specific snapshots")
+    print("• Statistics and summary information")
+
+
+def main():
+    """Main test function."""
+    # Setup logging
+    logging.basicConfig(
+        level=logging.INFO,
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+    )
+
+    tester = SnapshotDownloaderTester()
+
+    # Run tests
+    success = asyncio.run(tester.run_all_tests())
+
+    # Show usage examples
+    if success:
+        show_usage_examples()
+
+    return 0 if success else 1
+
+
+if __name__ == "__main__":
+    exit(main())

tests/test_title_format.py

@@ -0,0 +1,361 @@
+#!/usr/bin/env python3
+"""
+Test Title Format Functionality
+
+This script tests that snapshot titles are properly formatted using
+child forename and author forename/surname instead of post ID.
+"""
+
+import sys
+import os
+import tempfile
+from pathlib import Path
+
+# Add the current directory to the path so we can import modules
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from snapshot_downloader import SnapshotDownloader
+
+
+class TitleFormatTester:
+    """Test class for title formatting functionality."""
+
+    def __init__(self):
+        """Initialize the tester."""
+        pass
+
+    def test_title_formatting(self):
+        """Test that titles are formatted correctly with child and author names."""
+        print("=" * 60)
+        print("TEST: Title Format - Child by Author")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            downloader = SnapshotDownloader(output_dir=temp_dir)
+
+            print("1. Testing standard title format...")
+
+            # Test case 1: Complete data
+            mock_snapshot = {
+                "id": 123456,
+                "type": "Snapshot",
+                "child": {
+                    "forename": "Noah",
+                    "surname": "Smith"
+                },
+                "author": {
+                    "forename": "Elena",
+                    "surname": "Garcia"
+                },
+                "startTime": "2024-01-15T10:30:00",
+                "notes": "<p>Test snapshot content</p>"
+            }
+
+            html_content = downloader.format_snapshot_html(mock_snapshot)
+            expected_title = "Noah by Elena Garcia"
+
+            if f'<h3 class="snapshot-title">{expected_title}</h3>' in html_content:
+                print(f"   ✅ Standard format: {expected_title}")
+            else:
+                print(f"   ❌ Expected: {expected_title}")
+                print("   Debug: Looking for title in HTML...")
+                start = html_content.find('snapshot-title')
+                if start != -1:
+                    sample = html_content[start:start+100]
+                    print(f"   Found: {sample}")
+                return False
+
+            print("\n2. Testing edge cases...")
+
+            # Test case 2: Missing child surname
+            mock_snapshot_2 = {
+                "id": 789012,
+                "type": "Snapshot",
+                "child": {
+                    "forename": "Sofia"
+                    # Missing surname
+                },
+                "author": {
+                    "forename": "Maria",
+                    "surname": "Rodriguez"
+                },
+                "startTime": "2024-01-15T10:30:00",
+                "notes": "<p>Test content</p>"
+            }
+
+            html_content_2 = downloader.format_snapshot_html(mock_snapshot_2)
+            expected_title_2 = "Sofia by Maria Rodriguez"
+
+            if f'<h3 class="snapshot-title">{expected_title_2}</h3>' in html_content_2:
+                print(f"   ✅ Missing child surname: {expected_title_2}")
+            else:
+                print(f"   ❌ Expected: {expected_title_2}")
+                return False
+
+            # Test case 3: Missing author surname
+            mock_snapshot_3 = {
+                "id": 345678,
+                "type": "Snapshot",
+                "child": {
+                    "forename": "Alex",
+                    "surname": "Johnson"
+                },
+                "author": {
+                    "forename": "Lisa"
+                    # Missing surname
+                },
+                "startTime": "2024-01-15T10:30:00",
+                "notes": "<p>Test content</p>"
+            }
+
+            html_content_3 = downloader.format_snapshot_html(mock_snapshot_3)
+            expected_title_3 = "Alex by Lisa"
+
+            if f'<h3 class="snapshot-title">{expected_title_3}</h3>' in html_content_3:
+                print(f"   ✅ Missing author surname: {expected_title_3}")
+            else:
+                print(f"   ❌ Expected: {expected_title_3}")
+                return False
+
+            # Test case 4: Missing child forename (should fallback to ID)
+            mock_snapshot_4 = {
+                "id": 999999,
+                "type": "Snapshot",
+                "child": {
+                    "surname": "Brown"
+                    # Missing forename
+                },
+                "author": {
+                    "forename": "John",
+                    "surname": "Davis"
+                },
+                "startTime": "2024-01-15T10:30:00",
+                "notes": "<p>Test content</p>"
+            }
+
+            html_content_4 = downloader.format_snapshot_html(mock_snapshot_4)
+            expected_title_4 = "Snapshot 999999"
+
+            if f'<h3 class="snapshot-title">{expected_title_4}</h3>' in html_content_4:
+                print(f"   ✅ Missing child forename (fallback): {expected_title_4}")
+            else:
+                print(f"   ❌ Expected fallback: {expected_title_4}")
+                return False
+
+            # Test case 5: Missing author forename (should fallback to ID)
+            mock_snapshot_5 = {
+                "id": 777777,
+                "type": "Snapshot",
+                "child": {
+                    "forename": "Emma",
+                    "surname": "Wilson"
+                },
+                "author": {
+                    "surname": "Taylor"
+                    # Missing forename
+                },
+                "startTime": "2024-01-15T10:30:00",
+                "notes": "<p>Test content</p>"
+            }
+
+            html_content_5 = downloader.format_snapshot_html(mock_snapshot_5)
+            expected_title_5 = "Snapshot 777777"
+
+            if f'<h3 class="snapshot-title">{expected_title_5}</h3>' in html_content_5:
+                print(f"   ✅ Missing author forename (fallback): {expected_title_5}")
+            else:
+                print(f"   ❌ Expected fallback: {expected_title_5}")
+                return False
+
+            print("\n3. Testing HTML escaping in titles...")
+
+            # Test case 6: Names with special characters
+            mock_snapshot_6 = {
+                "id": 555555,
+                "type": "Snapshot",
+                "child": {
+                    "forename": "José",
+                    "surname": "García"
+                },
+                "author": {
+                    "forename": "María",
+                    "surname": "López <script>"
+                },
+                "startTime": "2024-01-15T10:30:00",
+                "notes": "<p>Test content</p>"
+            }
+
+            html_content_6 = downloader.format_snapshot_html(mock_snapshot_6)
+
+            # Check that special characters are preserved but HTML is escaped
+            if "José by María López" in html_content_6 and "&lt;script&gt;" in html_content_6:
+                print("   ✅ Special characters preserved, HTML escaped")
+            else:
+                print("   ❌ Special character or HTML escaping failed")
+                return False
+
+            print("\n✅ Title formatting test completed successfully!")
+            return True
+
+    def test_complete_html_generation(self):
+        """Test title formatting in complete HTML file generation."""
+        print("\n" + "=" * 60)
+        print("TEST: Title Format in Complete HTML File")
+        print("=" * 60)
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            downloader = SnapshotDownloader(output_dir=temp_dir)
+
+            # Create multiple snapshots with different name scenarios
+            mock_snapshots = [
+                {
+                    "id": 100001,
+                    "type": "Snapshot",
+                    "child": {"forename": "Noah", "surname": "Sitaru"},
+                    "author": {"forename": "Elena", "surname": "Blanco"},
+                    "startTime": "2025-08-14T10:42:00",
+                    "notes": "<p>Noah's progress today</p>"
+                },
+                {
+                    "id": 100002,
+                    "type": "Snapshot",
+                    "child": {"forename": "Sophia", "surname": "Sitaru"},
+                    "author": {"forename": "Kyra", "surname": "Philbert-Nurse"},
+                    "startTime": "2025-07-31T10:42:00",
+                    "notes": "<p>Sophia's activity</p>"
+                },
+                {
+                    "id": 100003,
+                    "type": "Snapshot",
+                    "child": {"forename": "Emma"},  # Missing surname
+                    "author": {"forename": "Lisa", "surname": "Wilson"},
+                    "startTime": "2025-06-15T14:30:00",
+                    "notes": "<p>Emma's development</p>"
+                }
+            ]
+
+            print("1. Generating complete HTML file...")
+            html_file = downloader.generate_html_file(mock_snapshots, "2024-01-01", "2024-12-31")
+
+            if html_file.exists():
+                print("   ✅ HTML file generated successfully")
+
+                with open(html_file, 'r', encoding='utf-8') as f:
+                    file_content = f.read()
+
+                # Check for expected titles
+                expected_titles = [
+                    "Noah by Elena Blanco",
+                    "Sophia by Kyra Philbert-Nurse",
+                    "Emma by Lisa Wilson"
+                ]
+
+                print("\n2. Checking titles in generated file...")
+                all_found = True
+                for title in expected_titles:
+                    if f'<h3 class="snapshot-title">{title}</h3>' in file_content:
+                        print(f"   ✅ Found: {title}")
+                    else:
+                        print(f"   ❌ Missing: {title}")
+                        all_found = False
+
+                if not all_found:
+                    return False
+
+                print("\n3. Verifying HTML structure...")
+                if 'class="snapshot-title"' in file_content:
+                    print("   ✅ Title CSS class present")
+                else:
+                    print("   ❌ Title CSS class missing")
+                    return False
+
+                print("\n✅ Complete HTML file generation test passed!")
+                return True
+            else:
+                print("   ❌ HTML file was not generated")
+                return False
+
+    def run_all_tests(self):
+        """Run all title formatting tests."""
+        print("🚀 Starting Title Format Tests")
+        print("=" * 80)
+
+        try:
+            success = True
+
+            success &= self.test_title_formatting()
+            success &= self.test_complete_html_generation()
+
+            if success:
+                print("\n" + "=" * 80)
+                print("🎉 ALL TITLE FORMAT TESTS PASSED!")
+                print("=" * 80)
+                print("✅ Titles formatted as 'Child by Author Name'")
+                print("✅ Edge cases handled correctly (missing names)")
+                print("✅ HTML escaping works for special characters")
+                print("✅ Complete HTML generation includes proper titles")
+                print("\n📋 Title Format Examples:")
+                print("• Noah by Elena Blanco")
+                print("• Sophia by Kyra Philbert-Nurse")
+                print("• Emma by Lisa Wilson")
+                print("• Snapshot 123456 (fallback when names missing)")
+            else:
+                print("\n❌ SOME TITLE FORMAT TESTS FAILED")
+
+            return success
+
+        except Exception as e:
+            print(f"\n❌ TITLE FORMAT TESTS FAILED: {e}")
+            import traceback
+            traceback.print_exc()
+            return False
+
+
+def show_title_format_info():
+    """Show information about the title format."""
+    print("\n" + "=" * 80)
+    print("📋 SNAPSHOT TITLE FORMAT")
+    print("=" * 80)
+
+    print("\n🎯 New Format:")
+    print("Child Forename by Author Forename Surname")
+
+    print("\n📝 Examples:")
+    print("• Noah by Elena Blanco")
+    print("• Sophia by Kyra Philbert-Nurse")
+    print("• Alex by Maria Rodriguez")
+    print("• Emma by Lisa Wilson")
+
+    print("\n🔄 Fallback Behavior:")
+    print("• Missing child forename → 'Snapshot [ID]'")
+    print("• Missing author forename → 'Snapshot [ID]'")
+    print("• Missing surnames → Names without surname used")
+
+    print("\n🔒 HTML Escaping:")
+    print("• Special characters preserved (José, María)")
+    print("• HTML tags escaped for security (<script> → &lt;script&gt;)")
+    print("• Accents and international characters supported")
+
+    print("\n💡 Benefits:")
+    print("• More meaningful snapshot identification")
+    print("• Easy to scan and find specific child's snapshots")
+    print("• Clear attribution to teaching staff")
+    print("• Professional presentation for reports")
+
+
+def main():
+    """Main test function."""
+    tester = TitleFormatTester()
+
+    # Run tests
+    success = tester.run_all_tests()
+
+    # Show information
+    if success:
+        show_title_format_info()
+
+    return 0 if success else 1
+
+
+if __name__ == "__main__":
+    exit(main())