MangaReader/backend/TEST_README.md

# Integration Tests for MangaReader VPS Backend

This directory contains comprehensive integration tests for the complete VPS flow: iOS app → VPS backend → Storage → Images served back.

## Test Files

### 1. `test-vps-flow.js`
Tests the complete end-to-end flow of downloading and serving manga chapters.

**Test Coverage:**
- Server health check
- Chapter image scraping from source
- Download to VPS storage
- Storage verification
- Image file validation
- Image path retrieval
- Chapter listing
- Storage statistics
- Chapter deletion
- Post-deletion verification
- Storage stats update verification

**Usage:**
```bash
# Make sure the server is running first
node server.js &

# In another terminal, run the test
node test-vps-flow.js
```

**Expected Output:**
- Color-coded test progress
- Detailed assertions with success/failure indicators
- Storage statistics
- Final summary with pass/fail counts

### 2. `test-concurrent-downloads.js`
Tests concurrent download operations to verify thread safety and data integrity.

**Test Coverage:**
- Pre-download cleanup
- Concurrent chapter downloads (5 chapters, max 3 concurrent)
- Post-download verification
- File integrity checks (no corruption, no missing files)
- Manifest independence verification
- Storage statistics accuracy
- Chapter listing functionality
- Concurrent deletion
- Complete cleanup verification
- Race condition detection

**Usage:**
```bash
# Make sure the server is running first
node server.js &

# In another terminal, run the test
node test-concurrent-downloads.js
```

**Expected Output:**
- Progress tracking for each operation
- Batch processing information
- Detailed integrity reports per chapter
- Summary of valid/missing/corrupted images
- Concurrent delete tracking
- Final summary with race condition analysis

## Test Configuration

Both tests use the following configuration:

```javascript
{
  mangaSlug: 'one-piece_1695365223767',
  chapters: [787, 788, 789, 790, 791],  // For concurrent test
  baseUrl: 'http://localhost:3000',
  timeout: 120000-180000  // 2-3 minutes
}
```

You can modify these values in the test files if needed.

## Prerequisites

1. **Dependencies installed:**
   ```bash
   npm install
   ```

2. **Server running on port 3000:**
   ```bash
   node server.js
   ```

3. **Storage directory structure:**
   The tests will automatically create the required storage structure:
   ```
   /storage
     /manga
       /one-piece_1695365223767
         /chapter_789
           page_001.jpg
           page_002.jpg
           ...
           manifest.json
   ```

## Running All Tests

Run both test suites:

```bash
# Terminal 1: Start server
cd /home/ren/ios/MangaReader/backend
node server.js

# Terminal 2: Run VPS flow test
node test-vps-flow.js

# Terminal 3: Run concurrent downloads test
node test-concurrent-downloads.js
```

## Test Results

### Success Indicators
- ✓ Green checkmarks for passing assertions
- 🎉 "ALL TESTS PASSED!" message
- Exit code 0

### Failure Indicators
- ✗ Red X marks for failing assertions
- ❌ "SOME TESTS FAILED" message
- Detailed error messages
- Exit code 1

## Color Codes

The tests use color-coded output for easy reading:
- **Green**: Success/passing assertions
- **Red**: Errors/failing assertions
- **Blue**: Information messages
- **Cyan**: Test titles
- **Yellow**: Warnings
- **Magenta**: Operation tracking (concurrent tests)

## Cleanup

Tests automatically clean up after themselves:
- Delete test chapters from storage
- Remove temporary files
- Reset storage statistics

However, you can manually clean up:

```bash
# Remove all test data
rm -rf /home/ren/ios/MangaReader/storage/manga/one-piece_1695365223767
```

## Troubleshooting

### Server Not Responding
```
Error: Failed to fetch
```
**Solution:** Make sure the server is running on port 3000:
```bash
node server.js
```

### Chapter Already Exists
Tests will automatically clean up existing chapters. If you see warnings, that's normal behavior.

### Timeout Errors
If tests timeout, the scraper might be taking too long. You can:
1. Increase the timeout value in TEST_CONFIG
2. Check your internet connection
3. Verify the source website is accessible

### Port Already in Use
```
Error: listen EADDRINUSE: address already in use :::3000
```
**Solution:** Kill the existing process:
```bash
lsof -ti:3000 | xargs kill -9
```

## Test Coverage Summary

| Feature | VPS Flow Test | Concurrent Test |
|---------|---------------|-----------------|
| Server Health | ✓ | - |
| Image Scraping | ✓ | ✓ |
| Download to Storage | ✓ | ✓ (5 chapters) |
| File Verification | ✓ | ✓ |
| Manifest Validation | ✓ | ✓ |
| Storage Stats | ✓ | ✓ |
| Chapter Listing | ✓ | ✓ |
| Deletion | ✓ | ✓ (concurrent) |
| Race Conditions | - | ✓ |
| Corruption Detection | - | ✓ |

## Integration with CI/CD

These tests can be integrated into a CI/CD pipeline:

```yaml
# Example GitHub Actions workflow
- name: Start Server
  run: node server.js &

- name: Wait for Server
  run: sleep 5

- name: Run VPS Flow Tests
  run: node test-vps-flow.js

- name: Run Concurrent Tests
  run: node test-concurrent-downloads.js
```

## Performance Notes

- **VPS Flow Test**: ~2-3 minutes (downloads 5 images from 1 chapter)
- **Concurrent Test**: ~3-5 minutes (downloads 5 images from 5 chapters with max 3 concurrent)

Times vary based on:
- Network speed to source website
- VPS performance
- Current load on source website

## Contributing

When adding new features:
1. Add corresponding tests in `test-vps-flow.js`
2. If feature involves concurrent operations, add tests in `test-concurrent-downloads.js`
3. Update this README with new test coverage
4. Ensure all tests pass before submitting

## License

Same as the main MangaReader project.