TESTING_GUIDE.md 14 KB
GrabZilla 2.1 - Manual Testing Guide
Complete guide for manual testing of all features before production release.
🎯 Testing Objectives
- Verify all download functionality works with real videos
- Test parallel processing with multiple concurrent downloads
- Validate GPU acceleration improves performance
- Ensure pause/resume works correctly
- Test queue management (cancel, priority)
- Verify error handling and user feedback
- Confirm UI responsiveness and accuracy
🛠️ Test Environment Setup
Prerequisites
# 1. Ensure binaries are installed
npm run setup
# 2. Start in development mode (with DevTools)
npm run dev
# 3. Check binary versions
# Should see yt-dlp and ffmpeg versions in statusline
Cookie File for Age-Restricted Videos
Some videos (like Big Buck Bunny) may require authentication. To download these:
Export cookies from your browser:
- Chrome: Use extension like "Get cookies.txt LOCALLY"
- Firefox: Use extension like "cookies.txt"
- Export in Netscape format
Select cookie file in GrabZilla:
- Click the "Cookie: Select File" button
- Choose your exported .txt file
- You'll see the filename displayed next to the button
Cookie file is automatically used for all downloads once selected
- No need to re-select for each video
- Persists for the session
Note: The cookie file path is shown in the UI after selection. If you see "Age-restricted video - authentication required" errors, make sure you've selected a valid cookie file first.
System Requirements
- macOS 10.15+ / Windows 10+ / Linux (Ubuntu 20.04+)
- 8GB RAM minimum (16GB recommended)
- 5GB free disk space for test downloads
- Internet connection (stable, > 5 Mbps)
📋 Test Procedures
Test 1: Basic Download (10 min)
Objective: Verify single video download works end-to-end.
Steps:
- Launch GrabZilla in dev mode
- Paste URL:
https://www.youtube.com/watch?v=jNQXAC9IVRw - Click "Add Videos"
- Select save directory
- Choose quality: 720p
- Choose format: MP4 (H.264)
- Click "Download Videos"
Expected Results:
- ✅ Video appears in video list with "Ready" status
- ✅ Download starts automatically
- ✅ Progress bar updates smoothly (0-100%)
- ✅ Speed displayed in MB/s or KB/s
- ✅ Status changes: Ready → Downloading → Completed
- ✅ File saved to selected directory
- ✅ File plays correctly in video player
- ✅ Statusline shows updated metrics
Success Criteria:
- Download completes without errors
- Progress reporting is accurate
- File integrity verified (plays correctly)
- Time: < 30 seconds for short video
Test 2: Concurrent Downloads (15 min)
Objective: Test parallel processing with multiple videos.
Setup: Use these 4 URLs:
https://www.youtube.com/watch?v=jNQXAC9IVRw
https://www.youtube.com/watch?v=dQw4w9WgXcQ
https://www.youtube.com/watch?v=9bZkp7q19f0
https://www.youtube.com/watch?v=_OBlgSz8sSM
Steps:
- Paste all 4 URLs (one per line or comma-separated)
- Click "Add Videos"
- Verify all 4 appear in video list
- Click "Download Videos"
- Watch queue panel
Expected Results:
- ✅ Queue panel shows: Active: 4/4, Queued: 0
- ✅ All 4 videos download simultaneously
- ✅ Each video has individual progress bar
- ✅ Each video shows its own speed
- ✅ CPU usage displayed in queue panel (should be < 5%)
- ✅ Downloads complete in parallel (not sequential)
- ✅ All 4 files saved correctly
Success Criteria:
- Parallel downloads work correctly
- No race conditions or crashes
- CPU usage remains reasonable
- Time: ~2-3 minutes total (much faster than sequential)
Comparison:
- Sequential: Would take ~4-6 minutes
- Parallel (4): Should take ~1-2 minutes
- Improvement: 2-4x faster ⚡
Test 3: Pause & Resume (10 min)
Objective: Verify pause/resume functionality.
Steps:
- Start downloading:
https://www.youtube.com/watch?v=_OBlgSz8sSM(longer video) - Wait for download to reach ~30%
- Click "Pause" button on video item
- Wait 5 seconds
- Verify download is paused (progress frozen)
- Click "Resume" button
- Wait for download to complete
Expected Results:
- ✅ Pause button appears during download
- ✅ Click pause → download stops immediately
- ✅ Progress bar frozen at ~30%
- ✅ Status shows "Paused"
- ✅ Resume button appears
- ✅ Click resume → download continues from 30%
- ✅ Download completes successfully
- ✅ File integrity maintained (plays correctly)
Success Criteria:
- Pause response: < 1 second
- Resume works correctly from paused point
- No corruption in downloaded file
- Progress accurate after resume
Test 4: Cancel Download (5 min)
Objective: Verify cancellation works correctly.
Steps:
- Start downloading a video
- Wait for download to reach ~20%
- Click "Cancel" button
- Verify download stops
Expected Results:
- ✅ Download stops immediately
- ✅ Video removed from active queue
- ✅ Partial file cleaned up (or marked incomplete)
- ✅ No errors in console
- ✅ Queue panel updates (Active count decreases)
Success Criteria:
- Cancel response: < 1 second
- Clean termination (no zombie processes)
- UI updates correctly
Test 5: GPU Acceleration (15 min)
Objective: Verify GPU hardware acceleration improves performance.
Setup:
- Video requiring conversion (download best quality, convert to H.264)
Steps:
Part A: With GPU (Default)
- Settings → GPU Acceleration: ON
- Download video:
https://www.youtube.com/watch?v=aqz-KE-bpKQ - Quality: 1080p
- Format: H.264
- Note conversion time and CPU usage
Part B: Without GPU
- Settings → GPU Acceleration: OFF
- Download same video again (different name)
- Same quality and format
- Note conversion time and CPU usage
Expected Results:
| Metric | With GPU | Without GPU | Improvement |
|---|---|---|---|
| Conversion time | ~30s | ~90s | 3x faster |
| CPU usage | 10-20% | 80-100% | 4-5x lower |
| GPU status | Shows type | "Software" | N/A |
Success Criteria:
- GPU accelerated conversion is 2-5x faster
- CPU usage significantly lower with GPU
- Both produce playable videos
- File size similar (within 10%)
GPU Types by Platform:
- macOS: VideoToolbox
- Windows (NVIDIA): NVENC
- Windows (AMD): AMF
- Windows (Intel): QSV
- Linux: VA-API or NVENC
Test 6: Queue Management (10 min)
Objective: Test queue with many videos and priority.
Steps:
- Add 8 videos to queue
- Settings → Max Concurrent: 2
- Start downloads
- Observe queue panel: Active: 2, Queued: 6
- Cancel one active download
- Verify queued video starts automatically
- Change concurrency to 4
- Verify 2 more downloads start
Expected Results:
- ✅ Queue respects concurrency limit
- ✅ Queued videos wait their turn
- ✅ When slot opens, next video starts automatically
- ✅ Queue panel shows accurate counts
- ✅ Changing concurrency takes effect immediately
Success Criteria:
- Queue system works correctly
- Automatic slot filling
- Settings changes apply in real-time
Test 7: Playlist Download (20 min)
Objective: Test playlist parsing and batch download.
Small Playlist:
https://www.youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf
Steps:
- Paste playlist URL
- Click "Add Videos"
- Verify all videos from playlist appear in list
- Each video shows title, duration, thumbnail
- Start download (concurrent)
- Monitor queue panel
Expected Results:
- ✅ Playlist URL recognized
- ✅ All videos extracted (5-10 videos)
- ✅ Metadata fetched for each video
- ✅ Downloads proceed in parallel
- ✅ All videos download successfully
- ✅ Progress tracked individually
Success Criteria:
- Playlist parsing works
- Batch metadata fetching
- Concurrent downloads of playlist items
- Time: ~2-5 minutes for small playlist
Large Playlist (Optional):
- Test with 100+ videos
- Verify performance remains good
- Check memory usage doesn't spike
Test 8: YouTube Shorts (5 min)
Objective: Verify Shorts URL support.
Steps:
- Paste Shorts URL:
https://www.youtube.com/shorts/dQw4w9WgXcQ - Click "Add Videos"
- Verify URL normalized to watch URL
- Download video
Expected Results:
- ✅ Shorts URL recognized
- ✅ Converted to:
https://www.youtube.com/watch?v=dQw4w9WgXcQ - ✅ Download works normally
- ✅ Video quality matches original
Success Criteria:
- Shorts pattern detected
- URL normalization works
- Download succeeds
Test 9: Vimeo Support (5 min)
Objective: Test Vimeo video downloads.
Steps:
- Paste Vimeo URL:
https://vimeo.com/148751763 - Add and download
Expected Results:
- ✅ Vimeo URL recognized
- ✅ Metadata fetched
- ✅ Download succeeds
- ✅ File plays correctly
Success Criteria:
- Vimeo support working
- Same quality as YouTube workflow
Test 10: Error Handling (10 min)
Objective: Verify graceful error handling.
Test Cases:
A. Invalid URL
Input: https://www.youtube.com/watch?v=invalid123
Expected: Error message "Video unavailable or invalid URL"
B. Private Video
Input: [Private video URL]
Expected: Error message "Video is private"
C. Network Error
- Start download
- Disconnect internet at 50%
- Reconnect after 10 seconds
- Expected: Retry automatically (up to 3 times)
D. Disk Full
- Select directory with insufficient space
- Start large video download
- Expected: Error message "Insufficient disk space"
Success Criteria:
- All errors caught and handled
- User-friendly error messages
- No crashes or hangs
- Retry logic works for network errors
Test 11: UI Responsiveness (5 min)
Objective: Verify UI remains responsive during operations.
Steps:
- Start 8 concurrent downloads
- Try to:
- Scroll video list
- Open settings modal
- Add more videos
- Cancel downloads
- Pause/resume
Expected Results:
- ✅ UI never freezes
- ✅ All controls responsive
- ✅ Smooth scrolling
- ✅ No lag in interactions
- ✅ Progress updates don't cause jank
Success Criteria:
- UI frame rate > 30 FPS
- Interaction latency < 100ms
- No visual glitches
Test 12: Settings Persistence (5 min)
Objective: Verify settings save and load correctly.
Steps:
- Change settings:
- GPU Acceleration: OFF
- Max Concurrent: 6
- Quality: 1080p
- Format: ProRes
- Close application
- Reopen application
- Check settings
Expected Results:
- ✅ All settings preserved
- ✅ GPU setting: OFF
- ✅ Concurrency: 6
- ✅ Quality: 1080p
- ✅ Format: ProRes
Success Criteria:
- Settings persist across sessions
- No data loss
📊 Performance Benchmarks
Track these metrics during testing:
Download Performance
- Single video download time: _______ seconds
- 4 concurrent downloads time: _______ seconds
- 8 concurrent downloads time: _______ seconds
- Speedup vs sequential: _______ x faster
GPU Acceleration
- CPU encoding time: _______ seconds
- GPU encoding time: _______ seconds
- Speedup: _______ x faster
- CPU usage (GPU): _______ %
- CPU usage (CPU): _______ %
System Resources
- Peak CPU usage: _______ %
- Peak memory usage: _______ MB
- Disk I/O: _______ MB/s
- Network speed: _______ MB/s
Stability
- Total downloads tested: _______
- Successful: _______
- Failed: _______
- Success rate: _______ %
🐛 Bug Reporting Template
## Bug Report
**Test:** [Test name]
**Date:** [Date]
**Platform:** [macOS/Windows/Linux + version]
**Build:** [Dev/Prod]
### Description
[Clear description of the bug]
### Steps to Reproduce
1. [Step 1]
2. [Step 2]
3. [Step 3]
### Expected Behavior
[What should happen]
### Actual Behavior
[What actually happened]
### Screenshots/Logs
[Attach screenshots or console logs]
### System Info
- CPU: [Model]
- RAM: [Amount]
- GPU: [Model]
- Network: [Speed]
### Severity
- [ ] Critical (app crashes/data loss)
- [ ] High (feature doesn't work)
- [ ] Medium (feature works but has issues)
- [ ] Low (cosmetic/minor)
✅ Test Completion Checklist
Core Functionality
- Basic single video download
- Concurrent downloads (2, 4, 8 videos)
- Pause/resume functionality
- Cancel downloads
- Queue management
Advanced Features
- GPU acceleration (vs CPU comparison)
- Playlist downloads (small)
- Playlist downloads (large - optional)
- YouTube Shorts support
- Vimeo support
Quality & Formats
- Different qualities (720p, 1080p, 4K)
- Different formats (MP4, ProRes, DNxHR)
- Audio-only extraction
Edge Cases
- Invalid URLs
- Private videos
- Network interruption recovery
- Disk space errors
- Age-restricted content (with cookies)
Performance
- CPU usage acceptable (< 10% idle, < 50% active)
- Memory usage stable (< 500MB)
- UI remains responsive
- No memory leaks (test for 30+ min)
UI/UX
- Progress reporting accurate
- Speed display correct
- Queue panel updates
- Settings save/load
- Error messages clear and helpful
Cross-Platform (if applicable)
- macOS Intel
- macOS Apple Silicon
- Windows 10/11
- Linux (Ubuntu/Fedora)
📝 Final Sign-Off
Tester: _______________________ Date: _______________________ Build Version: _______________________ Overall Assessment: [ ] Pass / [ ] Pass with issues / [ ] Fail
Notes:
Ready for Production: [ ] Yes / [ ] No / [ ] With fixes
Good luck with testing! 🚀
Remember: The goal is to find issues before users do. Be thorough, document everything, and don't hesitate to test edge cases.