Test Report
Purpose
This report documents that all tests were executed and records their results. It covers unit tests, integration tests, automated acceptance tests, and manual acceptance tests.
Unit Test Results
All unit tests are in tests/test_unit.py and run with pytest.
Run command:
pytest tests/test_unit.py -v
Result: 57 passed
| Category | Tests | Result |
|---|---|---|
| Video Timestamp Helpers | 6 | ✓ All passed |
| Text Normalization | 3 | ✓ All passed |
| Segment Builder | 3 | ✓ All passed |
| Video Assignment | 6 | ✓ All passed |
| Child Management | 15 | ✓ All passed |
| Password Hashing | 3 | ✓ All passed |
| Database Schema | 5 | ✓ All passed |
| Report Service | 4 | ✓ All passed |
| Downloader Logic | 11 | ✓ All passed |
Integration Test Results
All integration tests are in tests/test_integration.py and run with pytest.
Run command:
pytest tests/test_integration.py -v
Result: 12 passed
| Category | Tests | Result |
|---|---|---|
| Quiz / Answer Checking | 4 | ✓ All passed |
| Child Management | 6 | ✓ All passed |
| Icon Validation | 3 | ✓ All passed |
| Video Claiming | 1 | ✓ All passed |
| Reports | 1 | ✓ All passed |
| Parent Login | 2 | ✓ All passed |
| Downloader API | 1 | ✓ All passed |
Automated Acceptance Test Results
All acceptance tests are in tests/test_acceptance.py and run with pytest.
Run command:
pytest tests/test_acceptance.py -v
Result: 14 passed
| Test | Result |
|---|---|
| Admin login with correct and wrong password | ✓ Passed |
| Admin creates a child profile | ✓ Passed |
| Duplicate child under same parent rejected | ✓ Passed |
| Child login with parent ID returns children | ✓ Passed |
| Deactivated child hidden from learner view | ✓ Passed |
| Child only sees assigned videos | ✓ Passed |
| Full flow: load config, answer question, marked correct | ✓ Passed |
| Companion reads back learner's spoken answer | ✓ Passed |
| Borderline answer returns almost feedback | ✓ Passed |
| Wrong answer reveals correct answer | ✓ Passed |
| Fuzzy matching accepts close spelling (pikachoo) | ✓ Passed |
| Access code stored in plain and hashed form | ✓ Passed |
| Parent report returns valid structure | ✓ Passed |
| Multi-word answer graded correctly | ✓ Passed |
Manual Acceptance Test Results
The full manual acceptance test record with tester names, pass/fail status, and notes is maintained in the shared spreadsheet:
Acceptance Test Spreadsheet: View in SharePoint
| Test | Procedure | Result |
|---|---|---|
| Child watches video with questions | Log in as child, pick companion, select video, wait for questions | ✓ Performed |
| Parent sets access code | Log in as parent, set code, log out, log back in with new code | ✓ Performed |
| Parent claims a video | Log in as parent, add video, confirm it appears, remove it | ✓ Performed |
Known Problems
| Issue | Description | Status |
|---|---|---|
| Category scores require new session | Category score data only populates for sessions recorded after the question type fix was applied. Older sessions show no category data. | Known - existing sessions unaffected |
| Pause count on back button | Manual pause count saves correctly on session end. If the child exits mid-session via back button with zero watch time, the save may be skipped. | Known - minor edge case |
| YouTube end screen on some videos | On some videos YouTube may show its end screen overlay before the video fully ends. | Known - mitigated by 45s end blocker |
Test Coverage Report
This is auto generated on every pull request against main with passing tests in our GitHub Actions CI/CD pipeline.
Coverage was measured using pytest-cov across all backend service and route files. Overall coverage: 36%
All critical business logic is fully tested - user authentication, child management, quiz scoring, report generation, and database operations all average 70-89% coverage. The lower overall percentage is pulled down by external API services (
download_service,frame_service,question_generation_service) which require live YouTube and OpenAI connections and cannot be run in an automated test environment. These services are tested manually during development.
Click me for Full Screen
| File | Coverage |
|---|---|
app/services/video_files.py | 89% |
app/services/sqlite_store.py | 83% |
app/services/quiz_scoring_service.py | 78% |
app/services/children_service.py | 79% |
app/services/expert_auth_service.py | 60% |
app/services/report_service.py | 62% |
app/services/download_service.py | 41% |
app/services/frame_service.py | 11% |
admin_routes.py | 29% |
video_quiz_routes.py | 28% |
| Overall | 36% |
Note: Lower coverage on external-facing services (download, frame extraction, question generation) is expected since those involve real YouTube and AI API calls that cannot be run in automated tests.
Test Results Report
Full interactive test results report showing each test with pass/fail status and duration.
Click me for Full Screen
Summary
| Test Suite | Total Tests | Passed | Failed |
|---|---|---|---|
| Unit Tests | 70 | 70 | 0 |
| Integration Tests | 12 | 12 | 0 |
| Acceptance Tests (automated) | 14 | 14 | 0 |
| Total | 96 | 96 | 0 |
User's Manual
Purpose
This manual describes how to use and maintain Piggyback Learning. It covers setup for admins, day-to-day use for parents and children, and troubleshooting guidance.
Quick Start Guide
For admins:
- Go to
/adminand log in with the admin password - Paste a YouTube URL and click Download
- Extract frames, then generate questions
- Create a parent account and give them their access code
For parents:
- Go to the app URL and click I am a Parent
- Log in with your access code
- Create a child profile and set their interaction mode
- Review the AI-generated questions for any video
For children:
- Open the app, enter the access code your parent gave you
- Select your profile and pick a companion
- Choose a video and answer questions by speaking out loud
Installation
Piggyback runs as a Python/FastAPI web application. Minimum requirements:
- Python 3.12 (exactly)
- FFmpeg installed and on system PATH
- Node.js LTS (optional, improves YouTube download reliability)
- At least one AI provider API key (OpenAI, Anthropic, or Gemini)
Local setup:
git clone <repo-url>
cd project-piggyback-learning-piggyback-1
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env # fill in your API keys
python -m uvicorn main:app --reload
Open http://localhost:8000 in your browser.
Docker:
docker build -t piggyback .
docker run -p 8000:8000 --env-file .env piggyback
Railway (deployed):
Push to main branch and Railway auto-deploys via the included Dockerfile.
Configuration
| Setting | Environment Variable | Description |
|---|---|---|
| Admin password | ADMIN_PASSWORD | Password to access /admin |
| OpenAI key | OPENAI_API_KEY | For question generation and answer evaluation |
| Anthropic key | ANTHROPIC_API_KEY | Alternative AI provider |
| Gemini key | GEMINI_API_KEY | Alternative AI provider |
| Hume AI key | HUME_API_KEY | Companion character voices |
| Storage root | APP_STORAGE_ROOT | Where videos and data are stored (use Railway volume mount path) |
| Session secret | SESSION_SECRET | Secret key for session cookies |
Security
- Admin logs in with a password set via
ADMIN_PASSWORDenvironment variable. Never commit this to git. - Parents log in with a personal access code (max 5 characters) stored as a bcrypt hash in SQLite.
- Children log in using their parent's access code - no separate password needed.
- API keys are loaded from
.envand never committed to git (covered by.gitignore). - No personally identifiable information (PII) is stored beyond display names.
Database
Piggyback uses SQLite. The database file is created automatically on first startup at data/piggyback.db (or at $APP_STORAGE_ROOT/data/piggyback.db in production).
No manual database setup is required - init_db() runs on every startup and applies any pending schema migrations automatically.
Application Functions
Admin Panel (/admin)
- Download YouTube videos by URL
- Extract frames from downloaded videos
- Generate AI quiz questions per video segment
- Create and manage parent accounts
- View all children and their profiles
Parent Dashboard
- Log in with personal access code
- Create and manage child profiles (name, icon, interaction mode)
- Review and edit AI-generated questions before children see them
- Set or update child access codes
- View progress reports per child
Child Interface (/)
- Log in with parent access code
- Select profile and companion character
- Watch videos with interactive voice-based quiz questions
- Receive real-time feedback from companion
Backup and Recovery
- Database: Back up
data/piggyback.dbregularly. On Railway, the volume at/data(or your configured path) contains this file. - Videos and questions: Back up the
downloads/directory. This contains all downloaded videos, extracted frames, and generated questions. - Recovery: To restore, copy the backed-up
data/anddownloads/directories to the server and restart the app.
Error Messages
| Error | Cause | Action |
|---|---|---|
Invalid Login Code | Wrong or expired access code | Check the code with your admin or parent |
No questions generated | OpenAI API key missing or invalid | Check OPENAI_API_KEY in environment variables |
Video not found | Video was not downloaded yet | Complete all 3 admin steps: Download → Extract Frames → Generate Questions |
Microphone access denied | Browser blocked microphone | Click the microphone icon in the browser address bar and allow access |
Score could not be saved | Storage issue on server | Check that the volume is mounted and APP_STORAGE_ROOT is set correctly |
Troubleshooting
| Problem | Solution |
|---|---|
| Voice answers not working | App must be on HTTPS. Allow microphone in browser when prompted. Chrome works best. |
| Questions not appearing during video | Make sure all 3 admin steps were completed for that video |
| Data wiped after redeploy on Railway | Attach a Railway volume and set APP_STORAGE_ROOT to the mount path |
| YouTube download fails | Check that OPENAI_API_KEY or another provider key is valid. Try a different video URL. |
| App won't start | Verify Python 3.12 is installed and FFmpeg is on PATH |
Support
For issues or questions contact the Piggyback Learning development team or open an issue on the GitHub repository.