85 lines
2.4 KiB
Markdown
85 lines
2.4 KiB
Markdown
# Debugging the Spelling Practice App
|
|
|
|
This document provides guidance on debugging and testing the app's data handling functionality.
|
|
|
|
## Testing Tools
|
|
|
|
### 1. API Test Page
|
|
|
|
A user-friendly interface for testing the API endpoints:
|
|
|
|
- **URL**: http://localhost:3000/api-test.html
|
|
- **Features**:
|
|
- Test the `/getResults` endpoint to retrieve session data
|
|
- Create and save new test sessions with customizable parameters
|
|
- View session details for specific users
|
|
|
|
### 2. Test Script
|
|
|
|
A Node.js script to verify the saveResults endpoint functionality:
|
|
|
|
```bash
|
|
node test-save-results.js
|
|
```
|
|
|
|
This script:
|
|
1. Verifies the server is running
|
|
2. Creates a test session for "testuser"
|
|
3. Validates the session was saved correctly
|
|
4. Shows summary information about the saved session
|
|
|
|
## Common Issues
|
|
|
|
### File Access Issues
|
|
|
|
If you're experiencing issues with data storage or retrieval:
|
|
|
|
1. **Check file permissions**:
|
|
- Make sure the `data` directory is writable by the Node.js process
|
|
- In Docker environments, ensure volume mounts are set up correctly
|
|
|
|
2. **Verify file formats**:
|
|
- The app expects JSON files in a specific format
|
|
- If manually editing files, validate the JSON structure before restarting
|
|
|
|
3. **Inspect server logs**:
|
|
- The server outputs detailed logs with emoji indicators
|
|
- Look for error messages marked with ❌
|
|
|
|
### Session Data Troubleshooting
|
|
|
|
If sessions aren't appearing correctly:
|
|
|
|
1. **Format compatibility**:
|
|
- The app supports multiple data formats for backward compatibility
|
|
- Session data may use either `timestamp` or `date` fields
|
|
- Word data may be in `answers` or `words` arrays
|
|
|
|
2. **Data verification flow**:
|
|
- Save a session using the API test page
|
|
- Check the response from the `/saveResults` endpoint
|
|
- Verify data using the `/getResults` endpoint
|
|
- Confirm it appears in the UI
|
|
|
|
## Server Recovery
|
|
|
|
If the server stops working:
|
|
|
|
1. **Restart the server**:
|
|
```bash
|
|
node server.js
|
|
```
|
|
|
|
2. **Check for errors in the logs**
|
|
|
|
3. **Data integrity check**:
|
|
- Inspect JSON files in the `data` directory for formatting issues
|
|
- Restore from backups or seed files if needed
|
|
|
|
## Recent Fixes
|
|
|
|
- Added backup data display when `results.json` can't be read
|
|
- Improved error handling in saveResults endpoint
|
|
- Created helper functions to handle different session data formats
|
|
- Added SVG clipping paths to fix analytics graph display issues
|