Spaces:
Sleeping
Download docs/HF_SPACE_TESTING.md from jrrribeiro/BirdNET-Validator-App: direct link, hf CLI and curl.
- Browser
- Download file 9.83 kB
-
https://huggingface.co/spaces/jrrribeiro/BirdNET-Validator-App/resolve/main/docs/HF_SPACE_TESTING.md
- Command line
-
hf download hf://spaces/jrrribeiro/BirdNET-Validator-App/docs/HF_SPACE_TESTING.md
-
curl -L -o HF_SPACE_TESTING.md https://huggingface.co/spaces/jrrribeiro/BirdNET-Validator-App/resolve/main/docs/HF_SPACE_TESTING.md
A newer version of the Gradio SDK is available: 6.32.0
BirdNET Validator App - Testing Guide for HF Space
This guide explains how to test the BirdNET Validator application on Hugging Face Spaces.
Quick Overview
The validator is a Gradio application for human review of BirdNET detections. It provides:
- Multi-project login with role-based access
- Detection queue with filtering and pagination
- Audio playback and validation actions
- Concurrency-safe writes with optimistic locking
- Conflict resolution and reporting
Architecture
βββββββββββββββββββββββββββββββββββββββββββββββββββ
β Gradio Web UI (app.py) β
βββββββββββββββββββββββββββββββββββββββββββββββββββ€
β ββ Login Page (auth_service) β
β ββ Admin Panel (admin_panel) β
β ββ Queue Display (detection_queue_service) β
β ββ Audio Player (audio_fetch_service) β
βββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Services & Repositories β
β ββ ValidationService (save/validate/report) β
β ββ DetectionQueueService (filter/paginate) β
β ββ AudioFetchService (download/cache) β
β ββ AppendOnlyValidationRepository (atomic ops) β
βββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Data Sources β
β ββ Projects (bootstrap/config) β
β ββ Users & Access Control β
β ββ Detections (HF dataset or seed file) β
β ββ Validations (local append-only log) β
βββββββββββββββββββββββββββββββββββββββββββββββββββ
Testing on HF Spaces
Step 1: Configure HF Space with Demo Data
- Go to BirdNET-Validator-App Space Settings
- Configure Variables/Secrets:
BIRDNET_ENABLE_DEMO_BOOTSTRAP=true
BIRDNET_PAGE_SIZE=25
These settings will:
- Load built-in demo users:
admin_user,demo_user,validator_demo - Load demo project:
demo-project - Load demo detections: 100 sample birds
Step 2: Access the App
- Go to your HF Space URL
- Wait for the Gradio interface to load
- You should see the login page
Step 3: Test Login
Test user 1 (Admin):
- Username:
admin_user - Expected: Access to all projects with admin role
- Expected UI: "Admin Panel" tab visible
Test user 2 (Validator):
- Username:
demo_user - Expected: Access to demo-project with validator role
- Expected UI: "Admin Panel" tab NOT visible
Test user 3 (Another Validator):
- Username:
validator_demo - Expected: Same access as demo_user
Step 4: Test Core Features
Feature 1: Project Selection
- Login as
admin_user - Click "Select Project"
- Verify:
demo-projectappears in list - Click to select
demo-project - Expected: Queue loads with 100 detections
Feature 2: Detection Queue & Filtering
Verify detections display with:
- Audio ID
- Scientific Name
- Confidence score
- Current validation status
Test filters:
- Filter by Species: Enter scientific name prefix, queue updates
- Filter by Confidence: Set min/max bounds, queue filters
- Search: Type audio ID, rows filtered in real-time
Test pagination:
- Default page size: 25 items
- Click "Next Page" / "Previous Page"
- Verify correct items load
Feature 3: Audio Playback
- Click on a detection row
- Click "Play Selected" button
- Expected: Audio player loads with sample WAV
- Verify audio plays correctly
- Verify sample rate and duration display
Feature 4: Validation Actions
- Select a detection by clicking the row
- Choose validation status:
- β Positive: Species confirmed
- β Negative: False alarm
- ? Uncertain: Unsure
- β Skip: Come back later
- Optional: Add notes in the text field
- Click "Save Validation"
- Expected UI changes:
- Row highlights in green (valid) or yellow (uncertain)
- Status displays in "Validation Status" column
- Validator name appears in "Validated By" column
Feature 5: Batch Validation (Conflicts)
- Simulate conflict: Validate same detection from 2 different users
- In separate browser windows:
- Window 1: Login as
admin_user - Window 2: Login as
demo_user
- Window 1: Login as
- Both validate the same detection differently
- In separate browser windows:
- Window 2 should show: "Optimistic lock conflict"
- Click "Reapply my validation" to override
- Expected: Validation saved, conflict row marked
Feature 6: Admin Panel (Admin Only)
Login as
admin_userClick "Admin Panel" tab
Verify options:
- View validation report
- Create invites
- Manage user roles
- View audit logs
Click "Validation Report"
Expected: Shows statistics:
- Total validations
- Breakdown by validator
- Breakdown by status
- Last updated time
Keyboard Shortcuts (if enabled)
Press '?' in the app to see shortcuts:
P: Positive validationN: Negative validationU: Uncertain validationS: Skip detectionβ: Next pageβ: Previous page?: Show this help
Data Flow During Test
User logs in
- Auth service validates credentials
- RuntimeConfig loads projects and user access
- Dashboard loads project list
User selects project
- DetectionQueueService loads first page (25 items)
- Each detection loads from in-memory repository
User clicks on detection
- AudioFetchService fetches from HF dataset
- Audio cached in ephemeral memory
- Audio player displays WAV
User validates
- ValidationService creates validation event
- AppendOnlyValidationRepository appends to log
- Optimistic locking prevents conflicts
- UI updates with new status
Expected Test Results
β All should pass:
- Login with
admin_usersucceeds - Login with
demo_usersucceeds - Project selection loads demo-project
- Queue displays 100 detections
- Filters reduce queue size
- Audio playback works
- Positive/Negative/Uncertain/Skip actions work
- Validation status updates in real-time
- Pagination works (next/prev page)
- Notes are saved with validation
- Admin panel visible for
admin_user - Validation report shows correct stats
- Multiple concurrent validations don't lose data
- Conflict resolution works
Troubleshooting
"Loading..." spinner stuck
Cause: Audio fetch service timeout or missing audio
Solution:
- Check HF dataset is accessible
- Verify
BIRDNET_DETECTIONS_FILEis set correctly - Check browser console for errors
"Optimistic lock conflict" on first validation
Cause: Concurrent writes detected (expected in conflict test)
Solution:
- Click "Reapply my validation" to override
- Or click "Discard" to cancel
"Project not found"
Cause: Bootstrap didn't load projects
Solution:
- Ensure
BIRDNET_ENABLE_DEMO_BOOTSTRAP=true - Or provide
BIRDNET_PROJECTS_FILEpointing to valid JSON - Check Space logs for errors
Audio player blank
Cause: Missing audio or fetch service error
Solution:
- Verify HF dataset has audio files
- Check
BIRDNET_DETECTIONS_FILEpoints to valid detection JSON - Verify audio file paths in detection data
Local Testing Before HF
To test locally before deploying to HF:
# Test with demo bootstrap
export BIRDNET_ENABLE_DEMO_BOOTSTRAP=true
export BIRDNET_PAGE_SIZE=25
python app.py
# Open browser to http://localhost:7860
Then follow the testing steps above.
Performance Expectations
- Login: < 1 second
- Project load: < 2 seconds
- Queue page load: < 1 second
- Audio fetch: 2-5 seconds (depends on file size)
- Validation save: < 1 second
- Pagination: < 1 second
Next Steps After Testing
- β Confirm all features work locally
- β Push to HF Space
- β Test on HF Space URL
- β Configure production data (real projects/users/detections)
- β Set up invite email (optional, requires EmailJS)
- β Share HF Space URL with validators
Files Reference
Main entry point:
app.py- Starts Gradio server
UI Components:
src/ui/app_factory.py- Creates Gradio interfacesrc/ui/login_page.py- Login formsrc/ui/admin_panel.py- Admin panel UI
Services:
src/services/validation_service.py- Validation logicsrc/services/detection_queue_service.py- Queue filtering/paginationsrc/services/audio_fetch_service.py- Audio download/cachingsrc/auth/auth_service.py- Authentication
Data:
src/repositories/append_only_validation_repository.py- Write validation eventssrc/repositories/in_memory_detection_repository.py- Read detectionssrc/config/runtime_config.py- Configuration from env varssrc/cache/ephemeral_cache_manager.py- Temporary audio cache
Security Notes
- Tokens are validated against Hugging Face API
- Each user needs
readaccess to the detection dataset - Each user needs
writeaccess to create validations - Admin users can manage invites and ACLs
- All writes are append-only (immutable audit log)
Questions or Issues?
Check:
- HF Space logs (Settings > Logs)
- Browser console (F12 > Console)
- README.md for configuration details
- app_factory.py for initialization code