AudioSort/TEST_README.md

AudioSort Test Suite

Comprehensive test suite for AudioSort application using real WAV files with embedded metadata.

Running Tests

Run all tests

npm test

Run specific test suites

# Tag Service tests (metadata read/write)
npm run test:tag

# Library Service tests (scanning, organizing, file operations)
npm run test:library

# Search Service tests (fuzzy search, filters)
node --import tsx --test src/test/SearchService.test.ts

Run individual test files

node --import tsx --test src/test/DatabaseService.test.ts
node --import tsx --test src/test/TagService.test.ts
node --import tsx --test src/test/LibraryService.test.ts
node --import tsx --test src/test/SearchService.test.ts

Test Coverage

DatabaseService Tests (20+ tests)

• File Management: upsertFile, listFiles, getFileById, updateFileLocation, deleteFile
• Tagging Operations: updateTagging, updateCustomName
• Category Management: upsertCategory, getCategoryById, listCategories
• Duplicate Detection: listDuplicateGroups by checksum
• Settings Persistence: setSetting, getSettings
• Edge cases: Missing files, null values, duplicate checksums

TagService Tests (14 tests)

• readMetadata: Reading author, copyright, title, rating from WAV files
• writeMetadataOnly: Writing metadata to WAV INFO chunks
• applyTagging: Updating tags/categories in database and WAV files
• Edge cases: Missing metadata, corrupted files, empty values, normalization

LibraryService Tests (20+ tests)

• scanLibrary: File discovery, metadata extraction, temp file cleanup
• listFiles: File listing with metadata
• renameFile: File renaming on disk and in database
• moveFile: Moving files between directories
• updateCustomName: Custom name management
• updateFileMetadata: Metadata updates without organizing
• readFileMetadata: Reading embedded WAV metadata
• listMetadataSuggestions: Aggregating author/copyright suggestions
• deleteFiles: File deletion from disk and database
• cleanupTempFiles: Orphaned temp file recovery

SearchService Tests (13 tests)

• search: Fuzzy search by filename, tags, path
• Advanced filters: author:, copyright: field-specific searches
• Metadata caching: Performance optimization
• rebuildIndex: Index updates after database changes
• Edge cases: Empty queries, typos, no matches

Test Data

Tests use the TestWavGenerator class to create real WAV files with:

• Configurable duration, sample rate, bit depth
• Embedded metadata (author, copyright, title, rating)
• Tags and UCS categories
• Sine wave audio data (440 Hz)

Example test file creation:

await TestWavGenerator.writeTestWav('test.wav', {
  duration: 1,
  sampleRate: 44100,
  bitDepth: 16,
  author: 'Test Author',
  copyright: 'Test Copyright',
  title: 'Test Title',
  rating: 3,
  tags: ['test', 'audio'],
  categories: ['AMBNatr']
});

Test Isolation

Each test suite:

1. Creates temporary database and library directories
2. Generates fresh test WAV files
3. Initializes services with isolated instances
4. Cleans up all resources after tests complete

Temporary files are created in test-data/ and automatically removed.

Testing Strategy

Unit Tests

• Test individual service methods in isolation
• Verify correct behavior with valid inputs
• Handle edge cases and error conditions

Integration Tests

• Test interactions between services (LibraryService + TagService + SearchService)
• Verify database updates reflect in search results
• Ensure file system operations complete successfully

Real Data Tests

• Use actual WAV files with embedded metadata
• Test metadata round-trip (write then read)
• Verify file integrity after operations

Extending Tests

Adding New Test Cases

1. For TagService:

it('should handle new metadata field', () => {
  tagService.writeMetadataOnly(testFilePath, {
    tags: [],
    categories: [],
    newField: 'value'
  });
  
  const metadata = tagService.readMetadata(testFilePath);
  assert.strictEqual(metadata.newField, 'value');
});

2. For LibraryService:

it('should handle new operation', async () => {
  await libraryService.scanLibrary();
  const files = libraryService.listFiles();
  
  // Perform operation
  await libraryService.newOperation(files[0].id);
  
  // Verify results
  const updated = libraryService.listFiles();
  assert.ok(/* verification */);
});

3. For SearchService:

it('should support new filter', () => {
  const results = searchService.search('newfilter:value');
  
  assert.ok(results.length > 0);
  assert.ok(/* filter applied correctly */);
});

Troubleshooting

Tests hang or timeout

• Check for leaked file handles (ensure database.close() in afterEach)
• Verify temp files are being cleaned up
• Increase test timeout if needed

File not found errors

• Ensure library path is created before writing test files
• Check file paths use correct separators for OS
• Verify temp directory permissions

Metadata not persisting

• Confirm WAV file format is correct (use WaveFile library)
• Check INFO chunk tags are supported
• Verify file is written to disk before reading

Search tests fail

• Rebuild search index after database changes
• Clear metadata cache when needed
• Check Fuse.js scoring thresholds

Performance Considerations

• Tests create real WAV files (may be slower than mocks)
• Each test suite runs independently with fresh data
• Cleanup operations ensure no disk space accumulation
• Test data directory can be cleared manually if needed: rm -rf test-data

CI/CD Integration

Tests can be run in CI/CD pipelines:

# GitHub Actions example
- name: Run tests
  run: npm test

Tests require:

• Node.js 18+ (for node:test runner)
• File system write access
• Sufficient disk space for test WAV files (~1-2 MB per test run)

Debugging Tests

Enable verbose output:

NODE_OPTIONS='--test-reporter=spec' npm test

Run specific test:

node --import tsx --test --test-name-pattern="should read author" src/test/TagService.test.ts

Debug with inspector:

node --import tsx --test --inspect-brk src/test/TagService.test.ts